Pawl Laravel Package

Getting Started

Begin by installing the package: composer require ratchet/pawl. The primary entry points are the Connector class (for full control) and the convenience static connect() helper (a wrapper around Connector). Start with the minimal use case from the README: connect to a public echo server, send a message, receive it back, and exit. This validates your environment and confirms async event loop functionality. Next, read the Classes section to understand Connector, WebSocket, and MessageInterface. Ensure you’re using PHP 7.4+, and verify ReactPHP’s event loop integration—Pawl uses the default loop unless you inject a custom one.

Implementation Patterns

• Standalone CLI Scripts: Ideal for real-time data ingestion (e.g., stock tickers, IoT data). Use Loop::run() to keep the process alive and attach message/close handlers for stateful interaction.
• Reactor-Aware Services: In ReactPHP-based backends (e.g., Swoole workers or custom daemons), inject a shared React\Socket\Connector into Connector to configure DNS, timeouts, and TLS—enabling robust, production-grade client behavior.
• Subprotocol Integration: Negotiate subprotocols like graphql-ws or vnd.api+json during handshake to consume structured WebSocket APIs (e.g., Apollo subscriptions).
• Batch Connection Management: Reuse a single Connector instance to manage many concurrent connections—e.g., fan-out notifications across multiple external services—without blocking PHP’s main thread.
• Authentication Flows: Pass custom headers (e.g., Authorization: Bearer ...) during connection to authenticate with secured WebSocket endpoints.

Gotchas and Tips

• Loop Isolation: Injecting a custom event loop is safe only if it matches the one used by your app. In Laravel, avoid injecting loops in web requests—run Pawl exclusively in long-lived CLI commands or workers.
• TLS Validation: For wss:// connections, configure TLS options (e.g., verify_peer) via the injected React\Socket\Connector. Never disable verification in production.
• Resource Cleanup: Always close connections explicitly ($conn->close()) or attach cleanup logic to promise cancellation (then(null, null, fn() => $conn->close())). Unbalanced connections leak file descriptors.
• Binary Payloads: __toString() returns UTF-8 text only. Use $msg->getPayload() for binary data, and pair with unpack() or stream_get_contents() for structured decoding.
• Connection Timeouts: Default is 20s (since v0.3.1). Override via connect_timeout in the React connector if dealing with high-latency endpoints.
• Exception Handling: Rejections include Exception—always include a second callback in then() to handle connection failures, and ensure $loop->stop() is called on fatal errors in CLI scripts.
• RFC6455 Masking: Pawl auto-masks client frames per spec—no manual intervention needed, but note this prevents inspection via standard HTTP proxies.