PHP Error Handling

When to use

• The user must release a resource (file handle, lock, transaction) whether or not an exception is thrown on PHP 8.0+.
• The user needs domain-specific exceptions that callers can catch selectively on PHP 8.0+.
• The user wants to catch a low-level exception (PDO, cURL) and rethrow it as a domain exception without losing the cause on PHP 8.0+.

When NOT to use

• Do not use this skill for ordinary control flow where a missing or absent value is an expected outcome, not a failure.
• Do not use this skill when the intent is to suppress errors with @ or an empty catch to make a symptom disappear.

Core guidance

• Catch the most specific exception type — Catch the narrowest exception type that you can actually handle (catch (PaymentDeclinedException $e)), not a blanket catch (\Throwable $e).
• Root the hierarchy in a marker base exception — Give each bounded context one base exception (abstract class OrderException extends \RuntimeException) and extend it for specific failures.
• Release resources in finally, not in each path — Put resource release (close handle, unlock, roll back) in a finally block so it runs once on both the success and exception paths.

Quick recipe

1. Declare one abstract or concrete base exception per bounded context extending an SPL type (class OrderException extends \RuntimeException). (verify: Callers can catch (OrderException $e) for any order-domain failure)
2. Extend the base for each distinct failure and add static named constructors (PaymentDeclined::forOrder($id)) that build a rich message. (verify: Each failure type is catchable on its own and carries context in its message)
3. At integration boundaries, catch the low-level exception and rethrow the domain type passing the original as $previous; catch the domain base at the top-level handler. (verify: Logs show the domain exception with the original cause preserved via getPrevious())

Best practices

• When rethrowing, pass the caught exception as the third $previous constructor argument (throw new OrderException('...', 0, $e);) rather than discarding it
• Give a function that always throws or exits the never return type (function fail(string $m): never) so callers and analyzers know it does not return

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. catch(Exception) misses Error types — catch (\Exception $e) does not catch \Error subtypes (TypeError, UnhandledMatchError), because both extend \Throwable, not \Exception. Fix: Catch \Throwable at a top-level boundary when you genuinely must handle both exceptions and errors; otherwise catch the specific exception types you can recover from.
2. Rethrowing without the previous exception — Catching a low-level error and throwing a new one without passing $previous drops the original stack trace and root cause. Fix: Always pass the caught exception as the third constructor argument (throw new DomainException('...', 0, $e);) so getPrevious() retains the cause.
3. Empty catch block silently swallows failures — A catch (\Throwable $e) {} with an empty body discards the error and lets execution continue as if nothing failed. Fix: Handle, log, or rethrow the exception; if catching truly is intentional (e.g. optional cache warm-up), log at minimum and document why it is safe to ignore.

Version notes

• never return type added in PHP 8.1 (PHP >=8.1) — The never return type, for functions that always throw or exit, is available from PHP 8.1; on 8.0 and earlier express the intent only with a @return never docblock.

Security

• Do not leak exception details to clients — Never render raw exception messages, stack traces, SQL, or file paths to end users; log the full detail server-side and return a generic message with a correlation id.

Testing

• Activation and decision behavior are verified in eval/scenarios/php/error-handling.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: php/enums, php/match-expression