Types & Error Handling

A warning or notice is a diagnostic: the engine reports it and execution carries on. A fatal error stops the script outright. An exception is an object you throw; it unwinds the stack until a matching catch handles it, and if nothing does, it ends the script as a fatal error.

An attribute is structured metadata written as #[Route('/users')] above a class, method, property or parameter. The engine parses it and stops there — you read it via Reflection: getAttributes() returns the declarations and newInstance() builds the attribute object. An attribute class carries #[Attribute].

?int is shorthand for int|null — the same type, the same runtime check. The difference is reach: ? prefixes exactly one type, so a nullable union of two types must be spelled out as int|string|null. The two forms may not be mixed, and ?int|string is a parse error.

Throwable is the interface every throwable implements. Below it sit two separate branches: Exception for application failures you are meant to handle, and Error for engine faults such as TypeError. So catch (Exception $e) never catches an Error — catch Throwable for both.

A union accepts a value matching any one of the listed types and rejects the rest with a TypeError at the boundary. int|string takes an int or a string but not null — allowing null means writing int|string|null. The check happens at the call site, on every call, at runtime.

PHP 7 turned most engine faults into thrown Error objects — a method call on null, a TypeError, a DivisionByZeroError — so catch (\Error) or catch (\Throwable) handles them. What stayed a true fatal is what the engine cannot continue from: memory exhaustion, a time-limit abort, a parse error.

Base the hierarchy on how the CALLER must react, not on where the failure arose. Publish one base exception (or a marker interface) the whole module throws, so a caller can catch the module without knowing it. Split only where the handling differs. Carry the decline code as a typed property, never inside the message.

It changes only scalar type declarations, per file, and the deciding file is the one making the CALL — not the one declaring the function. So a strict file calling a coercive library is still checked strictly, and a coercive caller into your strict library still gets coercion.

An intersection accepts only a value that satisfies every listed type at once — an object implementing both Countable and Iterator. Only class and interface names may appear in one; scalars, null and array are rejected, so int&string is a compile error. It arrived in PHP 8.1.

never says the function never returns to its caller: it either throws, calls exit(), or loops forever. It is not void — a void function does return, just with no value. Analysers treat the code after such a call as unreachable, and a return inside a never function is an error.

A docblock is a comment: the engine throws it away, so every framework had to re-parse the source text with its own regex, and a typo failed silently. An attribute is real syntax — parsed by the engine, resolved as a class name, autoloaded, and exposed through Reflection. A misspelled attribute class is an error you can find.

The return value is evaluated and set aside, then finally runs, then the function returns. So finally always executes — on a normal return, on an exception, and on a break. If finally itself returns, its value overrides the one from try, and an exception thrown in try is discarded.

set_error_handler() intercepts the engine's diagnostics — warnings and notices — not exceptions, and not a fatal error, which it cannot recover from. Handlers usually rethrow them as ErrorException, so one try/catch covers both worlds and a warning can no longer be ignored.

PHP allows covariant return types and contravariant parameter types, both enforced by the engine at compile time. An override may narrow the return — return Dog where the parent returned Animal — and may widen a parameter, accepting Animal where the parent took Dog. The rule is Liskov substitution.

#[\NoDiscard] marks a function whose return value must be used. Calling it and throwing the result away emits a Warning at runtime, so a forgotten result stops being silent. When discarding really is intended, the new (void) cast silences it: (void) $conn->close();.

Handle it once, at the framework boundary: a single handler that catches \Throwable, so engine Errors are covered too. Controllers catch only what they can genuinely recover from. The handler maps the exception to a status code and a stable error shape, attaches a correlation id it also returns to the user, and logs that id with the trace and request context.

Roll it out file by file, starting at the LEAVES — the directive is decided by the CALLING file, so enabling it in a leaf that calls little turns almost nothing into a TypeError. Find the coercions ahead of production with static analysis plus the test suite run in strict mode. Where a function honestly takes both, declare int|string and normalise inside it.