# Swoole HTTP Server

> High-performance async HTTP server for PHP applications.

- Category: Web Servers & Reverse Proxies
- Difficulty: intermediate
- Components: swoole
- Tags: swoole, php, async, high-performance, coroutines
- Source: https://docker.recipes/web-servers/swoole

## Overview

Swoole is a revolutionary PHP extension that transforms traditional synchronous PHP into a high-performance asynchronous runtime, eliminating the need for external web servers like Apache or Nginx. Originally developed by Chinese engineers and now maintained globally, Swoole introduces coroutines, event loops, and built-in server capabilities directly into PHP, enabling developers to build concurrent applications without the complexity of callback-based programming. This async approach allows a single PHP process to handle thousands of concurrent connections efficiently.

The Swoole HTTP server leverages coroutine-based architecture to achieve performance gains of 10-100x over traditional PHP-FPM setups for I/O-intensive workloads. Unlike traditional PHP where each request spawns a separate process, Swoole maintains persistent worker processes that handle multiple requests concurrently using lightweight coroutines. The built-in HTTP server eliminates the overhead of CGI/FastCGI communication layers, while connection pooling for databases and caching systems dramatically reduces connection establishment costs.

This stack is ideal for PHP developers building high-throughput APIs, real-time applications, or microservices who need better performance without abandoning PHP's familiar syntax and ecosystem. Companies migrating from Node.js or Go for performance reasons can leverage Swoole to achieve similar concurrency levels while maintaining their existing PHP codebase and developer expertise.

## Features

- Coroutine-based concurrency allowing thousands of simultaneous connections without callback complexity
- Built-in HTTP/HTTPS server eliminating need for Apache, Nginx, or PHP-FPM
- Persistent connection pooling for MySQL, Redis, and PostgreSQL reducing connection overhead
- WebSocket and TCP/UDP server capabilities within the same PHP process
- Memory-resident application state between requests enabling advanced caching strategies
- Laravel Octane and Hyperf framework integration for enterprise applications
- Built-in process management with worker process recycling and memory limit controls
- Hook-based PHP function replacement making file I/O and network calls non-blocking

## Use cases

- High-frequency trading platforms requiring microsecond response times for financial data APIs
- Gaming backends handling real-time multiplayer interactions and leaderboard updates
- IoT data collection services processing thousands of sensor readings per second
- Chat applications combining HTTP APIs with WebSocket connections in single deployment
- E-commerce platforms during flash sales requiring rapid inventory updates across concurrent users
- Microservices architectures where PHP teams need Node.js-level performance without language migration
- Development environments testing async PHP code before production deployment

## Prerequisites

- Minimum 512MB RAM allocation as Swoole maintains persistent worker processes
- PHP 7.2+ knowledge with understanding of namespace and class-based architecture
- Port 9501 available for HTTP server or ability to modify port mapping
- Basic understanding of asynchronous programming concepts and coroutines
- Familiarity with PHP composer for managing Swoole-compatible packages
- Application code designed for stateful operation as variables persist between requests

## docker-compose.yml

```yaml
services:
  swoole:
    image: phpswoole/swoole:latest
    container_name: swoole
    restart: unless-stopped
    volumes:
      - ./app:/var/www/html
    ports:
      - "9501:9501"
    networks:
      - swoole-network

networks:
  swoole-network:
    driver: bridge
```

## .env

```bash
# Swoole HTTP server
```

## Usage notes

- Docs: https://wiki.swoole.com/
- Coroutine-based PHP - async without callback hell
- 10-100x faster than php-fpm for many workloads
- Built-in HTTP server, WebSocket, TCP, UDP support
- Connection pooling for MySQL, Redis, PostgreSQL
- Compatible with Laravel (Octane), Hyperf, and other frameworks

## Troubleshooting

- Fatal error: Class 'Swoole\Http\Server' not found: Ensure phpswoole/swoole image is used instead of standard PHP images
- Connection refused on port 9501: Verify Swoole server is binding to 0.0.0.0 instead of localhost in server configuration
- Memory leaks causing worker restarts: Implement proper variable cleanup and avoid circular references in request handlers
- Database connection errors after idle time: Configure connection pool with proper heartbeat settings to maintain persistent connections
- Session data not persisting between requests: Replace PHP's default session handling with Swoole Table or Redis-based storage
- Composer autoloader conflicts: Use Swoole-compatible autoloaders or manually require files before server startup

