Datagram Laravel Package

Getting Started

Start by installing via Composer: composer require react/datagram:^1.10. Create a Factory instance (no loop argument needed since v1.8.0—uses ReactPHP’s default loop) and use createClient() for clients or createServer() for UDP servers. The core API mirrors Node.js’s dgram.Socket: use send($data, $address) to transmit, and listen to the message event to receive datagrams. The simplest working example is sending a message and waiting for responses—just like the Quickstart example in the README. Check the examples directory for hands-on patterns (e.g., DNS lookup client, broadcast server, echo server).

Implementation Patterns

• Clients: Use createClient('host:port') to obtain a socket; resolve the promise before sending. Address can be hostname (resolves via DNS) or IP, with IPv6 fully supported.
• Servers: Use createServer(callable $handler)—the handler receives (string $message, string $address, Socket $server). Bind to 0.0.0.0:0 for auto-assigned port, or fixed *:port.
• Address handling: Remote addresses are returned in host:port format (e.g., ::1:53). Use react/dns for reverse lookups or custom resolution if needed.
• Integration with Laravel: Wrap ReactPHP event loop with Laravel’s queue:work --timeout=0 or use reactphp/async (recommended since v1.9.0) for async operations inside workers. Avoid blocking the HTTP request cycle—use UDP for fire-and-forget logging, metrics, or inter-service notification without blocking users.
• High-throughput pipelines: In batch workers (e.g., cron-triggered), open one socket, reuse for many send() calls, and batch messages. For persistent services, hook into Supervisor or systemd with loop->run() in a console command.

Gotchas and Tips

• No built-in reliability: UDP is lossy—this library doesn’t retransmit packets. Implement app-layer ACK/retry if needed (e.g., using Promise timeouts and retries).
• Address resolution pitfalls: Hostnames resolve via system DNS (including /etc/hosts, fallback servers since v1.7.0). If DNS fails, the client promise rejects with an informative error—always catch() the promise. IPv6 support requires OS/kernel support; tests auto-skip on unsupported systems.
• Error handling: Custom error handlers (e.g., set_error_handler()) may interfere—v1.9.0+ cleans up errors more gracefully. Always listen to the error event: $socket->on('error', fn($e) => error_log($e));.
• Promise cancellation: Since v1.1.0, cancelling pending createClient() DNS lookups avoids leaks—useful for timeouts in large-scale deployments.
• IPv6 pitfalls: Remote addresses include brackets for IPv6 (e.g., [::1]:53). Use parse_url() or strpos() carefully when parsing addresses manually. v1.1.1+ normalizes output but returns null for unknown/unparseable addresses.
• Lifecycle management: Don’t forget to $socket->close() when done—especially in long-running processes or CLI scripts—to avoid socket leaks. Laravel Horizon workers need explicit cleanup after each job.