PHP 8.1 language changes

PHP 8.1 adds language support for enumerations. An enum declares a closed set of named cases, and each case is a distinct value that you can use in type declarations and compare with ===. Backed enums attach a scalar value to each case, which is available through the value property, while every case exposes its name. Enums may also contain methods, so logic that used to live in helper functions next to a group of constants can sit beside the cases.

The main migration benefit is type safety: a parameter typed with an enum cannot receive an arbitrary string or integer the way a constant-based API can. Be aware that enum becomes a declaration keyword in this position, so check for conflicts with existing code when upgrading. Enum cases are not plain scalars, so existing code that stores or compares raw values has to read value explicitly.

PHP 8.1 introduces the readonly property modifier. A readonly property can be assigned a single time, normally in the constructor, and any later write throws an Error. Combined with constructor property promotion from PHP 8.0, this makes small immutable value objects very short to write.

Two practical points. First, readonly is now a keyword, although it can still be used as a function name, so check any code that used it in other positions. Second, readonly protects the property binding, not the value it points to: if a readonly property holds an object, that object can still be changed through its own methods. Readonly properties must also be typed. For modification you generally create a new instance, the so-called wither pattern shown below, rather than editing the existing one.

In PHP 8.0 an optional parameter placed before a required parameter was deprecated, but a call using named arguments could still skip the optional one and succeed. In PHP 8.1 the optional parameter is implicitly treated as required in every case. The call that omitted it now throws ArgumentCountError, exactly as a positional call would. The definition itself still emits a deprecation.

This is one of the few places where code that ran in 8.0 can fail at runtime in 8.1, so search for signatures with defaults ahead of required parameters. The fix is to move the required parameters first, or to remove the default if it never applied. The one documented exception is a parameter with a default of null used to make a type nullable: it is still accepted, but the parameter remains required.

Scalar parameters of built-in functions used to accept null and quietly coerce it. PHP 8.1 deprecates this to match user-defined functions, where a scalar type must be marked nullable explicitly. The call still works in 8.1, but it emits a deprecation, and the guide gives str_contains("foobar", null) as an example.

This tends to be the noisiest item during an upgrade because the null often comes from request data, optional array keys or database columns. Do not suppress the message. Decide what null should mean at that point: usually a default such as an empty string via ??, or an earlier branch that skips the call. Static analysis helps find these locations, since the parameter types of built-ins are well documented. Treat it as a bug-finding opportunity as well, since an unexpected null often signals missing validation upstream.

PHP 8.1 deprecates implicit float-to-int conversions that lose precision. The guide lists three places this affects: array keys, int type declarations in coercive mode, and operators that work on integers. A float with no fractional part, such as 15.0, is still fine because the conversion loses nothing.

The pitfall is that results of arithmetic are often floats with a hidden fractional part, such as a division or a percentage, which are then used as an offset. Make the intent explicit: use floor(), ceil() or round() to pick the rounding rule, then cast with (int), or use intdiv() where integer division is what you mean. Silent truncation was previously hiding that decision. Keep an eye on indexes computed from user input, since fractional values there are a sign of a logic error.

Before PHP 8.1, a child class that inherited a method without overriding it got its own copy of that method's static variables. In 8.1 the inherited method shares them with the parent's method. The guide notes that static variables in methods now behave the same way as static properties.

The risk is code that used a static variable as per-class state, such as a counter or cache inside a method called through several subclasses. After the upgrade those classes will see one combined value. If you need separate state per class, either override the method in the subclass so it has its own variables, or switch to a static property keyed by static::class. Add a test that calls the method through parent and child to catch this early.

PHP 8.1 allows new ClassName() expressions in places that previously required constant values: default values of parameters, static variable initializers, global constant initializers and attribute arguments. Objects can also be passed to define().

The most common use is a default collaborator for a constructor parameter. Before, you had to make the parameter nullable, default it to null and then substitute an instance inside the body, which blurred the real type. Now the parameter keeps its non-nullable type and the default is visible in the signature. Remember that the default expression is evaluated at call time, so each call without an argument gets a fresh object. This applies to the listed contexts only; it does not make arbitrary expressions valid in constant expressions elsewhere.

PHP 8.1 lets you turn any callable into a Closure by writing the call with ... in place of the arguments, for example myFunc(...). The guide describes it as identical to Closure::fromCallable('myFunc'). It works for plain functions, instance methods and static methods, so it replaces string and array callables such as 'strlen' or [$obj, 'method'].

The advantage is that the target is written as real code, so editors and static analyzers can rename and check it, and a typo fails when the expression runs instead of later when the callable is invoked. The ... is part of the syntax and is not an omission. Do not confuse it with argument unpacking, which has the ellipsis before an actual argument.

Array unpacking inside an array literal, available for integer-keyed arrays since PHP 7.4, now also supports string keys in PHP 8.1. You can merge associative arrays with the spread operator and add extra entries in the same literal.

For string keys, a later value replaces an earlier one with the same key, and the key keeps the position where it first appeared, which matches how array_merge() treats string keys. Integer keys are renumbered as before. The change mainly makes configuration merging and option defaults more readable. One pitfall: spreading something that is not an array or Traversable is still an error, so values that may be null need handling first.

PHP 8.1 adds never as a return-only type. It tells the engine and readers that a function does not return normally: it exits, throws an exception or never terminates. This is stricter than void, which means the function returns with no value.

It is most useful for small helpers that raise errors or redirect, because static analyzers can then treat code after the call as unreachable and stop complaining about missing return statements. Note the compatibility angle: never is now a reserved word, so it cannot name a class, interface or trait, and cannot be used in namespaces. If your codebase has a class called Never, rename it before upgrading. A function declared never must not contain a path that returns.

PHP 8.1 adds intersection types, written with &, which require a value to be an instance of every listed type. A parameter typed Countable&Traversable accepts only objects that implement both interfaces. Previously you could only express this with docblocks plus manual instanceof checks, or by inventing a combined interface that third-party classes would not implement.

The guide includes a caution: intersection types cannot be combined with union types in the same declaration. That limitation matters when you are tempted to write something like a nullable intersection. A value that fails the check raises a TypeError, as with other declared types. Use them for capability-based parameters, and keep the list of types short so the contract stays readable.

PHP 8.1 adds support for Fibers. A fiber runs a callable that can pause itself with Fiber::suspend(), handing a value back to the code that started or resumed it, and can later be continued with resume(). The state of the whole call stack inside the fiber is preserved, which is different from generators, where only the generator function itself can yield.

For most application code Fibers are a building block rather than something you call directly; they are mainly used by schedulers and asynchronous frameworks. Adopting them does not require changes to existing synchronous code. Be careful when mixing them with code that assumes a straight-line execution order, since a suspension can occur deep inside nested calls and control returns to the caller of start() or resume().

PHP 8.1 adds support for the final modifier on class constants. A final constant cannot be redefined in a subclass, which is useful for values that other code relies on staying fixed. Trying to override one is a compile-time error, so mistakes show up as soon as the file loads.

The same release also changes the default for interface constants: they are now overridable unless declared final. If you relied on implementing classes being unable to change an interface constant, add final to it in the interface. Constants without final in classes remain overridable, as before. Use final sparingly and only for values that are truly part of a contract, since it limits how others can extend your class.

Autovivification means PHP creates an array automatically when you append to a value that is not one yet. Scalars have never been allowed to do this, but false was an exception. PHP 8.1 deprecates that exception, so code like assigning with [] to a variable that holds false now emits a deprecation.

Autovivification from null and from undefined variables or array elements is still allowed, so the usual pattern of building an array lazily keeps working. The practical risk is functions that return false on failure and whose result is then appended to directly. Initialize an empty array explicitly when you see false, or check the value before writing to it. Doing so also makes the failure case visible instead of quietly turning it into data.