laravel-octane

Auto-invoked skill

High-performance with Swoole, RoadRunner, or FrankenPHP

Trigger Keywords

This skill automatically activates when Claude detects these keywords:

octane swoole roadrunner frankenphp high performance concurrent

Overview

The laravel-octane skill provides expertise for supercharging Laravel applications using Octane with Swoole, RoadRunner, or FrankenPHP for dramatically improved performance through application server persistence.

What This Skill Provides

  • Server Setup - Install and configure Octane with your preferred server
  • Concurrent Tasks - Run tasks in parallel
  • Caching - In-memory caching and tables
  • WebSockets - Real-time with Swoole WebSockets
  • Best Practices - Avoiding memory leaks and state issues

Quick Start

# Install Octane
composer require laravel/octane

# Install with Swoole
php artisan octane:install --server=swoole

# Or with RoadRunner
php artisan octane:install --server=roadrunner

# Or with FrankenPHP
php artisan octane:install --server=frankenphp

# Start server
php artisan octane:start

Configuration

// config/octane.php
return [
    'server' => env('OCTANE_SERVER', 'swoole'),

    'swoole' => [
        'options' => [
            'worker_num' => env('OCTANE_WORKERS', 4),
            'task_worker_num' => env('OCTANE_TASK_WORKERS', 6),
            'max_request' => 500, // Restart worker after N requests
        ],
    ],

    'watch' => ['app', 'routes', 'config'],
    'garbage' => 50, // Clean up after N requests
];

Concurrent Tasks

use Laravel\Octane\Facades\Octane;

// Run tasks concurrently
[$users, $products, $orders] = Octane::concurrently([
    fn () => User::all(),
    fn () => Product::all(),
    fn () => Order::recent()->get(),
]);

// With timeout
$results = Octane::concurrently([
    fn () => $this->fetchFromApi(),
    fn () => $this->fetchFromDatabase(),
], 5000); // 5 second timeout

Swoole Tables (In-Memory)

// Define table in config/octane.php
'tables' => [
    'cache' => [
        'columns' => [
            ['name' => 'value', 'type' => Octane::TABLE_COLUMN_STRING, 'size' => 1000],
        ],
        'rows' => 1000,
    ],
],

// Use in application
use Laravel\Octane\Facades\Octane;

Octane::table('cache')->set('key', ['value' => 'data']);
$row = Octane::table('cache')->get('key');

Avoiding Memory Leaks

// BAD: Static properties persist between requests
class BadService
{
    public static array $cache = []; // Will grow forever!
}

// GOOD: Use request-scoped instances
class GoodService
{
    private array $cache = [];

    public function __construct()
    {
        $this->cache = []; // Fresh per request when resolved
    }
}

// GOOD: Flush after resolving
$this->app->resolving(SomeService::class, function ($service) {
    $service->flush();
});

Listeners

// app/Providers/AppServiceProvider.php
use Laravel\Octane\Events\RequestReceived;
use Laravel\Octane\Events\RequestTerminated;

public function boot(): void
{
    Octane::on(RequestReceived::class, function ($event) {
        // Prepare for new request
    });

    Octane::on(RequestTerminated::class, function ($event) {
        // Clean up after request
    });
}

Production Deployment

# Supervisor configuration
[program:octane]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan octane:start --server=swoole --host=0.0.0.0 --port=8000
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/html/storage/logs/octane.log

# Reload workers (zero-downtime)
php artisan octane:reload

Common Pitfalls

  • Static properties - Persist between requests, causing memory leaks
  • Singleton bindings - May hold stale state
  • Global state - Avoid global variables
  • File uploads - Ensure temp files are cleaned
  • Database connections - May need pooling with Swoole

Best Practices

  • Use --watch in development for auto-reload
  • Set max_request to recycle workers periodically
  • Avoid static properties that accumulate data
  • Use octane:reload for zero-downtime deploys
  • Test thoroughly for memory leaks before production
  • Monitor memory usage per worker

Related Skills