Getting Started

Minimal Setup in Laravel

Install the package:
```
composer require chrome-php/wrench
```

Create a basic WebSocket server (e.g., app/Console/Commands/WebSocketServer.php):

use Wrench\BasicServer;
use Wrench\Application\DataHandlerInterface;
use Illuminate\Console\Command;

class WebSocketServer extends Command implements DataHandlerInterface
{
    protected $signature = 'ws:server';
    protected $description = 'Start the WebSocket server';

    public function handle()
    {
        $server = new BasicServer('ws://localhost:8000', [
            'allowed_origins' => ['*'], // Adjust for production
        ]);

        $server->registerApplication('chat', $this);
        $server->run();
    }

    public function onData(string $data, \Wrench\Connection $connection): void
    {
        $this->info("Received: {$data}");
        $connection->send("Echo: {$data}");
    }
}

Register the command in app/Console/Kernel.php:

protected $commands = [
    Commands\WebSocketServer::class,
];

Run the server:
```
php artisan ws:server
```

Test with a client (e.g., browser JavaScript):

const socket = new WebSocket('ws://localhost:8000/chat');
socket.onopen = () => socket.send('Hello');
socket.onmessage = (e) => console.log(e.data);

First Use Case: Real-Time Chat

Use the chat application endpoint to handle messages.
Extend DataHandlerInterface to implement custom logic (e.g., broadcast to all connected clients).

Implementation Patterns

Workflows

Server-Side Routing:

$server->registerApplication('notifications', new NotificationHandler());
$server->registerApplication('live-updates', new LiveUpdateHandler());

Use Laravel’s service container to resolve dependencies:

$server->registerApplication('auth', app(AuthWebSocketHandler::class));

Client Management:

Track connected clients using a Connection object:

public function onData(string $data, \Wrench\Connection $connection): void
{
    $userId = $connection->getExtraData('user_id');
    // Store connection in Redis for later broadcasting
}

Use Connection::getExtraData() to attach metadata (e.g., user IDs, session tokens).

Broadcasting:

For Laravel integration, use a queue to trigger WebSocket broadcasts:

// In a Laravel event listener
event(new MessageSent($message));

// In a queue job
public function handle()
{
    $connections = Redis::smembers('ws:connections');
    foreach ($connections as $connectionId) {
        $client = new \Wrench\Client('ws://localhost:8000/chat');
        $client->connect();
        $client->sendData($this->message->data);
        $client->disconnect();
    }
}

Hybrid HTTP/WebSocket:

Use Laravel routes to proxy HTTP requests to WebSocket:

Route::get('/ws-proxy', function () {
    $server = new \Wrench\Client('ws://localhost:8000/chat');
    $server->connect();
    return response()->json(['status' => 'connected']);
});

Integration Tips

Logging: Inject a PSR-3 logger for debugging:

$server->setLogger(app(\Psr\Log\LoggerInterface::class));

Error Handling: Wrap server startup in a try-catch:

try {
    $server->run();
} catch (\Exception $e) {
    report($e);
    $this->error("WebSocket server crashed: " . $e->getMessage());
}

Configuration: Store WebSocket settings in config/websocket.php:

return [
    'port' => env('WEBSOCKET_PORT', 8000),
    'origins' => explode(',', env('WEBSOCKET_ORIGINS', '*')),
];

Then load it in your server command:

$server = new BasicServer("ws://localhost:{$config['port']}", [
    'allowed_origins' => $config['origins'],
]);

Gotchas and Tips

Pitfalls

Blocking Calls:

Avoid synchronous operations (e.g., database queries) in onData(). Use queues or async tasks:

public function onData(string $data, \Wrench\Connection $connection): void
{
    dispatch(new ProcessWebSocketData($data, $connection));
}

Connection Leaks:
- Always close connections explicitly:
```
$client->disconnect(); // Critical for resource cleanup
```
- Use registerShutdownFunction to ensure cleanup on crashes.
Origin Restrictions:
- Misconfigured allowed_origins will block WebSocket connections. Test with:
```
'allowed_origins' => ['http://localhost:3000', 'https://yourdomain.com'],
```
PHP 8.5 Quirks:
- New: Ensure random_bytes() is available (it is in PHP 8.5, but test if using custom PHP builds).
- New: Typed properties in DataHandlerInterface may require adjustments if extending classes.

Large Payloads:

Wrench has a default payload size limit (65536 bytes). For larger data, implement chunking:

if (strlen($data) > 65536) {
    $chunks = str_split($data, 65500);
    foreach ($chunks as $chunk) {
        $connection->send($chunk);
    }
}

Debugging

Handshake Failures:

Check for missing Sec-WebSocket-Key headers or malformed responses. Enable verbose logging:

$server->setLogger(new \Monolog\Logger('wrench', [
    new \Monolog\Handler\StreamHandler(storage_path('logs/wrench.log'), \Monolog\Logger::DEBUG),
]));

Connection Timeouts:
- Increase PHP’s max_execution_time or use a process manager (e.g., Supervisor) to restart crashed servers.
Memory Leaks:
- Monitor memory usage with memory_get_usage(). Close idle connections:
```
$connection->closeIfIdle(30); // Close after 30 seconds of inactivity
```

Extension Points

Custom Handshake:

Extend \Wrench\Server to validate tokens or enforce auth:

class AuthServer extends \Wrench\BasicServer
{
    protected function onHandshake(\Wrench\Connection $connection): void
    {
        $token = $connection->getHeader('Authorization');
        if (!auth()->validateToken($token)) {
            $connection->close();
            return;
        }
        parent::onHandshake($connection);
    }
}

STOMP Support:

Use Wrench’s built-in STOMP adapter for pub/sub:

$stompServer = new \Wrench\StompServer('ws://localhost:8000/stomp');
$stompServer->registerApplication('queue', new StompHandler());

Laravel Service Provider:

Create a provider to manage the WebSocket server lifecycle:

class WebSocketServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(WebSocketServer::class, function () {
            $server = new BasicServer(config('websocket.url'), config('websocket.options'));
            return $server;
        });
    }
}

Metrics:

Integrate with Laravel Horizon or Prometheus:

$server->onConnection(function (\Wrench\Connection $connection) {
    app(\App\Metrics\WebSocketMetrics::class)->incrementConnections();
});

Tips

Use reactphp for Async:

Leverage ReactPHP’s event loop for non-blocking operations:

use React\EventLoop\Factory;

$loop = Factory::create();
$server = new \Wrench\BasicServer('ws://localhost:8000', [], $loop);
$loop->run();

Load Testing:
- Use tools like websocat or autobahn-testsuite to simulate traffic:
```
websocat ws://localhost:8000/chat
```
Docker Integration:
- Run Wrench in a separate container with a health check:

Wrench Laravel Package