Download the PHP package modelslab/octane-coroutine without Composer

Laravel Octane with Swoole Coroutine Support

⚡ High-performance Laravel with true coroutine support for massive concurrency

Requires the latest Swoole with coroutine hooks enabled. Older versions are not supported.

🚀 What is this?

This is an enhanced fork of Laravel Octane that adds true Swoole coroutine support, enabling your Laravel application to handle thousands of concurrent requests efficiently through non-blocking I/O.

Performance Highlights

• 360× faster than standard Octane (2,773 req/s vs 7.71 req/s baseline)
• 87× per-worker efficiency through coroutines
• Handle 20,000+ concurrent connections on a single server
• Production-tested under extreme load

⚡ The Problem with Standard Octane

Standard Octane uses a "One Worker = One Request" model. When a request performs blocking I/O (database queries, API calls, file operations), the entire worker is blocked:

With 1-second blocking operations, this means only ~8 requests/second throughput.

🎯 The Solution: Runtime Coroutine Hooks

This fork enables Swoole's coroutine runtime hooks (SWOOLE_HOOK_ALL), which automatically converts PHP's blocking functions into non-blocking, coroutine-safe versions:

With the same 1-second blocking operations, this achieves 2,773+ requests/second — a 360× improvement!

What Gets Hooked?

• ✅ sleep() → Non-blocking coroutine sleep
• ✅ file_get_contents() → Non-blocking file I/O
• ✅ curl_exec() → Non-blocking HTTP requests
• ✅ MySQL/PostgreSQL → Non-blocking database queries
• ✅ Redis → Non-blocking cache operations
• ✅ File operations → Non-blocking reads/writes

📦 Installation

Install via Composer from Packagist:

Then install Octane with Swoole:

Specific Version

Updating the Package

Tip: Pin your production deployments to specific versions:

🔧 Configuration

The package works out-of-the-box with sensible defaults. Coroutines are enabled by default with runtime hooks.

Worker Configuration

Start with appropriate worker count:

Advanced Configuration

Edit config/octane.php if needed:

Redis & Database Coroutine Safety

Coroutine mode relies on coroutine-safe IO drivers and connection handling. Recommended defaults:

Notes:

• phpredis is fastest. This fork rewrites Redis handling for coroutine safety so request-scoped Redis managers do not reuse process-shared persistent sockets.
• Predis is not included by default. If you prefer a PHP-only client, install it manually and disable persistence:
  • composer require predis/predis
  • REDIS_CLIENT=predis
  • REDIS_PERSISTENT=false
• PDO persistent connections can cause cross-coroutine contention; keep them off.
• DB pool max connections are per worker. The effective upper bound is workers × DB_POOL_MAX_CONNECTIONS, so size the pool below your database server's max_connections budget.
• Long external waits should not hold backend sockets. For AI/API workloads that wait 60-120 seconds on an upstream provider, release DB/Redis handles before the external wait whenever the request no longer needs them.
• Database connection pooling in config/database.php is separate from the HTTP runtime. The only octane.swoole.pool setting still used is the DB warning buffer above.

v0.8.7 Production Hardening

Version v0.8.7 includes the production hardening used for high-concurrency AI API workloads:

• app()->handle() subrequests now resolve the coroutine-scoped HTTP kernel/router and temporarily swap request bindings only inside the current request scope. This prevents JSON/form/base64 API subrequests from corrupting method, body, query, headers, or the outer request() helper.
• The DB pool rolls back dirty Laravel and PDO transactions before reuse.
• Idle DB sockets are pruned by heartbeat / max-idle settings.
• Worker termination releases coroutine DB connections before request scope is flushed, preventing stale pool counters after dirty requests.
• Request-scoped Redis/cache/session managers are released so sockets do not leak between coroutines.

Regression coverage for this release includes concurrent request isolation, nested API shape preservation, request-time container binding isolation, locale/translator isolation, Redis manager isolation, dirty DB transaction cleanup, and DB idle pruning.

Validated Stress Results

The v0.8.7 release was validated in Docker with host-network MySQL and Redis:

• App full suite: 1883 passed, 2 skipped, 5446 assertions.
• Package suite: 82 tests, 687 assertions.
• Fast full-stack wrk: 7912/7912 PASS, zero leaks/errors.
• Nested API app()->handle() wrk: 15860/15860 PASS, zero leaks/errors.
• Remote file parity wrk: 4049/4049 PASS, zero leaks/errors.
• Dirty DB transaction open/check wrk: 15894 dirty opens followed by 15654 clean checks at transaction level 0, zero leaks/errors.
• Mixed 0-60s full-stack wrk: 458/458 PASS, zero leaks/errors.
• Fixed-count 10k x 120s full-stack blocking IO: 10000/10000 valid JSON 200, zero leak responses.

After stress, MySQL and Redis returned to baseline (Threads_connected=1, connected_clients=1) with no container log stack traces.

🏊 Understanding Workers and Coroutines

This section clarifies the key concepts that make this fork different from standard Octane.

What are Workers?

Workers are OS-level processes spawned by Swoole. Each worker:

• Is a separate PHP process with its own memory space
• Can handle requests independently
• Is configured via --workers=N or worker_num in config

What are Coroutines?

Coroutines are lightweight, cooperative "threads" managed by Swoole at the application level (not OS-level). When a coroutine encounters blocking I/O, it yields control to other coroutines instead of blocking the entire worker.

How They Work Together

How Request Isolation Works

This runtime does not use an HTTP application pool anymore. Each Swoole worker boots one shared Laravel worker runtime, and concurrent requests are isolated by the coroutine-aware container proxy plus per-request scoped state for bindings such as request, session, router, view, log, cache, and Redis managers.

The legacy octane.swoole.pool config namespace remains only for db_max_connections_buffer, which is used by a startup safety warning.

🧪 Testing

Unit tests require a PHP build with the Swoole extension installed.

Coroutine Runtime Configuration

The package is pool-free for HTTP workers. The relevant Swoole config looks like:

OCTANE_POOL_DB_MAX_CONNECTIONS_BUFFER only affects the startup warning that checks MySQL max_connections against your configured database pool minimums.

⚡ Performance Optimization

CPU Usage and Tick Timers

Following Hyperf/Swoole best practices, this fork disables tick timers by default to prevent unnecessary CPU usage.

What are Tick Timers?

Octane can dispatch "tick" events to task workers every second. However:

• Tick is disabled by default ('tick' => false in config/octane.php)
• Task workers are set to 0 by default when tick is disabled
• This prevents 100% CPU usage from idle task workers waking up every second

Why Disable Tick?

In earlier configurations, tick timers with --task-workers=auto would create one task worker per CPU core (e.g., 12 workers on a 12-core system). Even with no traffic:

This causes high CPU usage even when the server is idle!

When to Enable Tick

Only enable tick if you have listeners for TickReceived or TickTerminated events that need to run periodically:

Then start with minimal task workers (not auto):

Task Worker Guidelines

📊 Performance Benchmarks

Real-world load testing results with wrk:

Baseline (No Coroutines)

• Workers: 8
• Result: 7.71 req/s

With Coroutines Enabled

• Workers: 32
• Result: 2,773.34 req/s
• Improvement: 360×

Per-Worker Efficiency

Each worker can efficiently handle ~87 concurrent requests thanks to coroutines!

🏗️ Architecture

Runtime Hooks

Enabled automatically on worker start:

This converts all blocking I/O to coroutine-safe operations without any code changes required.

Worker Initialization

Workers log their initialization for monitoring:

Graceful Degradation

If a worker isn't ready, requests receive 503 responses until initialization completes:

🎯 When to Use This Fork

✅ Perfect For:

• Applications with external API calls (payment gateways, third-party services)
• Database-heavy applications with long queries
• High-concurrency requirements (1,000+ concurrent users)
• Applications performing file I/O (uploads, processing)
• Any app with blocking operations that can benefit from async

⚠️ Standard Octane is Fine For:

• Purely CPU-bound operations (image processing, calculations)
• Ultra-fast responses (<50ms average)
• Low-concurrency requirements (<100 concurrent users)

🔍 Monitoring

Worker Logs

Check worker initialization in your logs:

Performance Metrics

Monitor your application:

• 5xx rate: Watch for upstream or worker errors under load
• Memory usage: ~50-200MB per worker depending on application
• Worker count: Scale based on CPU cores (typically 1-2× CPU count)
• Worker restarts: Unexpected churn usually means a fatal error or memory issue

🛠️ Production Recommendations

Resource Planning

Example: 32 workers = 3.2-6.4GB RAM

OS Tuning

For high concurrency (10,000+ connections):

Swoole Configuration

For extreme load:

🐛 Debugging

Enable debug logging to track worker behavior:

⚠️ Important Notes

• Database connections: Ensure max_connections can handle your concurrency
• Memory: Monitor usage and scale workers accordingly
• Warmup: Workers initialize automatically; allow 5-10 seconds before heavy load
• State management: Laravel's service container handles coroutine isolation automatically
• Proxy timeouts: If you're behind Nginx/ALB, set upstream read timeouts above your max request time

📈 Scaling Guide

Small (Development)

• Workers: 4-8
• Handles: ~500 concurrent requests
• RAM: 2-4GB

Medium (Production)

• Workers: 16-32
• Handles: ~2,000 concurrent requests
• RAM: 4-8GB

Large (High-Traffic)

• Workers: 32-64
• Handles: ~5,000 concurrent requests
• RAM: 8-16GB

XL (Enterprise)

• Workers: 64-128
• Handles: ~10,000+ concurrent requests
• RAM: 16-32GB

🎯 Recommended Configuration: 8-Core CPU for 10K req/sec

This section provides specific, tested recommendations for achieving 10,000 requests/second on an 8-core CPU.

Understanding the Math

Recommended Configuration

Start Command

Resource Requirements

Memory Calculation

Database Connection Pooling

Database pooling is separate from the HTTP runtime. Size it from worker count and your configured per-connection pool minimums and maximums.

For example, 8 workers × min_connections=1 means at least 8 DB connections before real traffic. OCTANE_POOL_DB_MAX_CONNECTIONS_BUFFER only adjusts the startup warning threshold for this planning.

Or configure MySQL server:

OS Tuning for 10K req/sec

Benchmark Expectations

With the above configuration on 8-core CPU:

Tuning Tips

1. Start Conservative: Begin with a modest worker count and measure under load
2. Monitor Actively: Watch memory, 5xx rates, worker restarts, and upstream saturation
3. Warm Up: Allow 30-60 seconds for workers to warm up before heavy traffic
4. Use Redis: Offload sessions and cache to Redis for better concurrency
5. Size Database Pools Separately: Prevent DB connection exhaustion independently of HTTP concurrency

📚 Resources

• Laravel Octane Documentation
• Swoole Documentation
• Coroutine Programming Guide

🤝 Contributing

Contributions are welcome! Please read the contribution guide.

🔒 Security

Please review our security policy to report vulnerabilities.

📄 License

This fork maintains the original MIT license. See LICENSE.md.

Built with ❤️ by ModelsLab

Original Laravel Octane by Taylor Otwell and the Laravel team