Skip to main content

​
Overview

Swoole variant images extend the Alpine-based images with the Swoole PHP extension, enabling asynchronous, concurrent, and high-performance network applications. Swoole provides coroutine-based concurrency, async I/O, and built-in HTTP/WebSocket servers.
Swoole images are built on top of Alpine base images, inheriting all SQL Server drivers and PHP extensions while adding Swoole capabilities.

​
What is Swoole?

Swoole is an asynchronous programming framework for PHP that provides:

Coroutines

Lightweight concurrent execution without callback hell

Async I/O

Non-blocking I/O operations for high concurrency

Built-in Servers

HTTP, WebSocket, TCP, and UDP servers out of the box

Performance

Handle thousands of concurrent connections efficiently

​
Available Tags

  • namoshek/php-mssql:8.4-cli-alpine-swoole
  • namoshek/php-mssql:8.4-fpm-alpine-swoole

​
What’s Included

Swoole images include everything from Alpine base images plus:

​
Swoole Extension

The Swoole PHP extension is added on top of the base Alpine image: 
FROM namoshek/php-mssql:8.4-cli-alpine

# Install the Swoole PHP extension
RUN chmod uga+x /usr/bin/install-php-extensions \
    && sync \
    && install-php-extensions swoole

​
Complete Feature Set

All features from Alpine images are included:
  • Microsoft ODBC Driver 18
  • mssql-tools18 (sqlcmd, bcp)
  • sqlsrv and pdo_sqlsrv extensions

​
When to Use Swoole

Real-time Applications

WebSocket servers, chat applications, live dashboards

Microservices

High-performance API gateways and service meshes

Long-running Processes

Background workers, queue processors, schedulers

High Concurrency

Applications handling thousands of simultaneous connections
Not Recommended For: Traditional PHP-FPM workflows, simple web applications, or projects where you don’t need async capabilities. Standard Alpine or Debian images are simpler for most use cases.

​
Swoole Capabilities

​
HTTP Server

Create a high-performance HTTP server without nginx or Apache: 
<?php
$http = new Swoole\Http\Server("0.0.0.0", 9501);

$http->on("start", function ($server) {
    echo "Swoole HTTP server started at http://127.0.0.1:9501\n";
});

$http->on("request", function ($request, $response) {
    // SQL Server connection with PDO
    $pdo = new PDO(
        "sqlsrv:server=sql-server;Database=mydb",
        "username",
        "password"
    );
    
    $stmt = $pdo->query("SELECT TOP 10 * FROM users");
    $users = $stmt->fetchAll(PDO::FETCH_ASSOC);
    
    $response->header("Content-Type", "application/json");
    $response->end(json_encode($users));
});

$http->start();

​
WebSocket Server

Build real-time WebSocket applications: 
<?php
$server = new Swoole\WebSocket\Server("0.0.0.0", 9502);

$server->on('open', function($server, $request) {
    echo "Connection opened: {$request->fd}\n";
});

$server->on('message', function($server, $frame) {
    echo "Received: {$frame->data}\n";
    $server->push($frame->fd, "Server: {$frame->data}");
});

$server->on('close', function($server, $fd) {
    echo "Connection closed: {$fd}\n";
});

$server->start();

​
Coroutines

Handle concurrent operations elegantly: 
<?php
use Swoole\Coroutine;

Co\run(function() {
    // Multiple SQL queries in parallel
    $results = [];
    
    $wg = new Swoole\Coroutine\WaitGroup();
    
    // Query 1
    $wg->add();
    Coroutine::create(function() use (&$results, $wg) {
        $pdo = new PDO("sqlsrv:server=sql-server;Database=mydb", "user", "pass");
        $results['users'] = $pdo->query("SELECT * FROM users")->fetchAll();
        $wg->done();
    });
    
    // Query 2
    $wg->add();
    Coroutine::create(function() use (&$results, $wg) {
        $pdo = new PDO("sqlsrv:server=sql-server;Database=mydb", "user", "pass");
        $results['products'] = $pdo->query("SELECT * FROM products")->fetchAll();
        $wg->done();
    });
    
    $wg->wait();
    
    var_dump($results);
});

​
Usage Examples

docker run -it -p 9501:9501 namoshek/php-mssql:8.4-cli-alpine-swoole php server.php

​
Laravel Octane Support

Swoole images work perfectly with Laravel Octane: 
services:
  octane:
    image: namoshek/php-mssql:8.4-cli-alpine-swoole
    ports:
      - "8000:8000"
    volumes:
      - ./laravel-app:/var/www
    working_dir: /var/www
    command: php artisan octane:start --server=swoole --host=0.0.0.0 --port=8000
    environment:
      - DB_CONNECTION=sqlsrv
      - DB_HOST=mssql
      - DB_DATABASE=laravel
      - DB_USERNAME=sa
      - DB_PASSWORD=YourStrong@Passw0rd
    depends_on:
      - mssql

  mssql:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong@Passw0rd

​
Image Size

Swoole adds minimal overhead to Alpine images:
  • CLI images: ~270-320 MB (+~20MB vs Alpine)
  • FPM images: ~220-270 MB (+~20MB vs Alpine)
Swoole’s performance benefits far outweigh the small size increase for async workloads.

​
Performance Comparison

Traditional PHP-FPM

~1,000 requests/second with 100 concurrent connections

Swoole HTTP Server

~10,000+ requests/second with 1,000+ concurrent connections
Actual performance depends on your application logic, database queries, and server hardware. Swoole excels at I/O-bound operations.

​
Important Considerations

Unlike PHP-FPM, Swoole keeps your application in memory between requests. This means:
  • Faster response times (no bootstrap overhead)
  • Shared state possible (use with caution)
  • Memory leaks can accumulate
  • Database connections should be managed carefully
Changes to PHP files don’t take effect automatically. You must:
  • Restart the Swoole server to see changes
  • Use hot-reload tools in development
  • Implement proper deployment strategies
Global variables persist between requests:
  • Be careful with static variables
  • Reset state as needed
  • Use Swoole’s context API for request-specific data
Not all PHP libraries work well with Swoole:
  • Most pure PHP code works fine
  • Libraries using blocking I/O may reduce performance
  • Frameworks like Laravel Octane are designed for Swoole
  • Test thoroughly with your dependencies

​
Debugging and Monitoring

<?php
// Enable Swoole statistics
$server = new Swoole\Http\Server("0.0.0.0", 9501);

$server->set([
    'worker_num' => 4,
    'daemonize' => false,  // Set true for production
    'log_file' => '/var/log/swoole.log',
    'log_level' => SWOOLE_LOG_INFO,
]);

// Monitor endpoint
$server->on('request', function($request, $response) use ($server) {
    if ($request->server['request_uri'] === '/stats') {
        $stats = $server->stats();
        $response->header('Content-Type', 'application/json');
        $response->end(json_encode($stats, JSON_PRETTY_PRINT));
        return;
    }
    
    // Your application logic
    $response->end("Hello World");
});

$server->start();

​
Learning Resources

Swoole Documentation

Official Swoole documentation and guides

Laravel Octane

Laravel’s first-party Swoole integration

Hyperf Framework

Modern PHP framework built for Swoole

Swoole GitHub

Source code and examples

​
Next Steps

Alpine Images

Learn about the base Alpine images

SQL Server Connection

Connect to SQL Server with Swoole

PHP Configuration

Configure PHP and Swoole settings

Examples

More container usage examples

Build docs developers (and LLMs) love

Get started for freeTalk to us