Weave Code
Laravel Bridge Laravel Package
roadrunner-php/laravel-bridge
Laravel Bridge for RoadRunner integrates the high-performance RoadRunner application server with Laravel. It bootstraps Laravel per worker and supports HTTP, queues, logging, metrics, and PSR-7 responses for faster, persistent-worker apps.
Complete Laravel integration for RoadRunner with support for HTTP, Jobs, gRPC, and Temporal plugins - going beyond Octane's capabilities
Frequently asked questions about Laravel Bridge
- What is roadrunner-php/laravel-bridge and how does it differ from Laravel Octane?
- It is the official integration layer between Laravel and RoadRunner, a Go-based PHP application server that replaces the php-fpm request lifecycle with long-lived PHP workers. Beyond HTTP serving, it provides Laravel-native adapters for RoadRunner's queue (jobs) plugin, KV cache store, gRPC and HTTP worker modes, plus optional Temporal workflow support. That breadth is what the package positions as going beyond Octane's capabilities, which are primarily focused on application server bootstrapping.
- How do I install roadrunner-php/laravel-bridge in a Laravel application?
- Install it with Composer; the package supports Laravel package auto-discovery, so the service provider registers without manual wiring. You then split configuration between Laravel config files and RoadRunner's .rr.yaml, and you must have the RoadRunner Go binary present in your deployment image. The README includes a refreshed installation walkthrough that covers the worker bootstrap and the required RoadRunner configuration.
- Which Laravel and PHP versions does the 6.6.x line officially support?
- The 6.6.x line targets Laravel applications running PHP 8.2 or newer on the persistent-worker runtime. Because exact Laravel framework constraints can shift between minor releases, verify the current composer.json require block and the release notes for 6.6.2 before pinning. Treat that compatibility check as a prerequisite step in your upgrade plan rather than an assumption.
- Do I need the RoadRunner binary installed in production?
- Yes. RoadRunner is a Go application server, so the binary has to be built or copied into your deployment image; the Composer package only supplies the PHP-side integration. That also means someone on the team owns the binary version, the .rr.yaml configuration, and worker sizing as a standing operational responsibility. Running the same container as stock php-fpm is not possible without a separate image or fallback path.
- How does the queue integration work and what changed in version 6.6.2?
- The bridge supplies Laravel job adapters for RoadRunner's jobs plugin, letting you run queue workloads without a separate broker in some setups. In 6.6.2, the release() delay is now correctly converted to seconds, so any code that compensated for the previous incorrect unit will silently change retry cadence. Also, WorkerOptions::$maxTries falling back to 10 when null means jobs that previously had an unbounded try count now stop after ten attempts. Array backoff is now honored on failed-job release, and failing jobs without an exception are handled correctly.
- Is my existing Laravel codebase safe to run under persistent workers?
- Only if the application is worker-safe: no leaked singletons, no per-request globals, and no assumptions about process isolation between requests. Long-lived workers mean state that was harmless under php-fpm can persist and corrupt subsequent requests. Audit request-scoped services, static caches, and in-memory registries before migrating, and load test under realistic concurrency. This is an infrastructure decision as much as a library decision.
- Can I use Temporal workflows with Laravel through this package?
- Yes, Temporal support is included as an optional path in the bridge, enabling durable orchestration for long-running work. It is materially more work than the HTTP or queue modes and should be treated as a separate initiative rather than part of an initial migration. Expect additional operational concerns around activity error propagation, since 6.6.2 now rethrows exceptions from failed activities instead of swallowing them.
- How is configuration split between Laravel config and .rr.yaml?
- Laravel-side configuration lives in the usual config files published by the package, while server-level settings such as worker counts, plugins, and transport options live in RoadRunner's .rr.yaml. Both must stay in sync, which is why the .rr.yaml file should be version-controlled alongside application config. Changes to one side without the other are a common source of confusing startup failures.
- What is the rollback story if we adopt RoadRunner and hit problems?
- Plan for rollback before you migrate: keep a php-fpm image available so you can run it behind the same load balancer as a fallback. Rehearse the switch as part of your rollout, and pin the bridge version explicitly rather than floating, so an unexpected patch cannot change queue or cache semantics mid-incident. The 6.6.2 fixes to retry delay units and try-count defaults are behavioral changes even on a patch release.
- Is the package actively maintained and production ready?
- The 6.6.2 release includes seven bug fixes, a documentation refresh, and a PHPStan-max refactor, which are reasonable signals of active maintenance and reduced onboarding friction. It is used as the official integration layer for RoadRunner with Laravel, so it is production-oriented. The main caveat is that production readiness depends on your team owning worker lifecycle semantics, the RoadRunner binary version, and load testing for your specific workload.
Weaver
How can I help you explore Laravel packages today?