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:

   php artisan octane:start
   

   Your Laravel app now runs as a high-performance server. Access it via http://localhost:8000 (default port).

3. Key Files to Review:

   • octane.php (config file in config/)
   • .octane/ directory (generated server configs)
   • artisan commands (octane:start, octane:stop, octane:install)

Implementation Patterns

Daily Workflow

1. Development Workflow:

   • Use php artisan octane:start for local development.
   • Leverage hot-reloading (enabled by default) to avoid manual restarts during code changes.
   • Access logs via php artisan octane:logs.

2. Server-Side Patterns:

   • Concurrency: Use Octane::concurrently() for parallel tasks:

     Octane::concurrently([
         fn() => Task::dispatch(new ProcessPodcast()),
         fn() => Task::dispatch(new SendEmail()),
     ]);
     

   • Event Handling: Octane optimizes event dispatching. Use event:dispatch in routes or services:

     event(new OrderShipped($order));
     

3. Integration with Laravel Features:

   • Queues: Octane integrates seamlessly with Laravel Queues (Redis, Database, etc.).
   • Caching: Use Cache::remember() or Cache::tags() as usual; Octane optimizes cache operations.
   • Views: Blade templates render faster due to pre-compiled routes and optimized PHP execution.

4. Configuration:

   • Customize server behavior in config/octane.php:

     'servers' => [
         'frankenphp' => [
             'workers' => 4,
             'max_requests' => 1000,
             'options' => [
                 'php' => [
                     'opcache.enable' => '1',
                     'opcache.validate_timestamps' => '0',
                 ],
             ],
         ],
     ],
     

   • Environment variables override config values (e.g., OCTANE_WORKERS=8).

5. Deployment:

   • Use php artisan octane:install to generate server-specific configs (e.g., Caddyfile for FrankenPHP).
   • Deploy with your preferred process manager (Supervisor, Systemd) or container orchestration (Docker, Kubernetes).

Gotchas and Tips

Common Pitfalls

1. Debugging:

   • Logs: Check php artisan octane:logs for server errors. FrankenPHP logs may appear in .octane/frankenphp/logs/.
   • Dumping Data: Avoid dd() or dump() in high-traffic routes; use Octane::debug() for safe debugging:

     Octane::debug($variable);
     

   • OPcache: Ensure opcache.validate_timestamps=0 in php.ini or Octane config to avoid file-watching overhead.

2. Configuration Quirks:

   • Worker Count: Set OCTANE_WORKERS based on CPU cores (e.g., OCTANE_WORKERS=$(nproc)).
   • Memory Limits: FrankenPHP/Swoole may hit memory limits. Adjust memory_limit in php.ini or server config.
   • Static Files: FrankenPHP serves static files by default. Disable with:

     'frankenphp' => [
         'serve_static_files' => false,
     ],
     

3. Extension Points:

   • Custom Servers: Extend Octane\Server to support additional servers (e.g., Octane\Servers\CustomServer).
   • Middleware: Octane respects Laravel middleware. Add custom middleware to app/Http/Kernel.php:

     protected $middleware = [
         \App\Http\Middleware\CustomMiddleware::class,
     ];
     

   • Event Listeners: Register listeners in EventServiceProvider as usual; Octane optimizes their execution.

4. Performance Tips:

   • Route Caching: Pre-compile routes for zero-overhead routing:

     php artisan route:cache
     

   • Queue Workers: Run separate queue workers (not via Octane) for background jobs to avoid blocking HTTP requests.
   • Database Connections: Use connection pooling (e.g., pgsql:pool or mysql:pool in .env) to reduce connection overhead.

5. Debugging Tools:

   • Admin Panel: FrankenPHP provides an admin panel (e.g., http://localhost:2302). Access via:

     'frankenphp' => [
         'admin_host' => '0.0.0.0',
         'admin_port' => 2302,
     ],
     

   • Metrics: Use Octane\Metrics to track request times or memory usage:

     Octane::metrics()->record('custom_metric', 100);
     

6. Migration Tips:

   • From PHP-FPM: Replace php-fpm pools with Octane workers. Update Nginx/Apache configs to proxy to Octane’s port (default: 8000).
   • From Horizon: Octane doesn’t replace Horizon. Use Horizon for queue monitoring alongside Octane.

7. Edge Cases:

   • File Watching: Exclude node_modules, vendor, or storage/logs from file watching in .octane/watch.json:

     {
         "ignore": ["node_modules", "vendor", "storage/logs"]
     }
     

   • HTTP/2: FrankenPHP enables HTTP/2 by default. Disable with:

     'frankenphp' => [
         'http2' => false,
     ],
     

   • Github Actions: Use OCTANE_SKIP_INSTALL=true to skip installation in CI:

     OCTANE_SKIP_INSTALL=true php artisan octane:start
     

```markdown
### Debugging Workflows
1. **Worker Crashes**:
   - Check `.octane/workers/*.log` for worker-specific errors.
   - Restart workers gracefully:
     ```bash
     php artisan octane:restart
     ```

2. **Slow Requests**:
   - Profile with Xdebug or Blackfire. Octane supports both:
     ```bash
     OCTANE_XDEBUG=true php artisan octane:start
     ```
   - Use `Octane::debug()` to log slow operations:
     ```php
     $start = microtime(true);
     // ... code ...
     Octane::debug("Operation took " . (microtime(true) - $start) . "s");
     ```

3. **Configuration Conflicts**:
   - Validate configs with:
     ```bash
     php artisan octane:validate
     ```
   - Reset configs to defaults:
     ```bash
     php artisan octane:install --force
     ```

4. **Environment-Specific Issues**:
   - Use `.env.octane` for Octane-specific overrides:
     ```
     OCTANE_WORKERS=2
     OCTANE_MAX_REQUESTS=500
     ```
   - Test locally with Docker:
     ```bash
     docker run --rm -p 8000:8000 -v $(pwd):/app laravel/octane:latest
     ```