Symfony Laravel Package

Getting Started

• composer require luzrain/phpstreamserver-bundle. Note what this package actually is: a Symfony bundle (the v0.2.2 note references kernel.terminate, an HttpKernel event). In a Laravel app you do not get bundle auto-discovery — the realistic path is to run PHPStreamServer standalone behind your existing front controller, or to lift the request/upload handling rather than the bundle wiring. Read the README before committing to an integration story.
• Registration (Symfony): add the bundle to config/bundles.php, then create config/packages/phpstreamserver.yaml. Start with the smallest thing that runs — one HTTP server, one worker, pointing at the app's existing public/index.php.
• First commands: php bin/console phpstreamserver:run (plus :stop / :reload). Hit a route, then exercise an upload and confirm the temp file is gone after the response is flushed, not before.
• Look first at the compiled config (php bin/console debug:config phpstreamserver) and, for this release, grep the bundle for kernel.terminate — that listener and its new tests are the code path that changed in 0.2.2.
• Version posture: pre-1.0 (0.x). Pin the minor and read the changelog on every bump; this release is behavior-changing even though it isn't an API break.

Implementation Patterns

• Server/worker split. Config declares servers (HTTP) and workers (processes). Common day-to-day shape: one http server for web traffic, separate workers for background/job processes, SO_REUSEPORT when multiple workers share a listening port.
• Boot once, handle many. Each worker boots the kernel a single time and then serves many requests, calling terminate() after each. Anything you'd normally get "for free" from php-fpm (fresh container, fresh statics) you now have to reset explicitly.
• Upload lifecycle. The HTTP server writes the multipart body to a temp path and hands the app a normal uploaded-file object. As of 0.2.2, deletion is deferred to the kernel.terminate listener — i.e. after the response has been sent. Pattern: treat the temp file as valid only for the duration of the request; if you want to keep it, copy/move it inside the controller or a kernel.request listener and let the terminate listener no-op.
• Front controller contract. Runtime::run() is what calls $kernel->terminate($request, $response). Keep it. If you're porting the pattern to Laravel, the equivalent hook is $kernel->terminate() via app()->terminating() — register the cleanup there rather than inline in a controller.
• Dev loop. Single worker plus the debug plugin, reload workers on change instead of restarting the whole server, and watch for in-memory caches that survive the reload.
• Deploy. systemd unit or container entrypoint running phpstreamserver:run, graceful :reload for zero-downtime, worker count near CPU cores, logs to stderr.

Gotchas and Tips

• 0.2.2 changed the deletion timing. Two consequences: (1) a client can observe a response before the temp file is unlinked, so don't build consumers that assume otherwise; (2) if the kernel never reaches terminate() — fatal error in the worker, exception escaping the handler, custom front controller — the file leaks. Watch temp-dir disk usage in staging.
• Don't double-clean. Manual unlink plus the listener is harmless-but-pointless; manual unlink before a listener that still expects the file is a bug. Conversely, confirm the listener tolerates files you've already moved to permanent storage.
• Terminate listeners run after the response, so their exceptions never reach the client. Log them. Silent failures here are the classic "worker filled the disk overnight" surprise.
• Long-running state. Static properties, container singletons, Doctrine connections, Monolog buffers — all persist across requests. Reset via kernel.request/kernel.terminate listeners or recycle workers on a schedule.
• Config is compiled/cached. Restart or reload workers after config edits; debug:config shows the merged view, but a running worker still holds the old one.
• Binding. listen: 0.0.0.0:8080 vs a unix socket; SO_REUSEPORT is required for multiple workers on the same port; check for orphaned processes after :stop.
• Debugging. A 502 usually means the worker died before responding, not a PHP error in the request — read worker stderr and enable the debug/metrics plugins first.
• Extension points. Custom plugins, service tags for listeners, subclassed server/worker config. The terminate listener added here is the best small example in the codebase of how to hang behavior off the request lifecycle; its tests show how to assert cleanup without a live HTTP client.

Given the 0.x line has already shipped a behavior change in a patch release, pin exactly and treat each bump as a review item.