Laravel Bridge Laravel Package

Getting Started

Assessment as of 6.6.2. This is a patch release focused on queue, cache, and Temporal correctness; no breaking changes are called out.

Minimal steps:

1. Install the bridge with Composer: composer require roadrunner-php/laravel-bridge.
2. Install/configure RoadRunner and create .rr.yaml; point server.command at the bridge worker entrypoint documented in the refreshed README.
3. Publish or verify config/roadrunner.php; set queue/cache connections and worker options explicitly.
4. Start RoadRunner with rr serve and verify a simple Laravel route.
5. First production use case: serve HTTP through RoadRunner, then migrate queue workers and cache operations once the request lifecycle is stable.

Look first at:

• The refreshed README installation/examples.
• config/roadrunner.php for worker, queue, cache, and Temporal settings.
• .rr.yaml for RoadRunner server/worker configuration.
• RoadRunnerJob and WorkerOptions when debugging queue retry/backoff behavior.

Implementation Patterns

• HTTP serving: Keep normal Laravel routes, controllers, middleware, and validation. Treat the worker as long-running: avoid mutable static/singleton state and reset request-scoped services between requests.
• Queue jobs: Configure a RoadRunner-backed queue connection, then dispatch standard Laravel jobs with ShouldQueue. Prefer explicit $tries, $backoff, and $timeout on jobs instead of relying on worker defaults.
• Job release/retry: Use Laravel’s seconds-based delay semantics with release(). In 6.6.2 the bridge converts release delay to seconds correctly; remove any millisecond workaround if you added one.
• Backoff arrays: If WorkerOptions::$backoff is an array, the bridge now honors it when releasing failed jobs. Use per-attempt backoff arrays for jobs with external dependencies.
• Cache: Use Laravel’s cache API through the RoadRunner-backed store. 6.6.2 preserves remaining TTL on increment/decrement, so counters with expiry behave like other Laravel stores.
• Temporal: Keep activities as Laravel services and let exceptions propagate. 6.6.2 rethrows exceptions from failed activities, which is usually what you want for Temporal retry/error semantics.
• Worker configuration: Set WorkerOptions::$maxTries explicitly. If it is null, 6.6.2 falls back to 10 max tries.
• Deployment: Cache Laravel config in production, restart RoadRunner workers on deploy, and monitor worker memory/connection health.

Gotchas and Tips

• Long-running process state: The most common failure mode is stale container/static state. Do not assume a fresh PHP process per request; reset or avoid stateful singletons.
• Release delay units: 6.6.2 fixes release() delay conversion to seconds. If you previously multiplied or divided delays to compensate, re-test and remove the workaround.
• Max tries fallback: A null WorkerOptions::$maxTries now means 10. Set it deliberately to match your job policies; otherwise jobs may retry more than expected.
• Array backoff: Verify failed-job backoff behavior after upgrading, especially if you rely on attempt-specific delays.
• Jobs failing without exceptions: 6.6.2 handles failing RoadRunnerJob instances without an exception. Ensure your logging/monitoring still captures failed jobs, since there may be no exception object to inspect.
• Non-object payloads: 6.6.2 tolerates non-object task payloads in RoadRunnerJob. Validate job payload shape in your job constructors rather than relying on the bridge to reject it.
• Temporal activity errors: Exceptions are rethrown from failed activities. Catch only where your workflow semantics require it; otherwise let Temporal retry/fail correctly.
• Cache TTL: Test increment/decrement on keys with expiry after upgrading. The fix is important for rate limiters, counters, and locks that depend on TTL.
• Debugging: Use RoadRunner logs (rr serve -v), Laravel logs, php artisan queue:failed, and worker restart commands. Check config/roadrunner.php and .rr.yaml together when behavior differs between local and production.
• Extension points: Custom cache stores, job payload mapping, Temporal activity registration, and worker options are the main places to adapt the bridge to application-specific needs. Keep those integrations covered by tests.