Cleanup with finally Blocks

A handler that opens a lock and forgets to release it on the error path does not crash — it wedges every later request that needs that lock. The bug is structural: cleanup written after the risky work runs only if the work succeeds.

$fp = fopen('/var/lock/inventory.lock', 'w');
flock($fp, LOCK_EX);

$result = updateStock($sku, $delta);   // throws? the lock below never runs

flock($fp, LOCK_UN);
fclose($fp);
return $result;

finally is the language's answer — a block that runs whenever the try is left, no matter how:

$fp = fopen('/var/lock/inventory.lock', 'w');
try {
    flock($fp, LOCK_EX);
    return updateStock($sku, $delta);   // success AND return both pass through finally
} finally {
    flock($fp, LOCK_UN);
    fclose($fp);                        // runs on success, on exception, on return
}

The exit-path matrix is worth memorizing, because it is the whole topic:

Two consequences follow. First, return inside try is safe with respect to cleanup: the returned value is computed, then finally runs, then the function actually returns — so the lock is always released before any caller observes the result. Second, the finally block is the only place cleanup belongs when multiple paths share it: writing flock/fclose after the try AND again in the catch duplicates the release in two places that drift the moment either side changes.

A try with no catch and only a finally is legal and reads precisely: "nothing to recover here, just guarantee the release". That form suits code where the caller is the designated handler — your function's job is the resource, theirs is the policy. Note also what finally is not: it is not a substitute for the handler-coverage discussion in Registering Custom Error Handlers — a notice-turned-exception still passes through your finally exactly like any throw — and it is not destructors, whose non-deterministic timing (see the pitfalls chapter) makes them the wrong tool for this job. With the mechanism fixed, the next chapter maps it onto the concrete resources PHP hands out.

Read the block fluently and the intent is unmistakable: the try is the work, the finally is the release, and no third location exists for the same cleanup — which is exactly what makes it refactor-proof. A common question at this stage — does finally delay the return? — has a precise answer: the return value is computed first, then finally runs to completion, then the value is delivered to the caller. The observable effect is that any code the finally touches still sees the function's resources alive, and any exception the finally throws replaces the pending return entirely. That last rule returns in the pitfalls chapter as one of the pattern's two sharp edges.

The finally pattern generalizes to every resource PHP tracks externally — the ones whose release cannot be left to request shutdown because something else holds them too.

File handles and locks are the teaching case because their failure mode is visible. PHP's garbage collector closes file handles eventually, but locks are process-level coordination primitives: an unreleased LOCK_EX blocks other processes (other FPM workers, cron jobs) until your handle is actually closed, not until your script forgets about it. Release order matters — flock($fp, LOCK_UN) before fclose() — since closing releases the lock anyway, but explicitness survives refactors that replace the handle mid-function.

Database transactions are the expensive case. An open transaction holds row locks and can stall unrelated writers; a half-committed one corrupts invariants:

$pdo->beginTransaction();
try {
    $pdo->exec("UPDATE accounts SET cents = cents - 500 WHERE id = 1");
    $pdo->exec("UPDATE accounts SET cents = cents + 500 WHERE id = 2");
    $pdo->commit();
} catch (\Throwable $e) {
    $failed = true;                  // marker for the finally below
    throw $e;                        // rethrow — the caller decides policy
} finally {
    if (isset($failed) && $pdo->inTransaction()) {
        $pdo->rollBack();            // exactly-once rollback, exception or not
    }
}

The inTransaction() guard is deliberate: if the exception came from beginTransaction() itself, or the commit already closed the transaction, a blind rollBack() would raise a second exception from inside finally — masking the original, as the pitfalls chapter details. Markers like $failed, or simply the inTransaction() state check, keep cleanup idempotent.

Stream contexts, curl handles, and PSR-7 responses follow the same shape with different verbs; modern PHP softens some of them — CurlHandle objects free their socket when garbage-collected, and PHP 8.0's fpm-closing of sockets at request end is a backstop, not a plan. The criterion for "does this need finally?" is one question: is anything outside this process affected until release? Locks: yes, other workers wait. Transactions: yes, other writers wait and invariants dangle. A local array: no — leave it to scope. Notice what the pattern replaces: the __destruct temptation from Magic Methods like __get and __toString. A destructor fires at non-deterministic garbage-collection time — never for objects a registry holds, moot at web-request teardown — while finally fires at a known point on a known path. For locks and transactions, known-point release is not a nicety; it is the difference between a system that recovers from errors and one that accumulates wedged state. The remaining sharp edges — returns in finally, exceptions thrown from finally, and the exit() blind spot — are exactly what the last chapter dissects.

Ownership transfer is the one case that inverts the pattern. When a function hands a resource to something that outlives it — a file handle passed into a writer object, a transaction spanning several repositories — the releaser is no longer the opener, and finally at the opening site would close a resource someone else now owns. The PHP-ecosystem convention is therefore explicit: a method that receives ownership says so in its name or docblock, and the original site's finally releases only what it still holds. Confusion here produces the two classic opposites — double release, where a finally closes a handle the callee was still using, and leak-on-success, where the happy path transfers ownership but the error path forgets. Name the owner, and the bug becomes a review comment instead of a midnight page.

The finally guarantee has edges, and each one produces a distinct, memorable bug.

A return inside finally overrides everything. If the try was returning a value or propagating an exception and the finally block also executes return, the finally's return wins — silently swallowing the exception in the process:

function findUser(int $id): ?array
{
    try {
        return $db->find($id);        // or: throw new OfflineException();
    } finally {
        return null;                  // BUG: discards the value AND swallows the throw
    }
}

The rule: a return, throw, or break inside finally cancels whatever the try or catch had pending. This is why style guides treat return in finally as a review-blocking defect — it converts your guaranteed-cleanup block into a guaranteed-silent-failure block. Cleanup code should only clean up.

An exception thrown inside finally masks the original. If the try was already unwinding with PaymentException and the finally throws (the blind rollBack() from the last chapter, a null-dereference in cleanup code), the new exception replaces the old one — and PHP 7.3+ attaches the original as $previous (you will see both in the trace as "During handling of the above exception, another exception occurred"), but many reporters surface only the top one. Treat cleanup code as hostile-environment code: guard it (if ($pdo->inTransaction())), and never let a helper's failure escape your finally unexamined.

exit() and die() skip finally entirely. They terminate the process immediately — no unwinding, no finally, no destructors-on-collection. Code that calls exit() deep in a locked section will hold that lock until the OS reclaims the handle. The fix is architectural: return an error value or throw, and confine the single legitimate exit — if any — to the outermost request layer where no resources are held. Fatal errors (OOM, parse failures in included files) have the same blind spot; that is the coverage gap log_errors and shutdown functions were enlisted for in the error-handler topic.

One composition note to finish: finally nests and composes cleanly with the rest of the toolset — catch-and-rethrow above it, error handlers converting notices into exceptions that still traverse it, and multiple finally blocks layering when scopes nest (innermost first, like try blocks everywhere). The mental model to carry forward is that PHP gives exactly one deterministic release point per scope, and it is the block named for it. What finally guarantees is that release happens; it cannot guarantee the release was recorded or diagnosed — that is the job of the last piece of the error-handling story: Logging Errors for Production.

One pattern composes the whole phase cleanly: fail loudly, clean deterministically, report once. The throw supplies the loud failure, finally supplies the deterministic release, and the outermost handler from the error-handling topics supplies a single structured report via the logger, chaining whatever context the translation layers added. Code that attempts all three inline — logging at every layer and releasing in catch blocks — produces duplicate log lines per incident and release-order bugs per refactor; code that attempts none produces silent wedges. PHP gives each job exactly one mechanism: exceptions for propagation, finally for release, handlers and loggers for reporting. Keep the three in their own lanes, and the tools of this phase stay small, composable, and hard to misuse — the mark of an API designed for failure.