Thruway Common Laravel Package

Getting Started

• Treat voryx/thruway-common as a protocol building block, not an application package. In most Laravel apps you will get it transitively via voryx/thruway; install it directly only if you are writing custom WAMP message handling, serializers, or tests against WAMP frames.

  composer require voryx/thruway-common
  

• Look first under vendor/voryx/thruway-common/src/:
  • Message/ — WAMP message classes and message-code mapping. Start with the base Message class and Message::createMessageFromArray().
  • Role/ — WAMP role definitions (Caller, Callee, Publisher, Subscriber) and role feature negotiation.
  • Serializer/ — JSON/MsgPack serialization helpers when present in your installed version.
  • Logging/ — shared logger wiring used by Thruway components.
• First practical use case: decode a captured WAMP frame in a Laravel command or test so you can see exactly what the router/client exchanged before wiring it into application code.

  use Thruway\Message\Message;
  
  $parts = json_decode($rawWampFrame, true);
  $message = Message::createMessageFromArray($parts);
  
  dump(get_class($message), $message->getMessageParts());
  

• If you are building the actual integration, install/use voryx/thruway for the connection/session/client layer, then use this package’s message and role classes when you need to inspect, test, or customize behavior.

Implementation Patterns

• Wrap Thruway client setup in a Laravel service provider and bind a configured connection/session as a singleton. Keep WAMP config in config/wamp.php with realm, router URL, auth, and reconnect settings.
• Use a long-running Artisan command for the WAMP worker rather than opening WAMP connections from HTTP requests. Dispatch Laravel events/jobs from WAMP callbacks, and keep the worker under Supervisor.
• For RPC, register procedures through the Thruway client session, then validate incoming arguments and return plain serializable values. Use common message classes in tests to assert the expected CallMessage, ResultMessage, or ErrorMessage payloads.
• For pub/sub, map WAMP topics to Laravel events or listeners. Use the common PublishMessage/EventMessage classes when testing or when building a custom router-side component, but let the client session handle normal subscribe/publish flows.
• If you need custom serialization, implement the Thruway serializer contract and register it consistently on both client and router. JSON is easiest to debug; MsgPack is better for binary/large payloads but harder to inspect.
• Use Message::createMessageFromArray() heavily in unit tests. It lets you build realistic WAMP frames without a live router, which is useful for testing Laravel listeners, exception mapping, and auth failures.
• Treat role classes as protocol metadata. When checking a router’s WelcomeMessage, use the role definitions to verify that caller/callee/publisher/subscriber features match what your client expects.
• Keep WAMP callbacks thin: translate WAMP arguments into DTOs, dispatch Laravel jobs/events, and avoid doing heavy work inside the socket read loop.

Gotchas and Tips

• This is not a Laravel package. There is no service provider, facade, config file, or published migrations. You must wire logging, config, connection lifecycle, and error handling yourself.
• Version alignment matters. voryx/thruway-common and voryx/thruway share the Thruway\ namespace; mismatched versions can produce confusing class/API differences. Check with:

  composer show voryx/thruway-common
  composer why voryx/thruway-common
  

• PHP version is now an explicit Composer requirement (added in 1.0.6), and jsonSerialize has a proper return type as of 1.0.6 for PHP 8.1+. If you were previously suppressing deprecation notices from the serializer on PHP 8.1+, upgrading removes those. Confirm the resolver picks 1.0.6+ before relying on that behavior.
• WAMP messages are positional arrays. Do not reorder message parts. Empty dictionaries and empty lists are not interchangeable in WAMP JSON: PHP’s empty array often serializes as [], while WAMP expects {} for empty dicts. Use new \stdClass() or explicit JSON handling where the spec requires an object.
• Message type codes are numeric and protocol-defined. Debug by dumping the raw parts and the resolved message class:

  dump($message->getMessageParts());
  dump(get_class($message));
  

• Request IDs must be unique per session. The common message classes do not manage session state for you; the client/session layer does. If you hand-build messages, track IDs carefully.
• ErrorMessage is not a normal exception. It carries a WAMP error URI and arguments. Map these to domain exceptions in your Laravel integration instead of letting them leak into application code.
• The package is low-activity; the latest release (1.0.6) is a small compatibility/maintenance update rather than a feature or behavior change. Treat it as stable protocol plumbing, not an actively evolving Laravel dependency. Test on your target PHP version, especially PHP 8.2+.
• Logging is easy to miss. Configure the Thruway logger early in the worker bootstrap; otherwise connection and protocol failures can be silent or hard to trace.
• Long-running WAMP workers need reconnect/backoff, ping/pong handling, and memory monitoring. The common library provides messages and roles, not connection supervision.
• Extension points are usually serializers, transports, and application-level message handling. Avoid inventing custom WAMP messages unless you control both peers; WAMP’s core message set is fixed.
• For debugging, compare against the WAMP spec and router logs (e.g., Crossbar). Most integration bugs are malformed message parts, wrong realm/auth details, or an unexpected role feature negotiation.