Websocket Laravel Package

## Getting Started

### Minimal Setup for Laravel
1. **Install the package**:
   ```bash
   composer require phrity/websocket

2. Basic Client Usage (Request/Response):

   use WebSocket\Client;
   use WebSocket\Middleware\CloseHandler;
   use WebSocket\Middleware\PingResponder;
   
   $client = new Client("wss://echo.websocket.org/");
   $client
       ->addMiddleware(new CloseHandler())
       ->addMiddleware(new PingResponder());
   
   $client->text("Hello");
   $response = $client->receive();
   echo $response->getContent(); // Output: "Hello"
   $client->close();
   

3. Basic Server Setup (Laravel Route):

   use WebSocket\Server;
   use WebSocket\Middleware\CloseHandler;
   use WebSocket\Middleware\PingResponder;
   
   Route::get('/ws', function () {
       $server = new Server(8080);
       $server
           ->addMiddleware(new CloseHandler())
           ->addMiddleware(new PingResponder())
           ->onText(function ($server, $connection, $message) {
               $connection->text("Echo: " . $message->getContent());
           });
       $server->start();
   });
   

4. Key Files to Review:

   • docs/Client.md (for client patterns)
   • docs/Server.md (for server patterns)
   • docs/Middleware/ (for middleware customization)

Implementation Patterns

Laravel-Specific Workflows

1. WebSocket Client in Laravel Jobs/Commands

Use the client for background tasks (e.g., real-time data sync):

use Illuminate\Bus\Queueable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use WebSocket\Client;

class SyncDataJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle()
    {
        $client = new Client("wss://api.example.com/ws");
        $client->addMiddleware(new CloseHandler());
        $client->text(json_encode(['action' => 'sync']));

        $response = $client->receive();
        $data = json_decode($response->getContent(), true);
        // Process $data...
        $client->close();
    }
}

2. Server Integration with Laravel Events

Trigger Laravel events on WebSocket messages:

$server->onText(function ($server, $connection, $message) {
    event(new WebSocketMessageReceived(
        $message->getContent(),
        $connection->getRemoteAddress()
    ));
});

3. Middleware Stack for Reusability

Create a base middleware stack in a service provider:

// app/Providers/WebSocketServiceProvider.php
public function register()
{
    $this->app->singleton('websocket.middleware.stack', function () {
        return [
            new CloseHandler(),
            new PingResponder(),
            new CompressionExtension(new DeflateCompressor()),
        ];
    });
}

Then reuse it:

$client = new Client("wss://example.com");
foreach ($this->app['websocket.middleware.stack'] as $middleware) {
    $client->addMiddleware($middleware);
}

4. Connection Management with Laravel Sessions

Store WebSocket connections in Laravel sessions:

$server->onOpen(function ($server, $connection) {
    session([$connection->getId() => $connection]);
});

$server->onClose(function ($server, $connection) {
    session()->forget($connection->getId());
});

5. Broadcasting with WebSockets

Replace Laravel Echo/Pusher with custom WebSocket broadcasting:

// app/Services/WebSocketBroadcaster.php
class WebSocketBroadcaster
{
    protected $server;

    public function __construct(Server $server)
    {
        $this->server = $server;
    }

    public function broadcast($event, $data)
    {
        $this->server->getConnections()->each(function ($connection) use ($data) {
            $connection->text(json_encode($data));
        });
    }
}

Middleware Patterns

1. Custom Authentication Middleware

use WebSocket\Middleware\ProcessHttpIncomingInterface;

class AuthMiddleware implements ProcessHttpIncomingInterface
{
    public function processHttpIncoming($stack, $connection)
    {
        $request = $stack->handleHttpIncoming();
        $token = $request->getHeader('Authorization');

        if (!auth()->validate($token)) {
            throw new \RuntimeException("Unauthorized");
        }

        return $request;
    }

    public function __toString()
    {
        return 'AuthMiddleware';
    }
}

// Usage:
$client->addMiddleware(new AuthMiddleware());

2. Logging Middleware

use WebSocket\Middleware\ProcessIncomingInterface;
use WebSocket\Middleware\ProcessOutgoingInterface;

class LoggingMiddleware implements ProcessIncomingInterface, ProcessOutgoingInterface
{
    public function processIncoming($stack, $connection)
    {
        $message = $stack->handleIncoming();
        \Log::debug("Incoming: " . $message->getContent());
        return $message;
    }

    public function processOutgoing($stack, $connection, $message)
    {
        \Log::debug("Outgoing: " . $message->getContent());
        return $stack->handleOutgoing($message);
    }

    public function __toString()
    {
        return 'LoggingMiddleware';
    }
}

3. Rate Limiting Middleware

use WebSocket\Middleware\ProcessIncomingInterface;
use Illuminate\Cache\RateLimiter;

class RateLimitMiddleware implements ProcessIncomingInterface
{
    protected $limiter;

    public function __construct(RateLimiter $limiter)
    {
        $this->limiter = $limiter;
    }

    public function processIncoming($stack, $connection)
    {
        $key = 'websocket_rate_limit_' . $connection->getRemoteAddress();
        if (!$this->limiter->tooManyAttempts($key, 10)) {
            return $stack->handleIncoming();
        }
        throw new \RuntimeException("Rate limit exceeded");
    }

    public function __toString()
    {
        return 'RateLimitMiddleware';
    }
}

Integration with Laravel Ecosystem

1. Laravel Queues + WebSocket

Use WebSocket clients in queued jobs for async operations:

// Dispatch a job to sync data via WebSocket
SyncDataJob::dispatch($userId);

2. Laravel Events + WebSocket

Listen to Laravel events and broadcast via WebSocket:

// In an event listener
event(new OrderPlaced($order));
broadcast(new WebSocketBroadcast($order))->toWebSocket();

3. Laravel API Resources

Format WebSocket messages as API resources:

$connection->text(response()->json([
    new UserResource($user),
    'meta' => ['timestamp' => now()]
]));

4. Laravel Validation

Validate incoming WebSocket messages:

$server->onText(function ($server, $connection, $message) {
    $data = json_decode($message->getContent(), true);
    $validator = Validator::make($data, [
        'action' => 'required|in:fetch,update',
        'data' => 'sometimes|array',
    ]);

    if ($validator->fails()) {
        $connection->text(response()->json(['error' => $validator->errors()]));
        return;
    }
    // Process valid data...
});

Gotchas and Tips

Common Pitfalls

1. Blocking Calls in Laravel

• Issue: receive() is blocking. Avoid calling it in routes or middleware.
• Fix: Use non-blocking patterns (e.g., onText callbacks) or run in a separate process/queue.

2. Connection Leaks

• Issue: Forgetting to call $client->close() or $server->stop() can leak connections.
• Fix: Use Laravel's finally blocks or context managers:

  $client = new Client("wss://example.com");
  try {
      $client->text("Hello");
      $response = $client->receive();
  } finally {
      $client->close();
  }
  

3. Middleware Order Matters

• Issue: Middleware execution order affects behavior (e.g., auth before logging).
• Fix: Add middlewares in the correct order:

  $client->addMiddleware(new AuthMiddleware())       // First
      ->addMiddleware(new LoggingMiddleware());      // Second
  

4. SSL/TLS Configuration

• Issue: wss:// connections may fail due to missing CA certificates.
• Fix: Configure OpenSSL defaults in Laravel:

  // config/websocket.php
  'ssl' => [
      'local_cert' => storage_path('certs/local.crt'),
      'local_pk'   => storage_path('certs/local.key'),
      'passphrase' => env('SSL_PASSPHRASE'),
  ];
  

5. Fragmented Messages

• Issue: