Websocket Server Laravel Package

Getting Started

Start by installing via Composer: composer require amphp/websocket-server. You’ll also need amphp/http-server for HTTP upgrade handling. The core concept is defining a Server class that implements Amp\WebsocketServer\WebsocketServer (or extends AbstractServer), and implementing onConnect(), onMessage(), and onClose() handlers. Your first use case will likely be a simple echo server: accept connections, echo received messages, and broadcast to all connected clients. Look at the examples/ directory in the repository for minimal working demos — especially echo-server.php — to bootstrap quickly.

Implementation Patterns

• Event-driven handler: Use class-based servers with callback-style lifecycle methods (onConnect, onMessage, onClose, onError) to manage client state and routing.
• Integration with amphp/http-server: Wrap your WebSocket server inside an HTTP server using WebSocketServerMiddleware, and route /ws paths to it while serving static files or API endpoints separately.
• Client management: Maintain a registry (e.g., SplObjectStorage) in your server class to track active connections. For larger apps, store session IDs or user IDs on connection and use them for targeted messaging.
• Frame handling: Use Amp\WebsocketServer\Message and Amp\WebsocketServer\Frame types directly in onMessage() to process text/binary payloads. For structured data, encode/decode JSON inside handlers.
• Graceful shutdown: Hook into HTTP server shutdown events to broadcast a “server shutting down” message and close connections cleanly.

Gotchas and Tips

• Async-only: All handlers must return promises (or null), never block (e.g., no sleep() or file I/O without Amp\Promise\wait() or async wrapper). Use Amp\Loop for timers instead of pcntl_alarm or sleep.
• Handshake customization: Extend DefaultHandshake or implement Handshake to inject custom headers or validate origins — common when using WebSocket behind reverse proxies (Nginx/Apache).
• Ping/pong handling: The library auto-pings by default, but verify your client-side code responds to them — stale connections may linger silently if clients ignore pings.
• Frame fragmentation: Large messages may arrive in multiple frames. If your protocol is message-based (not stream-based), buffer fragments in onFrame() until a complete message is received (e.g., using length prefixes or delimiters).
• Testing: Mock Connection objects to unit test handlers — avoid integration tests requiring actual sockets unless necessary. Use Amp\PHPUnit\AsyncTestCase for test harnesses.