PHP Reference ยท Types and Type Handling
PHP union, intersection and nullable types
Reference for PHP complex type declarations: union types A|B, intersection types A&B, nullable ?T, DNF types (A&B)|null, and coercion rules.
A type declaration can say more than one simple type. A union type A|B accepts a value of either type. A nullable type ?A is shorthand for A|null. An intersection type A&B requires a value to satisfy all listed class or interface types at once. Since PHP 8.2 you can combine them in disjunctive normal form (DNF), such as (Countable&Traversable)|null.
These types work on parameters, return values and properties, and the engine checks them at runtime.
function show(int|string $id): string|false { /* ... */ } function size(?array $items): int { /* ... */ } function each(Countable&Traversable $box): void { /* ... */ }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
function f(int|string $x): float|false { } function g(?Foo $x = null): ?Bar { } // ?T is T|null function h(A&B $x): void { } // intersection (classes/interfaces only) function i((A&B)|null $x): void { } // DNF, PHP 8.2 public int|float $price = 0; // property types
| Rule | Detail |
|---|---|
| Union members | Any types except void and never; each type may appear once. |
| Redundant members | `bool |
| Intersection members | Only class and interface names, not built-in types such as int, null or array. |
| `A | B&C` without parentheses |
Default null |
A parameter with a default of null is implicitly nullable, but that is deprecated in 8.4; write ?T or `T |
Usage notes
- Coercion order in weak mode. If the value's exact type is not in the union, PHP tries
int, thenfloat, thenstring, thenbool. So"3"passed toint|floatbecomesint3 and"1.5"becomesfloat1.5, whilescale("3")above returns int 6. Instrict_typesmode only widening int to float is allowed. - Strings that are not numeric do not coerce to
int|floatand raise aTypeError. ?Tis not "optional". The argument must still be passed unless you give a default.- Prefer small unions. More than two or three members often signals a design problem; consider an interface or a dedicated value class.
- Inheritance rules: return types are covariant (a child may narrow the union) and parameter types are contravariant (a child may widen it).
- Property types are checked on every assignment, and an uninitialized typed property throws when read.
falsein a union is the classic "or failure" idiom (string|false). New code usually prefers exceptions ornull.- Version notes:
?Tin 7.1, unions in 8.0, intersections in 8.1, DNF types and standalonenull/true/falsein 8.2.