Connection Manager Extra Laravel Package

Getting Started

Start by installing the package via Composer: composer require clue/connection-manager-extra. This package extends ReactPHP's React\Socket component with advanced decorators for connection management — it does not include ReactPHP itself, so ensure react/socket is also installed. The primary use case is managing persistent, asynchronous TCP/SSL connections in long-running applications (e.g., WebSocket clients, custom TCP servers, or microservices communication). Begin by reviewing the README for the included decorators: TimeoutDecorator, ReconnectDecorator, BufferedConnection, and SecureConnection.

Note (v1.3.0): New shorthand constructors (ConnectionManagerTimeout, ConnectionManagerDelayed) now infer the default event loop — simplifying usage by removing the need to pass $loop explicitly. Existing ...Decorator classes remain supported for backward compatibility.

Implementation Patterns

• Retry logic with ReconnectDecorator: Wrap your socket connections to automatically retry on failure with exponential backoff (configurable delays and max retries).

  $connector = new ReconnectDecorator($connector, ['delay' => 1000, 'maxAttempts' => 5]);
  

• Timeout enforcement with TimeoutDecorator / ConnectionManagerTimeout:
  • Legacy (explicit loop):

    $connector = new TimeoutDecorator($connector, 5.0, $loop);
    

  • New (default loop inferred):

    $connector = new ConnectionManagerTimeout($connector, 5.0); // $loop optional
    

• Secure + buffered connections: Chain decorators for robust production-ready clients (e.g., TLS + automatic buffering + auto-reconnect).

  $connector = new BufferedConnection($connector);
  $connector = new SecureConnection($connector, $context);
  $connector = new ReconnectDecorator($connector);
  

  Note: ConnectionManagerDelayed now accepts optional $loop parameter (inferred if omitted), enabling cleaner delayed-retry patterns without loop propagation boilerplate.

• Integration with existing ReactPHP apps: Drop these decorators into your application’s event loop–aware service layer (e.g., in a worker process or CLI daemon), avoiding blocking code and leveraging async streaming. Prefer ConnectionManager* variants for new code to leverage simplified APIs.

Gotchas and Tips

• Version compatibility: This package targets ReactPHP ^1.0 (react/socket ^1.3+). While PHP 8.1/8.2 is now fully supported, ensure react/promise v2.x is used for Promise v3 forward compatibility — breaking changes may occur with react/promise ^3.0 until further updates.
• Decorator order matters: Position TimeoutDecorator outside ReconnectDecorator if you want per-retry timeout control; otherwise, timeouts may reset on reconnect. Be consistent: Mix ConnectionManager* and *Decorator classes cautiously — they share core behavior but may differ in parameter handling.
• Memory leaks: BufferedConnection retains unread data until consumed; ensure consumers drain streams or register data handlers promptly.
• No built-in logging: Wrap decorators with custom logging (e.g., in a factory) — no debug output is emitted by default. Consider logging at ConnectionManager* boundaries for clearer tracing.
• Event loop coupling: While ConnectionManager* variants now infer the default loop (Loop::get()), avoid instantiating any decorator outside a running loop context. Explicit loop injection is still advised for testability.
• Extension point: Consider subclassing ConnectionManager* decorators to inject retry strategies (e.g., jittered exponential backoff), custom error handling, or telemetry integration.