Surge Laravel Package

Getting Started

1. Install the new major: composer require <vendor>/<package>:^2.0. Confirm the PHP/Laravel constraints in composer.json before upgrading—major versions often bump minimum PHP.
2. Publish the config if you have not already: php artisan vendor:publish --tag=<package>-config.
3. Pick a driver in .env:
   • SERVER_DRIVER=frankenphp for Caddy-based worker mode
   • SERVER_DRIVER=roadrunner for the RoadRunner binary/.rr.yaml workflow
4. Start the server with the package’s start command (for example php artisan <package>:start) and hit a route that exercises the container, sessions, and database.

Where to look first

• config/<package>.php: driver selection, worker counts, warm services, listeners.
• The driver classes (src/Drivers/* or equivalent): each driver has different bootstrap and lifecycle behavior.
• The README’s driver matrix: it will tell you which binary, PHP extension, or config file each driver needs.
• Existing Octane-style docs are a useful mental model if this package wraps a similar worker runtime.

First use case

Swap a staging environment from PHP-FPM to FrankenPHP worker mode and run a smoke test against a stateful flow (login → write → redirect → read). This surfaces state-leak bugs early and gives you a throughput baseline before touching production. Keep RoadRunner configured as a fallback so you can compare behavior and isolate driver-specific issues.

Implementation Patterns

• Environment-driven driver selection. Keep the driver in .env and never hard-code it. Use FrankenPHP locally for parity with production and RoadRunner in CI or on hosts where Caddy is not available.
• Local vs. production parity. Run the same driver in dev and prod where possible. Use watch/reload flags locally; use supervised processes and graceful reloads in production.
• Container-safe services. Treat the application container as long-lived. Register bootstrappers and warm services that are safe to reuse, and explicitly flush request-scoped state between requests.
• Separate worker processes. Run queue:work and schedule:work as their own supervised processes. Do not assume the HTTP worker will process queued jobs or scheduled tasks.
• Deployment sequence.
  1. Build or install the driver binary (FrankenPHP or RoadRunner) in your image.
  2. Run php artisan config:cache and route:cache.
  3. Start the server as a non-root user.
  4. On deploy, send the package’s reload signal/command rather than killing workers abruptly.
• Custom drivers. If you need a new runtime, implement the package’s driver contract and register it in config. The v2 drivers are good reference implementations for bootstrap order and lifecycle hooks.
• Observability. Expose a health endpoint, log driver output to a known path, and track worker restarts. Worker runtimes fail differently from PHP-FPM—silent worker death is the classic failure mode.
• Incremental migration. Adopt one driver first (FrankenPHP is usually the lower-friction choice because Caddy handles TLS and static files), prove it in staging, then standardize.

Gotchas and Tips

• State leakage is the number-one risk. Singletons, static properties, and container bindings persist across requests. Audit services that cache request data and reset them via listeners or middleware.
• FrankenPHP specifics. It depends on Caddy and a matching FrankenPHP binary/PHP version. Worker mode changes how uploads, temp directories, and $_SERVER values behave. Check Caddy logs, not just Laravel logs.
• RoadRunner specifics. .rr.yaml must define the HTTP, static, and logging sections correctly. Worker counts interact with PHP memory limits; set max_jobs so workers recycle before memory grows unbounded.
• Config caching traps. php artisan config:cache bakes the driver and worker settings. Clear and rebuild after changing .env, or you will debug a phantom driver mismatch.
• Debugging checklist.
  • Run the start command verbosely (-v) and read the driver’s own logs.
  • Use php artisan about to confirm the active driver and cached config.
  • Test a stateful request twice in the same worker to detect leakage.
  • Compare behavior by switching drivers in staging—if the bug follows the driver, it is lifecycle-related.
• Extension points. Use the package’s listener/bootstrapper hooks for per-request resets, and tick-style callbacks for periodic work. Avoid doing periodic work in request handlers.
• Vague changelog risk. “Enhance and Bug fix” tells you nothing. Before upgrading, read the diff or the full CHANGELOG, pin the version in composer.json, and run your stateful smoke tests against both new drivers. Major-version releases frequently include behavior changes that are not called out in the summary.