Swoole Bundle

Symfony integration with Open Swoole and Swoole to speed up your applications.

Sponsored by:
Blackfire.io

---

Build Matrix

CI Job	Branch master	Branch develop
Circle

Table of Contents

• Swoole Bundle
  • Build Matrix
  • Table of Contents
  • Quick start guide
  • Features
  • Requirements
    • Current version
    • Future versions
    • Open Swoole
      • Version check
      • Installation

Quick start guide

1. Make sure you have installed proper Open Swoole PHP Extension and pass other requirements.

2. (optional) Create a new symfony project

   composer create-project symfony/skeleton project
   
   cd ./project

3. Install bundle in your Symfony application

   composer require swoole-bundle/swoole-bundle

   If using OpenSwoole, you need to also install the core package:

   composer require openswoole/core

4. Edit config/bundles.php

   return [
       // ...other bundles
       SwooleBundle\SwooleBundle\Bridge\Symfony\Bundle\SwooleBundle::class => ['all' => true],
   ];

5. Run Swoole HTTP Server

   bin/console swoole:server:run

6. Enter http://localhost:9501

7. You can now configure bundle according to your needs

Features

• Built-in API Server

  Swoole Bundle API Server allows managing Swoole HTTP Server in real-time.

  • Reload worker processes
  • Shutdown server
  • Access metrics and settings

• Improved static files serving

  Swoole HTTP Server provides a default static files handler, but it lacks supporting many Content-Types. To overcome this issue, there is a configurable Advanced Static Files Server. Static files serving remains enabled by default in the development environment. Static files directory defaults to %kernel.project_dir%/public. To configure your custom mime types check configuration reference (key swoole.http_server.static.mime_types).

• Symfony Messenger integration

  Available since version: 0.6

  Swoole Server Task Transport has been integrated into this bundle to allow easy execution of asynchronous actions. Documentation of this feature is available here.

• Hot Module Reload (HMR) for development ALPHA

  Since Swoole HTTP Server runs in Event Loop and does not flush memory between requests, to keep DX equal with normal servers, this bundle uses code replacement technique, using inotify PHP Extension to allow continuous development. It is enabled by default (when the extension is found) and requires no additional configuration. You can turn it off in bundle configuration.

  Remarks: This feature currently works only on a Linux host machine. It probably won't work with Docker, and it is possible that it works only with configuration: swoole.http_server.running_mode: process (default).

  A polling-based stat mode is also available: it detects changes by polling file modification times from PHP (no inotify extension required) and triggers the same graceful worker reload, so it also works in Docker and on macOS. The auto default selects stat when the inotify extension is not loaded (debug builds only).

  Note that a worker reload can only apply changes to files that were not already loaded before the workers forked - PHP cannot redeclare a class the forked worker already holds. Applications that load most of their service classes during kernel boot get little or nothing out of it.

  For reliable local dev, use the swoole:server:watch console command as a supervisor: it restarts the server on any watched change (with a php -l guard), so your edit always takes effect regardless of what was loaded before the fork.

• Access logs, (disabled by default) logs are configurable is a same way as apache mod log. Documentation of this feature is available here.

• Liveness endpoint (disabled by default) on a port of its own, served by a dedicated process so that it keeps answering while every worker is busy. Projects can contribute their own checks to it. Documentation of this feature is available here.

Requirements

Current version

• PHP version >= 8.3 && <= 8.5
• Open Swoole PHP Extension ^v26.2.0
• Swoole PHP Extension ^6.2.0+
• Symfony ^7.4 || 8.0.*

Additional requirements to enable specific features:

• Inotify PHP Extension ^2.0.0 to use Hot Module Reload (HMR)
  • When using PHP 8, inotify version ^3.0.0 is required

Swoole

The bundle requires one of those extensions:

• Swoole PHP Extension version 6.2.0 or higher. Active bug fixes are provided only for the latest version.
• Open Swoole PHP Extension version 22.0.0 or higher. Active bug fixes are provided only for the latest version.

Version check

To check your installed version you can run the following command:

// Swoole
php -r "echo swoole_version() . \PHP_EOL;"

# 6.2.0+

// OpenSwoole
php -r "echo OpenSwoole\Util::getVersion() . \PHP_EOL;"

# 22.0.0+

Installation

Swoole

Official GitHub repository swoole/swoole-src contains comprehensive installation guide. The recommended approach is to install it from source.

OpenSwoole

Official GitHub repository openswoole/ext-openswoole contains comprehensive installation guide. The recommended approach is to install it from source.