Under PHP-FPM, what does fastcgi_finish_request() do, and what are its pitfalls when used for background work?

## What it does `fastcgi_finish_request()` is a function provided by the **PHP-FPM SAPI** (it is declared in FPM's own stub, not in a general extension). Its signature is: ```php fastcgi_finish_request(): bool ``` When called, it: 1. flushes every active output buffer and sends the HTTP headers; 2. ends the FastCGI request, so the web server can finish the HTTP response and the browser stops waiting; 3. returns `true` — or `false` if the request had already been finished. The PHP script **does not stop**. Code after the call runs as usual, invisibly to the user. The PHP manual describes the use case as time-consuming tasks performed "without leaving the connection to the client open" — video conversion or statistics processing in its examples. ```php <?php declare(strict_types=1); echo json_encode(['status' => 'accepted']); session_write_close(); // release the session lock first fastcgi_finish_request(); // the client gets its response now $mailer->sendReceipt($order); // runs after the response $stats->record($order); ``` ## Pitfall 1: the worker is still busy A PHP-FPM worker handles one request at a time, and it stays **busy** until the script ends — the response being finished changes nothing for FPM's accounting. If post-response work takes 5 seconds, every such request holds a worker for 5 seconds; under load that uses up `pm.max_children` just as a slow page would, and new requests queue. Worse, the pool's `request_terminate_timeout` is **not** engaged after `fastcgi_finish_request()` unless `request_terminate_timeout_track_finished = yes` is set, so a hung post-response task can hold a worker far longer than any page could. ## Pitfall 2: locks outlive the response - A **session** started with `session_start()` keeps its file lock until the script ends or `session_write_close()` is called. The user's next request, blocked on the same session, hangs — even though the previous page "finished". Close the session before calling `fastcgi_finish_request()`. - Database transactions and file locks held by the script are held for the extra time too. ## Pitfall 3: output and errors go nowhere After the call the client is gone: - `echo`, `header()` and `http_response_code()` no longer reach the browser; the response is already complete. - If the background part fails, the user saw a success message anyway. Errors must be logged, and anything that must succeed needs retries — which the request has no mechanism for. ## Pitfall 4: portability Because the function exists only under PHP-FPM, code that also runs under the CLI (tests, queue workers) or another SAPI must guard it: ```php if (function_exists('fastcgi_finish_request')) { fastcgi_finish_request(); } ``` Some other SAPIs offer their own equivalent functions, but they are separate APIs. ## The capacity arithmetic A pool's throughput is roughly workers divided by the time each request holds a worker. With 20 workers and pages that take 100 ms, the pool can serve about 200 requests per second. Add 400 ms of post-response work to every request and each worker is held for 500 ms: capacity falls to about 40 requests per second, although every user still sees a 100 ms response. That hidden cost is why post-response work must stay short. ## When to use it and when not | Situation | Suitable? | |---|---| | A few hundred milliseconds of logging or cache warming | Yes | | Sending one notification where loss is tolerable | Usually | | Seconds of work on every request | No — it drains the worker pool | | Work that must succeed or be retried | No — use a job queue | | Long jobs (exports, media processing) | No — a queue and a CLI worker | A **job queue** (a database table, an in-memory list or a message broker consumed by CLI workers) moves the work out of the FPM pool entirely: web workers return immediately, the job runs with its own concurrency limit, and failures can be retried and monitored. `fastcgi_finish_request()` is the lightweight option for small, best-effort tasks. ## Related behaviour - **`register_shutdown_function()`** callbacks still run at the end of the script, after the post-response work. - **No arguments.** The function takes no parameters; passing one throws an `ArgumentCountError`. - **Calling it twice** is harmless: the second call returns `false` because the request is already finished.