Thruway Common Laravel Package

Technical Evaluation

• Architecture fit: Unchanged. ThruwayCommon is not an application-facing library. It is the shared kernel of WAMP2 protocol primitives — message classes, URI validation, error hierarchies, payload handling — consumed by voryx/thruway (the router) and the Thruway client. It fits only if you have already committed to WAMP2 as your messaging model and to ReactPHP as your concurrency model. For a typical Laravel stack that fit is weak: Laravel is request/response-centric, and real-time needs are conventionally served by broadcasting (Reverb, Soketi, Pusher), Mercure, or plain WebSockets via Ratchet. WAMP2's genuine value — unified RPC and PubSub with broker/dealer roles over one connection, cross-language clients — is real, but the PHP ecosystem around it is thin.

• Integration feasibility: Unchanged in substance. Requiring voryx/thruway-common directly in composer.json is technically trivial (pure PHP, PSR-4, no extensions) but functionally pointless — you would acquire protocol value objects without the router or client that give them meaning. Genuine integration means pulling voryx/thruway or thruway/client, which drags this package in transitively, and that means adopting ReactPHP and running a long-lived process outside PHP-FPM's lifecycle. That is an architectural decision, not a library selection. The one thing 1.0.6 improves: the package now declares a PHP requirement, so an incompatible runtime fails at composer update rather than at boot.

• Technical risk: Still high relative to delivered value, but marginally improved. Release 1.0.6 adds a PHP version constraint and a return type on jsonSerialize for PHP 8.1 — housekeeping that confirms someone is tending the PHP 8.x compatibility surface, which is the specific drift risk called out previously. It does not change the structural picture: single maintainer, low visibility, no evident security-response process. Two new considerations follow from the patch itself. First, if the newly declared constraint raises the PHP floor to ^8.0/^8.1 (a mixed return type requires 8.0+), consumers still on PHP 7.4 are silently cut off — that is a breaking change for them, shipped in a patch version. Second, adding a return type to an inherited interface method is a source-compatibility break for any downstream subclass that overrides jsonSerialize without a matching declaration. Both are low-probability for our usage but should be verified, not assumed.

• Key questions:

  1. Are we integrating ThruwayCommon directly (almost certainly the wrong move) or adopting WAMP2 wholesale via Thruway?
  2. Does anything else in the stack already pull ReactPHP, and at which major version?
  3. Is the requirement genuinely RPC-shaped, or PubSub-shaped, or merely "push updates to the browser"? Only the first two justify WAMP2.
  4. Can we operate and supervise a persistent PHP worker (Supervisor/systemd) alongside FPM, with health checks and drain-on-deploy?
  5. What is the exit cost if upstream stalls — is the protocol boundary clean enough to swap in Crossbar or a Node/Go router without touching client code?
  6. New: what PHP floor does 1.0.6 declare, does it move from 7.4 to 8.x, and does that conflict with any application or CI runtime we still support?
  7. New: do we — or any transitive dependency — subclass ThruwayCommon's message classes or otherwise override jsonSerialize? If so, the return-type addition in 1.0.6 is a fatal-error risk on upgrade.

Integration Approach

• Stack fit: Unchanged. ThruwayCommon ships no Laravel coupling — no service provider, no config, no facade, no contracts. That is neutral rather than positive: zero framework ergonomics, and you write the wiring yourself. If WAMP2 is genuinely required, the pragmatic shape is a standalone router process (Thruway or Crossbar) under supervision, a thin client wrapper inside Laravel that publishes and subscribes, and Laravel's event system fanning out to that wrapper. Keep WAMP at the edge; do not thread it through domain code.

• Migration path: Unchanged. Do not migrate toward this package. If WAMP2 is a live requirement, the migration is from nothing to "router plus clients," and effort is dominated by router deployment, not by ThruwayCommon. If you are already on Thruway and hitting version conflicts, the likelier trajectory is migration away — toward Mercure (HTTP/SSE, Laravel-friendly) or Reverb/Soketi (native broadcasting). Both preserve the pub/sub semantics you would actually be exercising.

• Compatibility: The 1.0.6 notes change the checklist but not the conclusion. Confirm the newly declared PHP constraint and whether it raises the floor; confirm the ReactPHP event-loop major pinned by the parent Thruway release; verify PSR-7 implementation compatibility, since Thruway message objects interoperate with psr/http-message and mixing PSR-7 v1 and v2 implementations is a classic source of runtime type errors; confirm the serializer you need (JSON vs MsgPack) is present and the MsgPack extension is installed if used. Add one check specific to this release: grep the dependency tree for subclasses of the message classes that override jsonSerialize, because the new return type will fail at class-load time rather than in tests.

• Sequencing:

  1. Requirements pass — confirm RPC/PubSub semantics are actually needed, and document why broadcasting is insufficient.
  2. Timeboxed spike — stand up a Thruway router in a container, connect two clients, prove an RPC round-trip and a pub/sub fan-out.
  3. Dependency audit — composer why react/*, check the event-loop major, check for PSR-7 conflicts, and read the new PHP constraint against our supported runtime matrix.
  4. Decide: adopt, or fall back to Laravel-native broadcasting or Mercure.

Operational Impact

• Maintenance: Still effectively self-maintained, with a caveat softened. A single housekeeping release after a long quiet period is evidence the package is alive, not evidence of velocity — budget for vendor-patching or forking for PHP and ReactPHP compatibility as a recurring cost, not a one-time one. Treat releases as sporadic and non-semantic: 1.0.6 shipped a potential PHP-floor raise and a subclass-breaking signature change inside a patch version, so pin exactly and review diffs before bumping rather than relying on caret ranges.

• Support: Unchanged. No commercial backing, no active issue triage, minimal community. Knowledge concentrates in the small set of people who have run Thruway in production. Internal runbooks and documentation are mandatory rather than optional. The WAMP2 spec being well-documented and stable partially offsets this — wire-level debugging is feasible with any conformant client.

• Scaling: Unchanged. WAMP routing is stateful and connection-oriented. Scaling means scaling the router tier: sticky sessions or a router cluster with a shared broker, plus a message bus for cross-node fan-out. Thruway's router is single-process ReactPHP — vertical scaling and process-per-core sharding, not out-of-the-box horizontal elasticity. For a Laravel app with modest real-time needs this is over-engineering; at high fan-out it becomes the bottleneck nobody budgeted for.

• Failure modes: (a) the persistent worker dies silently under FPM-style supervision assumptions — requires Supervisor/systemd with restart policy and liveness checks; (b) event-loop starvation from a synchronous blocking call inside a handler, which stalls every subscription on that process; (c) unbounded memory growth in long-lived processes from accumulating subscription maps or listeners; (d) connection storms on deploy without graceful drain; (e) PSR-7 or ReactPHP version skew producing fatal type errors at boot rather than in tests; (f) new: a PHP floor raise or the jsonSerialize return-type addition breaking at class-load time on upgrade — mitigated by pinning to an exact version and validating in a staging boot before rollout.

• Ramp-up: Unchanged. Moderate to high for a Laravel team. The unfamiliar territory is the WAMP2 role model (broker/dealer, realms, sessions), ReactPHP's non-blocking discipline, and operating persistent PHP processes. ThruwayCommon's own API surface is small and readable — a day of reading. The operational model is the real onboarding cost: realistically two to four weeks before a team is confident running this in production.