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 Open Swoole) during installation.

2. First Use Case: Start Octane with your chosen server:

   php artisan octane:start
   

   For FrankenPHP (default):

   php artisan octane:start frankenphp
   

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

3. Key Files to Review:

   • octane.php (config file generated during installation)
   • .env (check OCTANE_SERVER, OCTANE_WORKERS, etc.)
   • artisan commands (octane:start, octane:stop, octane:reload)

Implementation Patterns

Core Workflows

1. Development Workflow:

   • Use php artisan octane:start in development for instant reloads on file changes.
   • FrankenPHP’s built-in file watcher (enabled by default) automatically reloads the app when files change.
   • For other servers (Swoole/RoadRunner), use php artisan octane:reload manually or via CI/CD hooks.

2. Production Deployment:

   • Configure workers and memory limits in octane.php:

     'workers' => [
         'concurrency' => env('OCTANE_WORKERS', 8),
         'memory' => env('OCTANE_MEMORY', '1G'),
     ],
     

   • Use environment variables to control server behavior:

     OCTANE_SERVER=roadrunner
     OCTANE_WORKERS=16
     OCTANE_MEMORY=2G
     

3. Concurrency Patterns:

   • Leverage Octane::concurrently() for parallel tasks:

     use Laravel\Octane\Facades\Octane;
     
     Octane::concurrently([
         fn() => dispatch(new ProcessPodcast()),
         fn() => dispatch(new SendNotifications()),
     ]);
     

   • Use Octane::task() for fire-and-forget background jobs:

     Octane::task(fn() => $this->processHeavyTask());
     

4. Server-Specific Patterns:

   • FrankenPHP:
     • Customize Caddyfile via OCTANE_CADDY_EXTRA_CONFIG:

       OCTANE_CADDY_EXTRA_CONFIG=@import /path/to/custom.conf
       

     • Enable Brotli compression by default (no config needed).
   • RoadRunner:
     • Configure via roadrunner.json (merged with Octane’s defaults).
     • Use php artisan octane:start roadrunner --config=custom.json.
   • Swoole/Open Swoole:
     • Tune worker count and memory via octane.php or .env:

       OCTANE_SWOOLE_WORKERS=auto
       OCTANE_SWOOLE_TASK_WORKERS=4
       

5. Integration with Laravel Features:

   • Queues: Octane optimizes queue workers. Use php artisan octane:queue for concurrent queue processing.
   • Horizon: Works seamlessly with Octane’s concurrency model.
   • Vite: Per-request state is flushed automatically (no manual config needed).
   • Testing: Use Octane::actingAs() for authenticated tests:

     Octane::actingAs($user)->get('/dashboard');
     

6. CI/CD Integration:

   • Use php artisan octane:test to run tests with Octane’s server.
   • Example GitHub Actions workflow:

     - name: Run Octane Tests
       run: php artisan octane:test --server=swoole --workers=2
     

Gotchas and Tips

Common Pitfalls

1. Memory Leaks:

   • Issue: Long-running Octane processes may leak memory if not managed.
   • Fix: Set OCTANE_MEMORY conservatively in production (e.g., 1G per worker).
   • Debug: Use php artisan octane:stop --force to kill stuck processes.

2. File Watcher Quirks:

   • FrankenPHP: Excludes node_modules, vendor, and .git by default. Add exclusions via:

     OCTANE_WATCH_EXCLUDES=storage/logs,bootstrap/cache
     

   • Swoole/RoadRunner: File watching is manual. Use php artisan octane:reload or integrate with nodemon/entr.

3. Configuration Overrides:

   • Issue: .env variables may not override octane.php as expected.
   • Fix: Use php artisan octane:install --keep-config to preserve custom configs during updates.

4. Database Connections:

   • Issue: Stale DB connections in containers after octane:reload.
   • Fix: Reset connections in AppServiceProvider:

     public function boot()
     {
         if (app()->runningInConsole() && !app()->runningUnitTests()) {
             DB::disconnect();
         }
     }
     

5. Streaming Responses:

   • Issue: Generators may not stream correctly with RoadRunner/Swoole.
   • Fix: Ensure responses are wrapped in StreamResponse:

     return response()->stream(fn() => yield $data);
     

6. Debugging:

   • FrankenPHP: Access admin panel at http://localhost:2019 (default port).
   • RoadRunner: Use rr get-stats to monitor workers.
   • Swoole: Check logs with php artisan octane:logs.

Pro Tips

1. Performance Tuning:

   • FrankenPHP: Enable HTTP/2 and Brotli for static assets:

     OCTANE_CADDY_EXTRA_CONFIG=encode gzip brotli
     

   • Swoole: Adjust OCTANE_SWOOLE_MAX_REQUESTS to limit worker lifespan:

     OCTANE_SWOOLE_MAX_REQUESTS=1000
     

2. Custom Servers:

   • Extend Octane with custom servers by implementing Laravel\Octane\Server:

     class CustomServer implements Server {
         public function run(): void { /* ... */ }
     }
     

   • Register via octane.php:

     'servers' => [
         'custom' => \App\Octane\CustomServer::class,
     ],
     

3. Dependency Injection:

   • Use Octane::boost() to optimize service containers:

     Octane::boost(function () {
         return new \App\Services\HeavyService();
     });
     

4. Environment-Specific Configs:

   • Load server-specific configs dynamically:

     $server = config('octane.server');
     $config = require __DIR__."/config/octane/{$server}.php";
     

5. Testing:

   • Mock Octane in tests with Octane::fake():

     Octane::fake();
     $response = Octane::actingAs($user)->get('/');
     Octane::assertConcurrentTasksRan();
     

6. Logging:

   • Redirect Octane logs to a file:

     OCTANE_LOG_CHANNEL=single
     OCTANE_LOG_FILE=/var/log/octane.log
     

7. Security:

   • Restrict admin panels (FrankenPHP/RoadRunner) to internal networks:

     OCTANE_ADMIN_HOST=127.0.0.1
     

8. Legacy Code:

   • Issue: dd() may not work as expected in Octane.
   • Fix: Use Octane::dumpAndDie() or configure FrankenPHP to handle dd():

     OCTANE_FRANKENPHP_DUMP_AND_DIE=true
     

9. Static Files:

   • Serve static files via Octane (FrankenPHP/RoadRunner) for better caching:

     Octane::serveStaticFiles();
     

10. Upgrade Notes:

    • Always back up octane.php and .env before upgrading.
    • Run composer update laravel/octane and php artisan octane:install --keep-config.