- What is nyatmeat/roadrunner-bundle and what does it do?
- It is a Composer package that lets you run a Laravel application on top of RoadRunner's persistent-worker runtime instead of the classic PHP-FPM request model. It handles the worker bootstrap, ships configuration you can publish and edit, and registers Artisan commands for serving and managing the application. The goal is faster throughput and lower bootstrap overhead per request.
- How do I install nyatmeat/roadrunner-bundle in a Laravel app?
- Install it with Composer using composer require nyatmeat/roadrunner-bundle, then publish its configuration so you can tune worker and server settings. Laravel's package auto-discovery normally registers the service provider for you; if not, add the provider to your providers list manually. After that, run php artisan list and look for the roadrunner commands to confirm the package is wired up.
- Which Laravel and PHP versions does this package support?
- Support depends on the version you install, so check the require constraints in the package's composer.json before adopting it. As a rule, you need a modern PHP 8.x runtime plus the RoadRunner binary available on the machine. If you are on an older Laravel release, test on a branch first or pin to a package version whose constraints match your framework.
- How is this different from Laravel Octane?
- Octane is Laravel's own first-party server abstraction with support for several runtimes, including RoadRunner. This bundle is a narrower, package-level integration that focuses on RoadRunner alone, providing its own worker bootstrap, configuration, and management commands. Choose Octane if you want one unified API across runtimes; choose this package if you want a lightweight, RoadRunner-specific setup.
- Which Artisan commands does it add and how do I start the worker?
- The package registers Artisan commands for serving the application under RoadRunner and for managing the worker lifecycle. Run php artisan list and filter on roadrunner to see the exact command names available in your installed version, since they can change between releases. Start the server through that command rather than calling the RoadRunner binary directly so Laravel bootstrapping stays consistent.
- How do I configure the worker and the RoadRunner server?
- Publish the package configuration file and adjust worker counts, environment, and runtime options for your application. RoadRunner's own server behavior is controlled through its .rr.yaml file, which defines the server, logging, and worker command settings. Keep both files in version control so deployments and local development use identical runtime configuration.
- Is it production ready and how do I keep the worker running reliably?
- It is intended for production use, but like any persistent-worker setup it needs proper process supervision. Run the start command under systemd or Supervisor so the process restarts automatically, and set restart policies on failure. Plan for graceful restarts on deploys, log worker output somewhere durable, and monitor memory growth over long runs.
- Do I need the RoadRunner binary installed separately?
- Yes. The Composer package bootstraps and configures your Laravel app, but the roadrunner binary itself has to be present on the server or in your build image. Install it through your deployment tooling or a Composer binary plugin, then verify the path in your configuration matches where it actually lives. Container images should bake the binary in so production never depends on a runtime download.
- What persistent-worker pitfalls should I watch out for?
- Because workers stay alive between requests, static properties, service container state, and open database connections can leak across requests. Avoid mutable global state, reset singletons when needed, and make sure connections are refreshed or reconnected after long idle periods. Test long-running behavior specifically, since bugs that never appear under PHP-FPM can surface here.
- How do I test my application when it runs under RoadRunner?
- Your normal PHPUnit or Pest suite runs the framework in-process, so it does not exercise the RoadRunner runtime and generally works unchanged. Use it to catch regressions from refactoring for persistent workers, and add integration tests that hit the running server for smoke coverage. Also test a full worker restart cycle before deploying to production.