Rapira Symfony Bundle Laravel Package

Getting Started

• Install: composer require fluffy-discord/rapira-symfony-bundle. As of v0.2.1 the bundle requires the stable rapira/contract ^0.9.1, so you no longer need "minimum-stability": "dev" in composer.json — if you added that flag for 0.2.0, remove it.

• Wire the runtime class (this is also step 1 of the 0.1.x upgrade path, so do it explicitly even on a fresh install):

  composer config extra.runtime.class 'FluffyDiscord\RapiraBundle\Runtime\Runtime'
  composer dump-autoload
  

  If this is missing, the app boots through the normal front-controller runtime and you'll get FPM-like behaviour instead of worker mode — a very confusing "nothing changed" symptom.

• Point Rapira at your front controller. In rapira.toml:

  [http.pool]
  entrypoint = "public/index.php"
  mode = "dispatcher"
  

  The vendored worker.php is gone; public/index.php serves both FPM/dev and worker mode.

• Where to look first: the bundle's FluffyDiscord\RapiraBundle\Runtime\Runtime class (that's the seam everything goes through), your rapira.toml pool block, and public/index.php — confirm nothing in the front controller echoes or exits before the runtime takes over.

• First use case: run an existing app under Rapira and smoke-test the four things 0.2.0 rewrote — a multipart/form-data POST with a real file upload, a zero-byte upload, a cookie-carrying request, and a session write followed by a session read on a different worker request. Those are exactly the areas that regressed in 0.1.x.

Implementation Patterns

• One entrypoint, two modes. Keep public/index.php side-effect free and identical between FPM and worker mode; do environment switching in config, not in the front controller. This makes "does it break under Rapira?" a one-line diff to debug.
• Pool config lives under [http.pool]. Anything still writing [pool] (entrypoint/mode) is 0.1.x syntax and will not boot on 0.2.x. Keep the mode = "dispatcher" key — the dispatcher runner is the path that got the PHP 8.4 fix.
• Treat DB connections as long-lived. Connections stay open per worker and the bundle replaces them when the server drops them (Doctrine and PDO sessions; PostgreSQL, MySQL, MariaDB). So: don't disconnect() per request, don't cache a PDO/Connection object somewhere the bundle can't see, and don't wrap requests in a transaction you might not commit.
• Do upload work early, or in a terminate listener. 0.2.0 guarantees uploads stay readable in kernel.terminate listeners, which makes the "move the temp file after the response is flushed" pattern viable. Beyond terminate, assume the temp file is gone.
• Rely on the request-hygiene fixes. PHP sessions and stray output are reset between requests, and form bodies / upload field names / cookies / zero-byte uploads are parsed like PHP-FPM. Delete any 0.1.x shims that manually re-parsed php://input, normalised $_FILES keys, or called ob_end_clean() defensively.
• Standard header access only. Header handling was hardened in 0.2.0; don't hand-roll $_SERVER['HTTP_*'] parsing and don't trust client-supplied duplicates.
• Integration tip — compare against FPM. Because both modes share public/index.php, running the same request through php -S/FPM is the fastest way to isolate whether a bug is yours or the worker layer's.
• Laravel note: this bundle targets Symfony's HttpKernel/Symfony Runtime. Laravel is not a Symfony HttpKernel app, so there is no drop-in path — you'd be writing an adapter around Illuminate\Foundation\Http\Kernel yourself. For most Laravel teams, Octane is the lower-risk route; treat this package as interesting-but-not-yet-day-to-day for Laravel specifically.

Gotchas and Tips

• Breaking upgrade from 0.1.x — three things at once: (1) worker.php is deleted, (2) [pool] became [http.pool] with entrypoint = "public/index.php", (3) extra.runtime.class must be set and the autoloader dumped. Miss any one and you get a boot failure or a silently non-worker-mode app.
• Pre-1.0. 0.2.x is still a moving target and rapira/contract is pinned at ^0.9.1. Pin exact versions in composer.json and re-read release notes on every bump.
• No sandboxing. The bundle resets PHP sessions and stray output — it does not reset your DI container, singletons, static caches, or auth guards between requests. Anything request-scoped that you stash in the container will leak across users. This is the single biggest footgun versus Octane, which has an explicit sandbox.
• Stale connections are handled, in-flight state is not. The bundle replaces dropped connections, but an open transaction or a dirty SET/USE at drop time is your problem. Set MySQL/MariaDB wait_timeout sensibly and never leave a transaction open across a request boundary.
• kernel.terminate is the Symfony event. If you're porting Laravel code, the equivalent hooks are terminable middleware and app()->terminating(). Verify uploads survive into those on your setup before deleting the in-request file handling — the release note guarantees the Symfony event, not Laravel's.
• PHP 8.4: 0.2.0 fixed "dispatcher runner not used on PHP 8.4". If you're on 8.4, confirm you're actually in dispatcher mode; a misconfigured pool can look like the old bug.
• Debugging recipe: if a request behaves differently than under FPM, check in this order — (1) is extra.runtime.class set, (2) is the pool block [http.pool] with public/index.php, (3) is there output/session state being written before the runtime boots, (4) does the failure only appear on the second request to the same worker (classic state-leak signal).
• Test the boring uploads. Zero-byte files and files[]-style array field names were explicitly broken and fixed; add them to your smoke suite, they regress easily.