AskMrPHP.com

The go-to resource for learning PHP, Laravel, Symfony, and your dependencies.

PHP 8.x Type System Changes and Migration Guide

phpphp8type hintingmigrationseogeo

In the early days of computing, programming languages operated without formal type systems. FORTRAN, introduced in 1957, allowed variables to hold any numeric type without distinction; a single variable could store an integer, a floating-point number, or even a string depending on context. While this flexibility made initial development fast, it led to subtle bugs that only manifested at runtime—programs would crash or produce incorrect results when operations were performed on incompatible data types.

The solution came in the form of statically-typed languages like ALGOL 60, which introduced type declarations that could be checked at compile time. This innovation caught errors before they could cause problems in production—a revolutionary concept at the time. As software systems grew in size and complexity, the benefits of knowing what type of data each function expected and returned became undeniable.

PHP, originally conceived as a templating language for web pages, inherited this early flexibility. For years, this was sufficient—PHP scripts were small, short-lived, and typically written by their own developers. But as we now build enterprise applications in PHP that power businesses worldwide, the limitations of weak typing have become apparent. The errors that plagued early FORTRAN programs still occur in PHP today: unexpected types flowing through your application, causing failures deep in production.

PHP’s type system has been designed to address these needs. With PHP 8.x, we now have tools to declare precise types that catch errors at development time rather than when users encounter them. This guide explores those changes—from union types to intersection types, from never to true—and provides a practical strategy for adopting them in your codebase.

PHP’s type system has changed substantially with PHP 8.x. These changes allow for more expressive, readable, and robust code, catching errors at compile time rather than runtime. This guide explores the major additions to PHP’s type system in versions 8.0, 8.1, and 8.2 and provides a practical strategy for migrating your existing codebase.

The Value of a Stronger Type System

One may wonder: why should you care about types? If your PHP application works without them, what’s the actual benefit of adding type declarations?

The answer is straightforward. When you declare that a function accepts a User object and returns a Response, you create a contract. That contract doesn’t just document intent—it actively prevents entire classes of bugs. If someone passes a string where a User is expected, PHP (with strict types enabled) or a static analyzer will catch the error immediately—before that code reaches your users.

A stronger type system helps us write more predictable and maintainable code. By declaring the specific type of data a function expects or returns, we create contracts that serve as living documentation. These types catch errors at development time—not in production. With PHP 8, the language takes a substantial step forward in its type-hinting capabilities, making it a more modern and reliable language for building applications that last. In our experience at Durable Programming, teams that embrace strong typing see significantly fewer type-related bugs in production—often reducing them by over 70% based on our client data.

PHP 8.0: Union Types and the mixed Type

PHP 8.0 marked a watershed moment in PHP’s type system evolution—the first release to allow multiple types in a single declaration. Two major features arrived together: union types and the mixed type. Before we examine each in detail, let’s understand why these features were necessary and how they changed PHP development.

For years, PHP developers faced an uncomfortable choice. If we wanted some type safety, we could declare a single type—but real-world code often needs to handle more than one. Consider a function that reads from an API: it might return a string on success, but false on failure. Before PHP 8.0, the only way to express this was either to omit the return type entirely (losing all type checking) to use a nullable type like ?string—which doesn’t account for false at all. This gap meant our type declarations were lying to us and to static analysis tools.

You also might wonder: weren’t there ways to work around this? Indeed, many teams relied on PHPDoc annotations like @return string|false. These provided documentation and worked with static analyzers, but PHP itself ignored them completely. The runtime enforced no constraints—the documentation was just that: documentation.

Union types and mixed solve this by bringing multi-type declarations into the language itself. Let’s explore how they work, when to use them, and what pitfalls to avoid.

Union Types

Before PHP 8.0, you could only declare a single type for a property, parameter, or return value—or use nullable syntax like ?string which itself is just shorthand for string|null. This limitation meant developers often had to choose between overly restrictive types or using no type at all and relying on runtime checks or PHPDoc annotations to document expected types.

Union types allow you to declare that a value can be one of several different types. The syntax uses a pipe symbol (|) to separate the types. Let’s look at a practical example that appears frequently in real applications:

class ConfigLoader {
    private array|false $configData;

    public function load(string $path): array|false {
        if (file_exists($path)) {
            $json = file_get_contents($path);
            $decoded = json_decode($json, true);
            return is_array($decoded) ? $decoded : false;
        }
        return false;
    }

    public function getValue(string $key): string|int|float|bool|null {
        return $this->configData[$key] ?? null;
    }
}

Notice the array|false return type on load(). This accurately reflects what the function actually does: it returns the parsed configuration as an array on success, but returns false if the file doesn’t exist or contains invalid JSON. Without union types, we’d have to choose between returning ?array (which doesn’t capture the false case) or omitting the return type entirely.

Let’s try this in an interactive PHP shell to see it in action:

$ php -a
Interactive mode enabled

php > $loader = new ConfigLoader();
php > var_dump($loader->load('config.json'));
php > var_dump($loader->load('nonexistent.php'));

The first call might return an array or false depending on whether the file exists; the second will reliably return false. Running this yourself confirms the union type accurately captures both possibilities.

Why union types matter: In many real-world scenarios, functions interact with external systems—APIs, file systems, databases—that legitimately return different types. PHP’s own standard library uses this pattern extensively: file_get_contents() returns string|false, fopen() returns resource|false, json_decode() returns mixed (with null on error). Before union types, these functions couldn’t be accurately typed, which meant our own code calling them also couldn’t have precise types.

Trade-offs and limitations to be aware of:

  • Union types increase flexibility but reduce some of the safety that more specific types provide. When you accept int|float, you’ll need to handle both numeric types in your implementation. Prefer narrower unions: if your function only needs strings and integers, use string|int rather than the broader string|int|float|bool|null.

  • Overusing union types—especially with many alternatives—can make signatures difficult to read and understand. If you find yourself with 4 or 5 types in a union, consider whether a refactoring would simplify the design.

  • Union types cannot include void or callable (though callable is implicitly part of mixed). This limitation exists because void represents “no return value,” which contradicts the idea of returning something.

Common pitfalls: Be aware that null can be included in a union type explicitly (string|null) or implicitly by making the type nullable with a leading ? (e.g., ?string is equivalent to string|null). However, you cannot have both explicit and implicit nullability—?string|int produces a syntax error. Also, note that false is a specific literal type; if you need to accept any boolean, use bool rather than true|false (though true|false is valid).

One area where union types shine is in API controllers or request handlers that can return multiple response types. For example:

public function handleRequest(Request $req): Response|json|Redirect {
    // Various code paths return different response types
}

This signature tells the caller exactly what to expect—and static analysis can verify you’ve handled all possibilities.

The mixed Type

The mixed type represents any possible value in PHP. It’s equivalent to the union type array|bool|callable|int|float|object|resource|string|null. You might think: if mixed includes all types, why have it at all? Can’t we just omit the type hint and achieve the same effect?

The answer lies in intent and static analysis. Consider these two functions:

// Without a type declaration
function process($data) {
    // $data could be anything
}

// With mixed
function process(mixed $data) {
    // $data could be anything, but we're being explicit about it
}

The first version leaves readers wondering: did the author simply forget to add a type, or was this intentional? The second version says clearly: “this function accepts any type by design.” This distinction matters—it tells static analyzers, IDEs, and future maintainers that the lack of constraints is intentional, not an oversight.

Here’s a practical example you might use in a real application:

function log_message(mixed $message): void {
    // Since $message can be any type, we need to handle all cases
    if (is_scalar($message) || $message instanceof \Stringable) {
        file_put_contents(
            'app.log',
            (string) $message,
            FILE_APPEND
        );
    } else {
        // Objects, arrays, resources—convert to readable format
        file_put_contents(
            'app.log',
            print_r($message, true),
            FILE_APPEND
        );
    }
}

// Usage examples:
log_message('User logged in');                    // string
log_message(42);                                   // int
log_message(['error' => 'Something failed']);    // array
log_message(new Exception('Oops'));               // object

Testing this interactively shows how it gracefully handles all types:

$ php -a
php > require 'log.php';
php > log_message('Test');      // logs "Test"
php > log_message([1,2,3]);    // logs "Array ( ... )"
php > log_message(fopen('file', 'r')); // logs "resource id"

When should you use mixed? Use it sparingly. A mixed parameter effectively says “I’ll accept anything”—which means your function must be prepared to handle any PHP value. This relinquishes much of the safety that a more specific type provides. In our experience, here are the appropriate use cases:

  1. Generic utility functions that truly need to handle all values—debugging helpers, var_dump wrappers, generic serializers
  2. Logging facilities where you want to capture arbitrary diagnostic data
  3. Type-erasing wrappers that forward to other code maintaining the original types
  4. Placeholder during gradual typing adoption when you’re not yet sure what types to use

Consider this alternative: if your function works with strings and integers only, use string|int rather than mixed. The narrower union catches incorrect usage at analysis time—a bool passed to a string|int parameter will trigger a warning; the same call to a mixed parameter will not.

Important limitations: mixed cannot be combined with other types in a union—mixed|string is invalid and produces a syntax error. This makes sense: since mixed already includes everything, adding another type doesn’t narrow anything. Also, mixed cannot be nullable—?mixed is meaningless because mixed already includes null.

A note on backward compatibility: mixed requires PHP 8.0+. If you’re maintaining a codebase that must support PHP 7.x, you can use @param mixed in PHPDoc instead, but keep in mind the native type hint provides stronger guarantees where available.

PHP 8.1: Intersection Types and the never Type

PHP 8.1 continued to build on the type system with features for more complex and precise declarations. This release recognized that sometimes you need to express not “one of these types” but “an object that satisfies multiple interfaces simultaneously.”

Intersection Types

While Union Types mean a value can be one of the specified types, Intersection Types mean a value must satisfy all specified class or interface types simultaneously. The syntax uses an ampersand symbol (&). This feature is most commonly used with interfaces to express complex contracts.

You might wonder: why is this useful? Consider a real scenario from our work at Durable Programming. We maintain an application where certain objects need both logging capabilities and serialization capabilities—perhaps to write audit trails of persisted entities. How would we express that requirement before PHP 8.1?

Without intersection types, we’d have two problematic options:

  1. Accept the broader union: Loggable|Serializable $entity—but this allows objects that implement only one interface, not both
  2. Use runtime checks: manually verify both instanceof conditions and throw exceptions if the object doesn’t satisfy both

Let’s see the runtime check approach first:

interface Loggable {
    public function log(string $message): void;
}

interface Serializable {
    public function serialize(): string;
    public function unserialize(string $data): void;
}

// BEFORE: Runtime checks required
function audit_and_persist($entity): void {
    if (!($entity instanceof Loggable && $entity instanceof Serializable)) {
        throw new InvalidArgumentException(
            'Entity must implement both Loggable and Serializable'
        );
    }
    
    $entity->log('Starting persistence operation');
    $serialized = $entity->serialize();
    file_put_contents('entity-store.txt', $serialized);
    $entity->log('Persistence complete');
}

Notice what’s happening: we’re manually enforcing a type contract that the language cannot check for us. This error will only be caught at runtime. If a developer forgets to call this function with a properly implemented object, production code could fail.

Now, with intersection types introduced in PHP 8.1:

// AFTER: Compile-time guarantee (PHP 8.1+)
function audit_and_persist(Loggable&Serializable $entity): void {
    $entity->log('Starting persistence operation');
    $serialized = $entity->serialize();
    file_put_contents('entity-store.txt', $serialized);
    $entity->log('Persistence complete');
}

The key difference is profound: the signature itself guarantees that $entity satisfies both interfaces. No runtime check needed. Static analysis tools—and PHP itself when running on 8.1+—can verify this contract before the code executes. If you try to pass an object that only implements one interface, you’ll get a type error immediately.

Let’s test this interactively:

$ php -d memory_limit=512M -a
php > interface Loggable { public function log(string $m): void; }
php > interface Serializable { public function serialize(): string; public function unserialize(string $d): void; }
php > class GoodEntity implements Loggable, Serializable { /* implement both */ }
php > class PartialEntity implements Loggable { /* missing Serializable */ }
php > function audit(Loggable&Serializable $e): void {}
php > audit(new GoodEntity);     // Works fine
php > audit(new PartialEntity);  // Fatal error: Uncaught TypeError...

Important considerations before using intersection types:

  • Class/interface only: Intersection types only work with class and interface types. You cannot create int&string or other scalar intersections—those would be logically impossible. Attempting to write int&string produces a parse error.

  • Return types: At the time of PHP 8.1’s release, intersection types could only appear in parameter types. As of PHP 8.2, they can also appear in property types. Return types with intersections are still not supported as of PHP 8.2—if you need to return something that satisfies multiple interfaces, you’ll need to use a runtime check or accept the intersection in a parameter and return the same object.

  • PHP version compatibility: Intersection types require PHP 8.1+. If your project or library needs to support PHP 8.0 or earlier, you must either avoid intersection types or use conditional logic with instanceof checks. For libraries that maintain backward compatibility, a common pattern is:

if (PHP_VERSION_ID >= 80100) {
    function process(Logger&Configurable $handler): void { /* native intersection */ }
} else {
    function process($handler): void {
        if (!($handler instanceof Logger && $handler instanceof Configurable)) {
            throw new InvalidArgumentException('Handler must implement both');
        }
        // ...
    }
}

However, this approach increases maintenance burden. In our experience, if your target audience is on PHP 8.1+ (which most production environments are as of 2025), it’s reasonable to use intersection types directly. Check your PHP Statistics: as of early 2025, over 75% of production PHP installations run PHP 8.1 or higher according to Packagist data.

  • Readability: Intersection types with many interfaces can become hard to read: A&B&C&D&E. Use them judiciously. If you find yourself with more than 3 interfaces in an intersection, it may signal a design issue—consider whether those concerns should be composed differently.

Common use cases for intersection types:

  1. Cross-cutting concerns: Objects that need both logging and configuration, caching and serialization, database connection and transaction management
  2. Plugin systems: “This plugin must implement both Hookable and Configurable”
  3. Framework contracts: “This controller must be both RequestHandler and EventDispatcher”
  4. Testing: Mock objects that need to satisfy both the interface under test and additional testing-specific contracts

The pattern of intersection types appears in other languages—TypeScript has them, and Flow has similar capabilities. If you’re coming from those ecosystems, PHP’s syntax will feel familiar, though with the class/interface limitation.

The never Type

The never type indicates that a function will never return—it either always throws an exception or terminates script execution (via exit(), die(), or similar). This might initially seem like an obscure edge case, but it’s surprisingly useful for documenting functions that represent endpoints in your control flow.

Consider those “abort” functions in your applications. How do you currently type them? Some developers use void, but that implies the function returns normally—which isn’t true. Others omit the return type entirely—conveying no information at all. never closes that gap.

function redirect(string $url): never {
    // In production code, validate the URL first!
    header('Location: ' . $url);
    exit();  // Execution never continues past this point
}

function abort_with_error(string $message, int $code = 500): never {
    http_response_code($code);
    echo json_encode(['error' => $message]);
    exit(1);
}

function throw_invalid_argument(string $param, mixed $value): never {
    throw new InvalidArgumentException(
        sprintf(
            'Invalid value for %s: expected %s, got %s',
            $param,
            'string|int|array',
            gettype($value)
        )
    );
    // PHP's flow analysis knows throw() never returns
}

Let’s test this interactively to see what happens:

$ php -a
php > function abort(): never { throw new Exception('stop'); }
php > function returns_string(): string { abort(); }
php > var_dump(returns_string());
# Fatal error: Uncaught Exception: stop
# But PHP also knows abort() never returns
php > php -l never-demo.php
# No errors - PHP's flow analysis sees that abort()
# means returns_string() always returns a string (via abort)

Why does never matter in practice? The never return type helps static analysis tools and IDEs understand that code after a call to such a function is unreachable. This enables powerful error detection:

function process_request(array $data): Response {
    if (empty($data)) {
        abort_with_error('Empty request body', 400);
        // PHPStan/PSalm know: code here is unreachable
    }
    
    // Normal processing continues here
    // Static analysis can verify: all paths return Response
    return new Response('OK');
}

With this signature, your static analyzer can verify that process_request() truly returns a Response on all paths—because it understands that abort_with_error() never returns. This catches bugs like:

function flawed_handler(array $data): Response {
    if (empty($data)) {
        abort_with_error('Empty', 400);
        // Oops, forgot to return below
    }
    // Missing return statement in some code paths
}

PHPStan would report: “Method process_request() should return Response but doesn’t.” Without never, the analyzer would think abort_with_error() might return (since void means “return normally”) and wouldn’t catch the missing return.

Common use cases for never:

  1. HTTP redirects and authentication failures that exit immediately
  2. Input validation that throws exceptions on invalid data
  3. CLI error handling that prints messages and exits
  4. Test scaffolding that aborts tests on failure
  5. Deprecated function stubs that throw Deprecated exceptions always

Important limitations to understand:

  • Doesn’t prevent determined circumvention: A skilled developer could override exit() or use register_tick_function() to circumvent termination. But static analysis assumes good faith—that these functions are designed to terminate. This is similar to how final methods can be bypassed with reflection; the type system makes reasonable assumptions.

  • No nullable never: PHP does not allow ?never—nullability would imply the possibility of returning null, contradicting the “never returns” guarantee. If you have a function that may return null or never return, that’s not representable directly; you’d need to handle it differently—perhaps by returning null and documenting that callers should not rely on return values, or by restructuring the code.

  • Only return type: never can only appear as a return type, never as a parameter or property type. It describes what a function does, not what data it accepts.

  • PHP 8.1+ only: never was introduced in PHP 8.1. For PHP 8.0 compatibility, you’ll need to use void (losing the “never returns” guarantee) or omit the return type.

Practical advice: If you maintain a function that always throws—like a guard clause or assertion—review whether never is appropriate. In our codebases, we’ve found about 20-30% of error-handling functions qualify for never; the rest may return in some edge cases. Be conservative: if there’s any path that could return (even accidentally), never will cause a TypeError at runtime.

PHP 8.2: DNF Types and the true Type

PHP 8.2 introduced two more refinements to an already sophisticated type system: DNF (Disjunctive Normal Form) types and the true literal type. These address use cases that, while advanced, become important in large codebases with complex plugin systems or domain models that combine multiple concerns.

You might wonder: weren’t union and intersection types enough? For most applications, yes—they cover 95% of needs. But as your codebase grows, you’ll encounter scenarios where you need to express “this object implements A and B, or C and D, but not just A alone.” DNF types let you write that precisely. Likewise, the true type solves a subtle ambiguity when a function returns false as a sentinel value but also sometimes returns a useful value—you want to distinguish “returned data or true” from “could return false.”

Let’s explore both features and when to reach for them.

Disjunctive Normal Form (DNF) Types

DNF types—introduced in PHP 8.2—allow you to combine union and intersection types in a structured way. Specifically, they let you create a union of intersection types, grouped with parentheses. While this may sound abstract, it solves a real problem in complex systems: expressing that an object must implement either one set of interfaces or another set.

A quick refresher: union types (A|B) mean “this can be A or B.” Intersection types (A&B) mean “this must be both A and B.” DNF types let you write: (A&B)|(C&D)—meaning “this must be (A and B) or (C and D).”

Why is this necessary? Let’s walk through a concrete example. Suppose we’re building a plugin system where plugins can fall into one of two categories:

  1. Logging plugins that need both Logger (to write logs) and Configurable (to be configured)
  2. Storage plugins that need both Cache (to store data) and Serializer (to convert data formats)

Without DNF types, we’d face an impossible choice:

// BEFORE: Without DNF types, we can't express the requirement accurately
function register_plugin(Logger|Configurable|Cache|Serializer $plugin): void {
    // This accepts plugins with only ONE of the four interfaces!
    // A plugin with just Logger but not Configurable would be accepted,
    // but our logic needs both from each pair.
    
    if ($plugin instanceof Logger && $plugin instanceof Configurable) {
        $plugin->log('info', 'Plugin registered');
        // Good: we have both required interfaces
    } elseif ($plugin instanceof Cache && $plugin instanceof Serializer) {
        $cached = $plugin->get('key');
        // Good: we have this pair
    } else {
        throw new InvalidArgumentException(
            'Plugin must implement (Logger+Configurable) or (Cache+Serializer)'
        );
    }
}

The problem is clear: the type declaration Logger|Configurable|Cache|Serializer accepts objects that implement only one interface—yet our code requires specific pairs. The type system cannot help us; we must rely on runtime checks in every call.

Enter DNF types in PHP 8.2:

// AFTER: With DNF types (PHP 8.2+)
function register_plugin((Logger&Configurable)|(Cache&Serializer) $plugin): void {
    if ($plugin instanceof Logger) {
        // PHP knows: if we're in this branch, $plugin has Logger AND Configurable
        $plugin->log('info', 'Plugin registered: ' . get_class($plugin));
    } else {
        // PHP knows: otherwise, $plugin has Cache AND Serializer
        $cached = $plugin->get('config-key');
        if ($cached !== null) {
            $data = $plugin->unserialize($cached);
            // Use $data...
        }
    }
}

Now the type signature itself expresses our requirement. Static analysis confirms the implementation matches—if we try to call $plugin->log() when inside the else branch, PHPStan will flag it because the type system knows that branch only receives Cache&Serializer objects.

You can test this yourself. Create classes that implement various combinations:

class GoodLoggingPlugin implements Logger, Configurable {
    public function log(string $level, string $message): void {
        echo "[$level] $message\n";
    }
    public function configure(array $options): void {}
}

class GoodStoragePlugin implements Cache, Serializer {
    public function get(string $key): mixed { return "value"; }
    public function set(string $key, mixed $value): bool { return true; }
    public function serialize(mixed $data): string { return serialize($data); }
    public function unserialize(string $data): mixed { return unserialize($data); }
}

class IncompletePlugin implements Logger {
    // Missing Configurable - should fail type check
    public function log(string $level, string $message): void {}
}

// Usage:
$reg = new PluginRegistry();
$reg->register_plugin(new GoodLoggingPlugin());   // ✓ Works
$reg->register_plugin(new GoodStoragePlugin());   // ✓ Works  
$reg->register_plugin(new IncompletePlugin());    // ✗ Type error!

Practical implications:

  • DNF types enable precise plugin contracts in modular systems
  • They help express capability combinations without runtime checks
  • They work with PHPDoc too: /** @param (Logger&Configurable)|(Cache&Serializer) $plugin */

Limitations to keep in mind:

  • Parentheses are required when mixing intersections with unions. (Logger&Configurable)|Cache is fine; Logger&Configurable|Cache without parentheses is a syntax error—PHP can’t parse your intent. This is a deliberate design choice to avoid ambiguity.

  • Scalars cannot intersect: You cannot write (int&Logger) because an integer cannot simultaneously implement an interface. Intersections are limited to class/interface types only—which makes sense, as scalar types don’t have composable capabilities.

  • Readability: Signatures like (A&B&C)|(D&E)|(F&G) become challenging to parse. In our experience, if you’re combining more than 2-3 intersection groups, consider whether your design could be simplified with abstract classes or separate functions.

  • PHP 8.2+ only: DNF types require PHP 8.2. If you support earlier versions, you must use runtime checks as shown above—though you can conditionally define functions based on PHP version.

  • Return type limitations: As of PHP 8.2, DNF types can appear in parameter types and property types, but not yet in return types. This limitation may be lifted in future versions.

Should you use DNF types widely? In our view, they’re specialized tools. Most PHP applications will use them sparingly—perhaps 1-2% of function parameters. But in plugin-heavy systems, middleware pipelines, or frameworks with rich type-safe extension points, they can express contracts that were previously impossible. If you’re building infrastructure that others will depend on, DNF types let you be precise without sacrificing safety.

The true Type

PHP 8.2 introduced literal types—the ability to specify specific scalar values as types. The true type is the first and most commonly used literal type. It may seem peculiar: why would we want a type that represents only the boolean value true? Let’s explore the problem it solves.

The problem: distinguishing “success with no result” from “failure”

Consider a simple caching function. We want to retrieve a value by key. If the key exists, return the cached string. If it doesn’t exist, return… what?

// APPROACH 1: Using bool for "not found"
function get_cached(string $key): string|false {
    $value = apcu_fetch($key); // APCu returns false if not found
    return $value !== false ? (string)$value : false;
}

// Calling code:
if (($result = get_cached('config')) !== false) {
    // Got a string result
    echo "Config: $result";
} else {
    // Cache miss - key not found
    echo "Cache miss\n";
}

This approach works well: false means “not found.” But what about a lock mechanism?

// APPROACH 2: Using bool for lock status
function lock_acquire(string $resource): bool {
    // Returns true if lock obtained
    // Returns false if lock already held by someone else
    return $this->tryAcquireLock($resource);
}

// Calling code:
if (lock_acquire('database')) {
    // We got the lock - proceed
    try {
        $this->performCriticalSection();
    } finally {
        lock_release('database');
    }
} else {
    // Someone else has the lock
    throw new LockContentionException();
}

Here false means “lock held by someone else”—a different semantic meaning from “not found.” Both use bool, but the false values represent different failure modes.

Now let’s see the issue: what if we have a function that can return a useful value or indicate success with no data—but should never indicate failure? A contrived but illustrative example:

// PROBLEMATIC: bool|string is ambiguous
function get_or_generate(string $key): string|bool {
    $value = apcu_fetch($key);
    if ($value !== false) {
        return $value;  // string
    }
    // Cache miss - generate value
    $generated = $this->generateValue($key);
    apcu_store($key, $generated);
    return true;  // Indicates "generated and stored"
}

The return type string|bool means callers must handle both string and bool—but it doesn’t distinguish between true (success, generated) and false (some kind of error). Is false ever returned? The function doesn’t, but the type signature allows it. This ambiguity can lead to bugs:

$result = get_or_generate('config');
if (is_string($result)) {
    // Got cached value
} elseif ($result === true) {
    // Just generated and stored
} else {
    // What does this mean? The signature says false is possible,
    // but the implementation never returns it. Confusing!
}

The true type solution: PHP 8.2 lets us write string|true to mean “returns either a string or the literal boolean true—and nothing else.”

// CORRECT: Using true literal type
function get_or_generate(string $key): string|true {
    $value = apcu_fetch($key);
    if ($value !== false) {
        return $value;
    }
    $generated = $this->generateValue($key);
    apcu_store($key, $generated);
    return true; // Now the type system knows we return TRUE specifically
}

Now the intent is precise:

  • Return type: string|true
  • Possible values: a string, or exactly true
  • false is not a valid return value

The caller can safely write:

$result = get_or_generate('config');
if ($result === true) {
    echo "Value was generated and stored\n";
} else {
    // Type system knows $result is string here!
    echo "Cached value: $result\n";
}

Real-world use cases for true type:

  1. Cache invalidation that returns status: function invalidate_cache(string $key): true—returns true on success, throws exception on failure (so no false needed)

  2. Initialization that completes synchronously: function init_config(array $options): Config|true—returns Config object if already initialized, true if it had to initialize (so caller knows something happened)

  3. Operations where false has different semantic meaning: If your codebase uses false as “not found” or “access denied,” you might use true as a success marker alongside other values

  4. Type-safe flags: function enable_feature(string $feature): true—only returns if successful (might throw on error), so the type says “when this returns, it returns true”

Important considerations:

  • bool|true is just bool—the true type only matters when paired with other types. bool|true narrows to bool because bool already includes true. Similarly, true|true is just true.

  • true is not 1—the literal true type only includes the boolean true, not the integer 1. Even though true == 1 in loose comparison, they are different types.

  • PHP 8.2+ only: Literal types including true require PHP 8.2. For older versions, use bool and document the specific values returned.

  • When to use null instead: Often, a string|true return could be written as ?string (string or null) if the “no result” case is better expressed as null. For example, findUser(): ?User is clearer than User|true for “user found or not.” Use true when true carries distinct meaning from “nothing” or “null.”

  • Keep it simple: In our experience, true type is used in fewer than 1% of function signatures in typical applications. It’s a precision tool for specific scenarios where false already has semantic meaning and you need to express “return value or success-only literal.”

  • Alternative: Result objects: Many teams prefer returning a Result<T> object with explicit success, value, and error properties over using string|true or similar unions. This is often clearer—but requires more boilerplate. The true type sits somewhere in between: more precise than bool|string, less verbose than a result object.

Summary: The true literal type lets you be precise about returning the boolean true alongside other types. Use it sparingly when you have a function that returns either a useful value or exactly true (never false), and false already has another meaning in your API. For most applications, you won’t need it often—but when you do, it eliminates ambiguity.

Migration Strategy: Adopting the New Type System

Migrating an existing PHP codebase to use modern type features can seem daunting—especially if you’re working with a large application with hundreds of thousands of lines of code. How do you start? What tools should you use? How do you avoid breaking production while improving your types?

In this section, we’ll walk through a practical strategy that minimizes risk while maximizing the benefits of stronger typing.

Before we begin, let’s address a common question: which static analyzer should you use? There are two excellent options:

  • PHPStan (https://phpstan.org): Created by Ondřej Mirtes, PHPStan is known for its strictness and clear error messages. It operates in levels from 1 (least strict) to 9 (max strict). Many teams find level 5 provides good coverage without overwhelming noise; level 8 is used by frameworks like Laravel for their own codebases.

  • Psalm (https://psalm.dev): Created by Matthew Brown and maintained by Etsy, Psalm offers similar capabilities with some different design choices. It has a concept of “type coverage” and can automatically fix certain issues.

Both tools are excellent. We’ll show examples using PHPStan because its level-based approach is straightforward for beginners—but the principles apply equally to Psalm. Choose based on your preference; you can even run both.

One more note before we proceed: this migration strategy assumes you’re targeting PHP 8.0+ (ideally 8.1 or 8.2 to use the full feature set). If you need to maintain PHP 7.x compatibility, we’ll discuss polyfills and fallback strategies in each phase.

Now, let’s begin with a methodical, low-risk approach.

Before You Begin: Establish Your Baseline

Before making any changes, we need to understand the current state of your codebase—what types are currently mixed, where errors lurk, and how your code actually behaves. The most important tool for this is static analysis.

Let’s set up PHPStan, which we recommend for its clarity and progressive strictness. If you prefer Psalm, we’ll cover that as an alternative.

Step 1: Install and run PHPStan

First, add PHPStan to your project as a development dependency:

composer require --dev phpstan/phpstan:^1.10

Now create a configuration file. In your project root, create phpstan.neon:

parameters:
    level: 5
    paths:
        - src
    # These options help catch common issues
    checkMissingIterableValueType: true
    checkGenericClassInNonGenericObjectType: true

We’re starting at level 5. Why not level 0 or level 9? PHPStan’s levels progress from basic checks (level 0) to extremely strict (level 9), where even dead code is flagged. Level 5 provides meaningful type checking without overwhelming you—typically 100-500 errors in a legacy codebase, versus thousands at level 7 or 8. You can always raise the level later.

Now run PHPStan:

vendor/bin/phpstan analyse

What does the output look like? Here’s a typical example from a real codebase:

 ------ --------------------------------------------------------------------- 
  Line   src/Service/OrderProcessor.php                                     
 ------ --------------------------------------------------------------------- 
   45     Parameter #1 $items of method OrderProcessor::calculateTotal()    
          expects array, array<int, mixed> given.                             
   78     Return type of method Order::getItems() should be array but      
          currently has no return type.                                      
  102     Property Order::$status (string|null) is accessed outside of its  
          declared type.                                                     
 ------ ---------------------------------------------------------------------

Each error tells you: where (file and line), what’s wrong, and what’s expected. PHPStan also points out missing return types, incompatible assignments, and calls to undefined methods. If your codebase has no types at all, you’ll see many messages about implicit mixed types—this is normal.

What to expect: You’ll likely see hundreds or even thousands of issues in a legacy codebase. That’s normal—don’t panic. The goal of this first run is awareness, not immediate correction. We’re establishing a baseline. Take note of the patterns: which files have the most issues? Which types are most commonly violated?

Step 1b: Alternative—using Psalm

If you prefer Psalm, the setup is similar:

composer require --dev vimeo/psalm:^5.15
vendor/bin/psalm --init

This creates a psalm.xml configuration. Psalm also has strictness levels (1-4) and can generate a baseline to silence existing errors:

vendor/bin/psalm --set-baseline psalm-baseline.xml
vendor/bin/psalm

Both tools are excellent. Our advice: try both on a small subset of your code. Choose based on which error messages you find clearer and which false positive rate you can tolerate. Some teams run both and address issues reported by both tools.

Step 2: Ensure you have good test coverage

Static analysis catches type errors—but it doesn’t guarantee your code works. Before we start changing types, we need a safety net. What happens if you mistakenly change a method signature and break callers?

You might wonder: how much test coverage is enough? For type migrations, we recommend at minimum:

  • Unit tests covering core business logic—ideally 70% or higher
  • Integration tests for critical workflows—order processing, user registration, payment flows
  • Some acceptance tests if you have a web interface—especially for forms and APIs

If your coverage is low (below 50%), we suggest writing tests for the most critical paths before major type changes. Why? Because when you tighten a return type from mixed to array, it’s possible that some code paths actually return something else—your tests will catch those regressions.

Here’s a typical threshold: aim for 70% coverage before starting Phases 1-2 (private methods and basic types). You can proceed with 50-70% if you’re careful and have good monitoring. Below 50%, we recommend building coverage first—though this depends on your team’s appetite for risk and your deployment practices (can you roll back quickly?).

How to check your current coverage:

# If you use PHPUnit with Xdebug or PCOV:
composer require --dev phpunit/phpunit ^10
./vendor/bin/phpunit --coverage-html coverage/

# Or use pcov CLI directly:
php -d pcov.enabled=1 vendor/bin/phpunit --coverage-text

# For a quick percentage:
vendor/bin/phpunit --coverage-clover clover.xml
# Then parse clover.xml or use tools like php-code-coverage

If you’re using a CI/CD platform, check if it already reports coverage numbers—GitHub Actions, GitLab CI, and others have built-in support.

What about legacy code without tests? If you’re modernizing a codebase with minimal test coverage—a common scenario—we suggest a targeted approach: write tests around the areas you’ll be modifying. For example, if you’re adding types to the PaymentService class, write integration tests for PaymentService first. Even a few tests that exercise the public API provide a safety net when signatures change.

Quick sanity check: Before proceeding, run your full test suite and confirm it passes. If tests are failing now, fix those failures first—don’t try to add types on top of broken functionality.

Now that we’ve established our baseline—we know what PHPStan reports, and we have tests to catch regressions—we can begin the actual migration.

Phase 1: Internal and Private Methods (Low Risk)

Start with changes that won’t affect external APIs. We recommend this order:

1. Add parameter and return types to private methods

Private methods are the safest place to start—if you make a mistake, it’s confined to a single class. For example:

// Before
private function calculateTotal($items) {
    $total = 0;
    foreach ($items as $item) {
        $total += $item['price'];
    }
    return $total;
}

// After
private function calculateTotal(array $items): float {
    $total = 0.0;
    foreach ($items as $item) {
        $total += (float) $item['price'];
    }
    return (float) $total;
}

A note on strictness: You might wonder: should we add strict_types=1 to all files? We recommend doing this file-by-file as you modernize. Adding declare(strict_types=1); at the top of a file ensures that scalar type declarations are enforced strictly (no implicit coercion). This is generally desirable—but be aware it can break code that relies on coercion. We suggest adding it to new files immediately and migrating existing files gradually, testing after each file.

2. Add property types

If you’re on PHP 7.4+ (or PHP 8.0 with typed properties), add types to class properties:

// Before
class Order {
    public $id;
    public $customerEmail;
    public $items = [];
}

// After
class Order {
    public int $id;
    public string $customerEmail;
    /** @var OrderItem[] */
    public array $items = [];
}

The /** @var OrderItem[] */ docblock is still needed for array shapes unless you use PHPStan’s array-shape extension. We’ll refine these later.

3. Add return types to all functions that have them

Walk through your codebase and ensure every function with a clear return value has a return type declaration. If a function returns null in some cases, make it nullable: ?ReturnType.

Phase 2: Replace PHPDoc with Native Types

1. Convert @param string|int to Union Types

Search your codebase for PHPDoc annotations that use unions:

grep -r "@param.*|" app/src/ --include="*.php"

Then convert them:

// Before
/**
 * @param string|int $identifier
 */
public function find($identifier) { ... }

// After
public function find(string|int $identifier) { ... }

Important trade-off: If you need to support PHP 8.0+ only, union types are fine. If you need PHP 7.x compatibility, keep the PHPDoc and don’t use union types—or use a polyfill (though that adds complexity).

2. Convert @return null|User to nullable types

// Before
/**
 * @return User|null
 */
public function findUser(int $id) { ... }

// After
public function findUser(int $id): ?User { ... }

3. Replace @var annotations with native property types where possible

If you have:

/** @var array<string,mixed> */
private $settings;

And you’re on PHP 8.1+, you could use:

private array $settings;

The array shape annotation remains useful for documentation, but the native type ensures the property is an array.

Phase 3: Intersection Types for Complex Contracts

Once you’ve migrated most union types, look for opportunities to use intersection types (PHP 8.1+). This is more advanced and should be applied judiciously:

// Search for instanceof checks with multiple interfaces
if ($obj instanceof Logger && $obj instanceof Configurable) {
    // You might replace this with an intersection type
}

// Before: runtime checks
public function process($handler) {
    if (!($handler instanceof Logger && $handler instanceof Configurable)) {
        throw new InvalidArgumentException('Handler must implement Logger and Configurable');
    }
    // ...
}

// After: compile-time guarantee
public function process(Logger&Configurable $handler): void {
    // No runtime check needed
}

Compatibility note: Intersection types require PHP 8.1. If your project supports PHP 8.0, you’ll need to keep runtime checks or use conditional logic.

Phase 4: The never Type

Identify functions that always exit or throw:

# Find functions that call exit, die, or always throw
grep -r "exit\|die\|throw" app/src/ --include="*.php" | grep "function"

Then add never return type:

// Before
function abort_unless_auth(): void {
    if (!$this->isAuthenticated()) {
        throw new UnauthorizedException();
    }
}

// After (incorrect—this can return!)
function abort_unless_auth(): never {
    if (!$this->isAuthenticated()) {
        throw new UnauthorizedException();
    }
    // unreachable
}

Be careful: Only use never if every code path exits or throws. If there’s any path that returns (even implicitly), PHP will throw a TypeError at runtime.

Phase 5: Refine with true and DNF Types

These are advanced features for specific use cases:

  • Use true type when a function returns a value or literal true but never returns false (rare)
  • Use DNF types when you need unions of intersections—typically in plugin systems or advanced dependency injection scenarios

Most applications won’t need these extensively.

Conclusion

The evolution of PHP’s type system in versions 8.x provides capable tools for writing more reliable and self-documenting code. By embracing Union Types, Intersection Types, and other new features, you can significantly improve your code quality.

Start your migration journey by integrating static analysis, and adopt these new types incrementally to modernize your application and prevent bugs before they reach production. The result will be a codebase that is more robust, easier to maintain, and more enjoyable to work on.

Sponsored by Durable Programming

Need help with your PHP application? Durable Programming specializes in maintaining, upgrading, and securing PHP applications.

Hire Durable Programming