Octane Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/octane
   php artisan octane:install
   

   Choose your preferred server (FrankenPHP, Swoole, RoadRunner, or OpenSwoole) during installation.

2. First Run:

   php artisan octane:start
   

   Access your app via http://localhost:8000 (default port).

3. Verify: Check logs for worker initialization:

   tail -f storage/logs/octane.log
   

First Use Case: Benchmarking

Compare response times between traditional php artisan serve and Octane:

# Traditional
ab -n 1000 -c 10 http://localhost:8000/

# Octane
ab -n 1000 -c 10 http://localhost:8000/

Expect 5-10x faster response times under concurrent load.

Implementation Patterns

Core Workflows

1. Server Selection

• FrankenPHP: Best for PHP 8.2+ (built-in HTTP/2, Brotli, and file watching).

  php artisan octane:install --server=frankenphp
  

• RoadRunner: Ideal for microservices or Dockerized setups.

  php artisan octane:install --server=roadrunner
  

• Swoole/OpenSwoole: For ultra-low latency (requires PHP Swoole extension).

2. Configuration

Customize in config/octane.php:

'workers' => [
    'connections' => [
        'http' => [
            'options' => [
                'max_connections' => 100, // Default: 50
                'max_requests' => 1000,  // Default: 0 (unlimited)
            ],
        ],
    ],
],

3. Dependency Injection

Leverage Octane’s Boost for high-performance DI:

use Laravel\Octane\Boost;

class MyService {
    public function __construct(
        private Boost $boost,
    ) {}

    public function resolve() {
        return $this->boost->resolve(MyOtherService::class);
    }
}

4. Concurrent Tasks

Offload blocking operations:

use Laravel\Octane\Facades\Octane;

Octane::concurrently(function () {
    // Fire-and-forget task
    dispatch(new ProcessHeavyTask);
});

5. Hot Reloading

Enable during development:

php artisan octane:start --watch

• FrankenPHP: Built-in file watching (no extra config).
• RoadRunner/Swoole: Use chokidar (configured in octane.php).

Integration Tips

With Docker

Use the Dockerfile template from Octane’s docs:

FROM laravel/octane:frankenphp-8.2

WORKDIR /var/www/html
COPY . .

RUN composer install --optimize-autoloader --no-dev

With Vite/Laravel Mix

Octane automatically flushes Vite’s per-request state:

// vite.config.js
export default defineConfig({
    server: {
        watch: {
            usePolling: true, // Required for Octane's file watcher
        },
    },
});

With Queues

Use Swoole’s async workers for queue listeners:

php artisan octane:install --server=swoole --with-queue-worker

Configure in config/octane.php:

'workers' => [
    'queue' => [
        'options' => [
            'worker_num' => 4, // Match CPU cores
        ],
    ],
],

With Testing

Mock Octane in PHPUnit:

use Laravel\Octane\Testing\Concerns\InteractsWithOctane;

class MyTest extends TestCase {
    use InteractsWithOctane;

    public function test_with_octane() {
        $this->actingAsOctane();
        // Test logic...
    }
}

Gotchas and Tips

Pitfalls

1. Memory Leaks

• Symptom: Workers crash with Allowed memory size exhausted.
• Fix:
  • Set max_requests in octane.php to force worker recycling:

    'max_requests' => 1000,
    

  • Use --memory-limit flag:

    php artisan octane:start --memory-limit=512M
    

2. File Watching Issues

• Symptom: Changes not detected in development.
• Fix:
  • Exclude node_modules and vendor from watch list:

    'watch' => [
        'exclude' => [
            'node_modules',
            'vendor',
            'storage/*',
        ],
    ],
    

  • For FrankenPHP, ensure APP_DEBUG=true in .env.

3. Database Connection Persistence

• Symptom: Connections leak across requests.
• Fix:
  • Use DB::disconnect() in middleware:

    public function terminate(Request $request) {
        DB::disconnect();
    }
    

  • For Swoole, enable reset_on_exit:

    'connections' => [
        'http' => [
            'options' => [
                'reset_on_exit' => true,
            ],
        ],
    ],
    

4. CORS Headers Missing

• Symptom: Preflight requests fail.
• Fix:
  • Ensure middleware is registered before Octane’s HandleRequests:

    Octane::serving(function () {
        $app->middleware(Cors::class);
    });
    

5. RoadRunner-Specific Quirks

• Symptom: Streams/generators fail.
• Fix:
  • Use RoadRunner\Worker::getStdout() for logging:

    public function onWorkerStart() {
        $this->getStdout()->write("Worker started\n");
    }
    

  • Avoid dd() or dump() in Octane (use Log::debug() instead).

Debugging Tips

Log Inspection

• Check Octane-specific logs:

  tail -f storage/logs/octane.log
  

• Enable verbose mode:

  php artisan octane:start --verbose
  

Worker Inspection

• FrankenPHP: Access admin panel at http://localhost:2323.
• RoadRunner: Use rr get-stats CLI command.
• Swoole: Check worker stats via:

  \Swoole\Runtime::stats();
  

Common Errors

Extension Points

1. Custom Workers

Extend Laravel\Octane\Worker:

use Laravel\Octane\Worker;

class CustomWorker extends Worker {
    protected function handle(): void {
        $this->app->make(MyCustomHandler::class)->handle($this->request);
    }
}

Register in config/octane.php:

'workers' => [
    'custom' => [
        'class' => \App\Octane\CustomWorker::class,
    ],
],

2. Middleware Hooks

Inject middleware dynamically:

Octane::serving(function () {
    $app->pushMiddleware(MyOctaneMiddleware::class);
});

3. Server-Specific Tweaks

• FrankenPHP: Override Caddyfile via CADDY_EXTRA_CONFIG:

  CADDY_EXTRA_CONFIG=@extra config/octane/frankenphp/Caddyfile
  

• RoadRunner: Customize rr.yaml:

  server:
    command: "php artisan octane:start --server=roadrunner"
    env:
      APP_ENV: production
  

4. Boost Optimization

Profile DI resolution:

use Laravel\Octane\Boost;

$boost = app(Boost::class);
$boost->profile(function () {
    return resolve(MyHeavyService::class);
});

Pro Tips

• For Production:
  • Use --daemon mode: