Swoole Server Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require brandoriented/swoole-server-bundle
   

   Ensure BrandOriented\SwooleServerBundle\SwooleServerBundle is registered in config/bundles.php.

2. Configure the Server: Override default settings in config/packages/brandoriented_swoole_server.yaml:

   host: 0.0.0.0
   port: 8080
   options:
       log_file: "%kernel.logs_dir%/swoole.log"
       document_root: "%kernel.project_dir%/public"
   

3. First Use Case: Start the server with:

   php bin/console swoole:server:start
   

   Verify it’s running by accessing http://localhost:8080 or checking logs in var/log/swoole.log.

Implementation Patterns

Workflow Integration

1. Hybrid Development:

   • Use the Swoole server for async tasks (e.g., WebSocket, HTTP long-polling) while keeping Symfony’s built-in server for CLI/debugging.
   • Example: Offload real-time notifications via WebSocket endpoints routed through Swoole.

2. Task Workers:

   • Define async tasks in Symfony controllers/services using Swoole\Coroutine or Swoole\AsyncTask.
   • Example:

     use BrandOriented\SwooleServerBundle\Task\TaskManager;
     
     class NotificationService {
         public function __construct(private TaskManager $taskManager) {}
     
         public function sendAsyncEmail(string $email) {
             $this->taskManager->dispatch('send_email', [$email]);
         }
     }
     

3. Static File Handling:

   • Enable enable_static_handler to let Swoole serve static assets (CSS/JS/images) directly, reducing PHP-FPM load.
   • Configure document_root to point to your public/ directory.

4. Event Listeners:

   • Hook into Swoole lifecycle events (e.g., onStart, onRequest) via Symfony’s event dispatcher:

     # config/packages/brandoriented_swoole_server.yaml
     events:
         on_start: App\EventListener\SwooleStartListener
     

5. Load Balancing:

   • Use worker_num and reactor_num to optimize CPU/memory usage for high-traffic apps.
   • Example config for 4 workers and 2 reactors:

     options:
         worker_num: 4
         reactor_num: 2
     

Gotchas and Tips

Pitfalls

1. Daemonization Conflicts:

   • If daemonize: true, ensure pid_file is writable (e.g., /var/run/swoole_server.pid). Use chmod 777 temporarily for testing.
   • Debugging: Check var/log/swoole.log for permission errors or use daemonize: false in development.

2. Static Handler Caveats:

   • enable_static_handler bypasses Symfony’s middleware (e.g., security, caching). Exclude sensitive routes from static handling.
   • Workaround: Use dispatch_mode: 1 (fixed) to prioritize PHP routes over static files.

3. Task Worker Isolation:

   • Tasks run in separate processes. Avoid sharing state (e.g., Symfony’s container) directly. Use queues (e.g., Doctrine Messenger) for persistence.

4. Port Reuse:

   • enable_port_reuse: true helps avoid "Address already in use" errors on restart. Test in staging before production.

5. SSL Configuration:

   • If using ssl_cert_file/ssl_key_file, ensure paths are absolute and files are readable. Test with:

     openssl s_client -connect localhost:8080 -servername yourdomain.com
     

Debugging Tips

1. Log Levels:

   • Override log level in config:

     options:
         log_level: 7  # DEBUG (1-7: ERROR to DEBUG)
     

2. Coroutine Debugging:

   • Use Swoole\Coroutine::getuid() to trace coroutine IDs in logs:

     \Swoole\Coroutine::debug();
     

3. Process Monitoring:

   • Attach to Swoole processes with:

     php bin/console swoole:server:ps
     

   • Kill specific workers with:

     php bin/console swoole:server:kill <worker_id>
     

Extension Points

1. Custom Middleware:

   • Extend BrandOriented\SwooleServerBundle\Middleware\AbstractMiddleware to add logic before/after requests.

2. Protocol Support:

   • Add support for custom protocols (e.g., WebSocket) by implementing BrandOriented\SwooleServerBundle\Protocol\ProtocolInterface.

3. Configuration Validation:

   • Override BrandOriented\SwooleServerBundle\DependencyInjection\Configuration to add custom validation for options.

4. Metrics Integration:

   • Integrate with Symfony Monitor or Prometheus by exposing Swoole stats via:

     $server->stats(); // Access Swoole server metrics
     

```markdown
---
**Note**: The package is minimally documented (0 stars, no active maintenance). Validate all `options` in a staging environment before production use. Consider forking to add missing features (e.g., WebSocket support, Docker integration).