Swoole Bundle Laravel Package

Getting Started

Install the package via Composer and publish its configuration:

composer require <vendor>/<swoole-bundle>  # replace with actual package name
php artisan vendor:publish --tag=swoole-config

Set the required environment variables in .env (host, port, worker count, etc.) and start the Swoole HTTP server:

php artisan swoole:start

Where to look first:

• config/swoole.php (or similarly named config) – server, cache, and pool settings.
• src/Server/HttpServerManager.php – request lifecycle and header/URI validation (critical after v1.3.0).
• Connection pool classes (ConnectionPool, PostgreSQLPool, RedisPool) – tune sizes for your workload.

First use case: Replace PHP-FPM for a high-traffic Laravel API or microservice. Start by running the HTTP server alone, confirm requests are handled correctly, then progressively enable the Swoole cache adapter and database connection pools. v1.3.0 is the minimum version for production due to security fixes; upgrade immediately if you were on an older release.

Implementation Patterns

• HTTP server integration – Use the provided HttpServerManager to bootstrap the Laravel kernel and handle concurrent requests. Ensure you are on v1.3.0+ to benefit from CRLF injection protection (headers and URIs are sanitised).
• High-performance caching – Switch your cache store to SwooleCacheAdapter. Pattern: configure CACHE_DRIVER=swoole (or custom store) and use Laravel’s Cache facade as usual. v1.3.0 disables object deserialization by default (allowed_classes => false); if you cache PHP objects, explicitly whitelist classes in the cache config.
• Database connection pooling – Use ConnectionPool, PostgreSQLPool, or RedisPool to share connections across workers. Pattern: configure pool min/max sizes in config/swoole.php (or database config). v1.3.0 uses atomic counters for thread‑safe size tracking; no code changes needed, but verify pool limits against your database’s max_connections.
• Coroutine‑aware code – Leverage Swoole coroutines for I/O‑bound operations (HTTP calls, file I/O). Pattern: wrap blocking calls in Swoole\Coroutine\run() or use the package’s coroutine helpers. Avoid mixing blocking extensions (e.g., curl without coroutine hooks).
• State reset between requests – Use the package’s request lifecycle hooks to clear Laravel’s container and static state. Pattern: register a middleware or event listener that calls app()->forgetInstance() for scoped bindings, or rely on the package’s built‑in reset if available.
• Gradual migration – Run the Swoole server behind a load balancer alongside existing PHP-FPM workers. Route a small percentage of traffic first, monitor memory and connection pools, then shift fully.

Gotchas and Tips

• State pollution – Swoole workers are long‑lived; Laravel’s container, singletons, and static properties persist across requests. Use the package’s reset mechanisms or manually clear state. Common culprits: Auth, Request, and custom singletons. Test with concurrent requests to catch leakage.
• CRLF injection fix (v1.3.0) – Headers and URIs are now validated and sanitised. If you previously passed raw user input directly into headers (e.g., header("X-Custom: $input")), test that the new validation doesn’t reject legitimate values. The fix reduces memory allocations, but any non‑standard header format may need adjustment.
• Cache deserialization change (v1.3.0) – allowed_classes => false is now the default. If you were caching objects and relying on automatic deserialization, you’ll receive __PHP_Incomplete_Class instances or errors. Fix: whitelist required classes in the cache configuration ('allowed_classes' => [YourClass::class]) or switch to array/JSON serialization.
• Connection pool race conditions (fixed) – v1.3.0 replaces int $currentSize with Atomic $currentSize. No action required, but if you had custom pool extensions, review them for similar non‑atomic counters. Monitor pool exhaustion under load; atomic operations are faster but pool size still needs tuning.
• Debugging – Xdebug is incompatible with Swoole coroutines. Use swoole_error_log or Laravel’s file logging. For coroutine tracing, enable swoole.enable_coroutine in php.ini and use Swoole\Coroutine::getCid() in logs. Avoid dd()/dump() inside coroutines – they may hang.
• Extension and version requirements – Swoole 6.0+ is required. Ensure the extension is installed and enabled (php --ri swoole). PHP 8.2–8.4 and Symfony 7/8 are supported; verify your Laravel version’s Symfony dependency matches (Laravel 11+ uses Symfony 7).
• No migration needed – v1.3.0 is backward compatible. However, security fixes are critical: upgrade immediately. If you use custom cache adapters or pool implementations, extend the provided classes rather than overriding internal atomic logic.
• Extension points – Extend HttpServerManager for custom request/response handling. Implement the Swoole cache interface for custom backends. Subclass ConnectionPool for other databases (e.g., MySQL) following the atomic‑size pattern.