Websocket Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: Still PHP-native and a clean fit for Laravel’s event-driven and DI patterns. v4 does not change the fundamental integration story — it changes the surface area your code touches (exceptions, connection accessors, HTTP message plumbing).
• Use Cases: Unchanged. Server-side broadcasting via laravel-websockets-style implementations or custom endpoints; client-side consumption in jobs/queues.
• Middleware Support: CloseHandler, PingResponder, and DeflateCompression remain the extension points. Behavioural change: compression failures now raise MessageEncodingException rather than surfacing as a silent/ambiguous encoding fault — this must be handled explicitly inside the middleware chain or it will bubble into the connection loop.
• PSR Alignment: Stronger than v3. The package now uses Nyholm PSR HTTP directly and drops its internal stub classes, so a single, well-maintained PSR-7 implementation serves both Laravel and the WebSocket layer. This is architecturally cleaner but converts an internal implementation detail into a hard Composer dependency.

Integration Feasibility

• Laravel Service Provider: Still viable, but the provider is the primary blast radius. v4 changes how Client and Server are configured — every constructor/options array assembled in the provider or config/websockets.php needs review against the v3→v4 migration guide.
• Event-Driven Workflow: Server::onText() → Laravel events is unaffected. Connection enumeration is affected: getConnections() now returns a Connections collection instead of an array.
• PSR Standards: Nyholm is already present in most Laravel stacks, which lowers the cost of adoption — provided version constraints resolve (see Technical Risk).

Technical Risk

• BREAKING RELEASE — primary risk. v4 removes deprecated code and reworks the exception hierarchy and Client/Server configuration. This is not a drop-in upgrade from 3.x.
• Version pinning: The prior assessment recommended pinning ~3.7. That guidance must now be split: ~3.8 (or ^3.7) for teams not yet migrated, ^4.0 only after a completed migration. Do not allow a floating constraint across the 3→4 boundary.
• Dependency resolution: Moving from internal stubs to a direct Nyholm dependency introduces a real possibility of a Composer conflict with the nyholm/psr7 version pinned by your Laravel framework release. Must be verified with composer why-not nyholm/psr7 before committing to v4.
• Exception hierarchy: Renamed/restructured exception classes will silently break existing catch blocks — a catch (WebSocket\Exception\...) that no longer matches will let failures escape to Laravel’s global handler and, in a server context, potentially terminate the connection loop.
• getConnections() type change: Any code doing array_filter, array_map, count() semantics, or type-hinting array will fail at runtime, not at static analysis time unless typed strictly.
• PHP version support: v3 was documented at PHP 8.5+/Laravel 10+. v4’s floor is not stated in the release notes and must be confirmed from composer.json before it is assumed unchanged.

Key Questions

1. Migration window: What is the v3 support/EOL timeline? Is 3.8.x receiving security fixes, or is v4 the only supported line?
2. Blast radius: Which of our integrations touch Client/Server configuration directly vs. only the high-level send/receive API? The former determines effort.
3. Dependency conflict: Does v4’s direct Nyholm dependency resolve against our current laravel/framework and nyholm/psr7 versions?
4. Exception mapping: Which new v4 exception classes must be mapped into Laravel’s Handler::$dontReport and our alerting rules?
5. Compression policy: Do we use Deflate at all? If not, MessageEncodingException is a non-event; if yes, it is a new failure path requiring handling.
6. Connection scale: At our peak connection count, is the Connections collection materially heavier than the prior array for per-tick enumeration?
7. Server vs. client scope: Is this replacing Laravel Echo/Pusher or augmenting it? (Unchanged from prior assessment — still unanswered.)

Integration Approach

Stack Fit

• Laravel Ecosystem: No change to the recommended placement — server via a long-running Artisan command, client inside jobs/queues.
• Dependencies (materially changed):
  • nyholm/psr7 / Nyholm PSR HTTP is now a direct dependency rather than an internal stub. Resolution against the framework’s pinned version is the first gate.
  • phrity/net-stream remains low-level and non-conflicting.
• Tooling: php artisan websocket:start and a Route::websocket() macro remain valid. Add a migration diagnostic command (e.g. websocket:diagnose) that reports pinned version, resolved Nyholm version, and any configured options keys that no longer exist in v4 — this pays for itself during rollout.

Migration Path

1. Freeze and inventory: Pin ~3.8 repo-wide to stop accidental 3→4 drift. Inventory every Client/Server construction site, every catch on a WebSocket exception, and every consumer of getConnections().
2. Dependency pre-flight: Resolve v4 in a throwaway branch. Confirm Nyholm and PHP floor compatibility and record the exact conflict set (if any).
3. Pilot (non-critical path): Migrate one client-side integration — typically an outbound notification sender in a queued job — to v4. Rewrite config mapping and exception handling here first.
4. Collection refactor: Convert getConnections() consumers from array semantics to iterable/collection semantics. This is mechanical but easy to miss.
5. Server migration: Apply the same config and exception changes to the server bootstrap and middleware chain, including MessageEncodingException handling in DeflateCompression.
6. Constraint flip: Move composer.json to ^4.0, delete the temporary pin, and remove any v3 compatibility shims.

Compatibility

• Laravel 10+: Expected to remain compatible, contingent on the Nyholm version resolution check.
• Legacy Laravel: Likely worse than v3 here — v4’s removal of internal stub classes reduces the package’s ability to paper over older PSR-7 versions. Treat sub-Laravel-10 as unsupported for v4.
• Coexistence: v3 and v4 can live in different services, but not different packages within one Laravel app. A monorepo with shared internal packages must migrate atomically or split the dependency.

Sequencing

1. Phase 0 — Contain: Pin ~3.8, open a migration epic, assign an owner, capture the v3 EOL answer.
2. Phase 1 — Client: Migrate client usage and configuration; establish the new exception-handling pattern.
3. Phase 2 — Collection semantics: Refactor getConnections() consumers ahead of the server cutover.
4. Phase 3 — Server: Migrate server bootstrap, middleware, and compression error handling.
5. Phase 4 — Constraint flip and cleanup: ^4.0, remove shims, close the epic.

Operational Impact

Maintenance

• Version policy: Two-track pinning for the migration window (~3.8 legacy, ^4.0 migrated). Enforce via a Composer constraint check in CI so a transitive bump cannot cross the major boundary unnoticed.
• Upstream cadence: v4 is a fresh major with four PRs in the initial tag (#162–#165); expect follow-up patch churn on the new exception and Nyholm paths. Budget for at least one point release before treating v4 as fully stable.
• Logging: Unchanged — funnel through Laravel’s Log facade. Update log-parsing rules to recognise the new exception class names.
• Third-party dependencies: The Nyholm dependency is now visible to your dependency audit and security scanning; previously it was opaque inside the package.

Support

• Error handling: The single highest-value operational task. Rebuild the exception-to-handler mapping against v4’s hierarchy and explicitly decide, per exception class, whether it is reported, retried, or swallowed. Unmapped exceptions in a long-running server process are the difference between a degraded connection and a dead worker.
• Alerting: MessageEncodingException deserves its own alert — it indicates message corruption on the wire, which is a signal worth page-worthy attention rather than a generic error counter increment.
• Debugging: onError() hooks and Telescope integration carry over. Telescope’s exception capture will group on the new class names, so historical dashboards will look discontinuous across the migration — annotate deploys.
• Runbook: Add a "WebSocket dependency version" section so on-call can identify which major a given environment is running without reading composer.lock.

Scaling

• Horizontal: Unchanged — load balancer plus Redis for shared state remains the pattern.
• Vertical: Unchanged — worker processes via pcntl_fork.
• Connection enumeration: The getConnections() return-type change has a mild but real scaling implication. If you broadcast by iterating all connections on a timer, measure the collection’s per-tick cost at peak connection count against the previous array implementation. Iteration is fine; if the collection is rebuilt per call, per-tick allocation grows with connection count.
• Resource limits: setMaxConnections() guidance stands; re-verify the option key against v4’s configuration surface.

Failure Modes

Ramp-Up

• Reading requirement: The v3→v4 migration guide is mandatory pre-read for anyone touching the integration, not optional background.
• Documentation: Publish an internal one-pager covering the three things that actually break — Client/Server configuration, exception hierarchy, getConnections() type. Laravel-specific examples (middleware wiring, provider config) still need writing.
• Training: Onboard devs on the new exception tree specifically, since that is the part that fails quietly rather than loudly. Existing WebSocket lifecycle training (onOpen/onClose) carries over unchanged.
• Tooling: php artisan tinker for interactive client testing and a health check on the up command remain valid; add the websocket:diagnose command described above so version/config drift is visible at a glance.