Websocket Laravel Package

Getting Started

Begin by installing the package via Composer (composer require amphp/websocket) and ensuring your environment supports Amp (PHP 8.1+ recommended). The first use case is typically building a minimal WebSocket server: extend Amp\Websocket\Server or use Amp\Websocket\Server::create() with a callback to handle incoming connections and messages. For clients, instantiate Amp\Websocket\Client and connect using await(). Check the official Amp documentation for foundational concepts (coroutines, event loop, Amp\Promise)—they’re essential to using this package correctly. Start with the included examples (e.g., examples/server.php, examples/client.php) to see echoing, broadcasting, and connection lifecycle handling.

Implementation Patterns

• Server with connection registry: Use SplObjectStorage or an array to track active connections per user/session, enabling targeted broadcasts. Dispatch messages using connection->send($frame).
• Message routing: Implement a simple switch or map-based handler (e.g., $handlers[$message->getPayload()] = $handler) inside your connection callback for type-specific processing.
• Integration with existing HTTP apps: Use Amp\Http\Server to serve your main app, then upgrade specific routes (e.g., /ws) to WebSocket via Amp\Websocket\Server by intercepting the handshake—this avoids coupling or port sprawl.
• Backpressure handling: Leverage the coroutine-friendly send() return value (Promise) and await() only when necessary. Buffer outgoing data using Amp\Promise\timeout() or manual streamSetReadTimeout() patterns to avoid memory bloat.
• Health checks & timeouts: Use periodic pings (connection->ping()) with Amp\Loop timers to detect zombie connections; clean up stale entries in your registry.

Gotchas and Tips

• Not PSR-7/15 compatible: This is event-driven, not middleware-based—don’t expect Symfony/Laravel-style request/response handling. State must be managed in the callback scope (closure captures) or via external registries.
• Threading ≠ parallelism: PHP coroutines are cooperative; CPU-heavy operations block the loop. Offload intensive work using Amp\Parallel or async I/O patterns (e.g., database calls via amphp/postgres, amphp/redis).
• Frame vs payload: onMessage() receives Amp\Websocket\Frame. Always extract payload with $frame->getPayload() (string or binary) and handle UTF-8 validation manually.
• Debugging tip: Enable Amp’s internal logging via Amp\Log\BufferedLogger + Amp\Log\StandardErrorHandler to catch handshake failures or silent connection drops.
• Security: Validate Origin header and apply your own authentication (e.g., JWT in URL query) during the handshake (use Server::create()’s $options['handshake'] callback).
• Upgrade path: If scaling beyond single-process, consider amphp/redis for pub/sub or amphp/parallel workers for inter-connection messaging.