PHP 8 introduces union types to support native syntax, allowing function parameters to accept multiple types. 1. Use the "|" symbol to define union types, such as int|string; 2. Supports primitive types, objects and nullable types without additional tags; 3. It is often used to flexibly input while maintaining type safety, such as processing user IDs or optional values; 4. Pay attention to the type check order, avoid duplicate types, and do not support PHP 8.0 return types. Union types improve code clarity, but still have limitations.

Union types in PHP 8 allows you to specify that a function parameter can accept more than one type. Before PHP 8, the only way to do this was by using comments (like @param ) for documentation, but now it's supported natively with actual syntax.

Basic Syntax

You use the pipe symbol ( | ) between types to define a union. For example:

 function setCount(int|string $value): void {
    // ...
}

In this case, the function setCount accepts either an int or a string . If any other type is passed, PHP will throw a TypeError .

This works not just for primitive types like int , string , and bool , but also for objects and even nullable types.

Note: If you're using null as part of a union, you don't need to mark the parameter as nullable separately. For example:

 function setName(string|null $name): void {}

This already allows null , so there's no need to write ?string here — in fact, doing both would be redundant and cause a parse error.

Common Use Cases

Union types are useful when a function needs to handle flexible input types while still keeping some level of type safety.

For example, imagine a function that can take either a user ID (as an integer) or a User object:

 function loadUser(int|User $identifier): ?User {
    if ($identifier instanceof User) {
        return $identifier;
    }

    return User::findById($identifier);
}

This makes the code clearer without having to rely on mixed or object types, which are too vague.

Another typical scenario is allowing optional values ??through null :

 function formatText(string|null $text): string {
    return $text ? strtoupper(trim($text)) : '';
}

Here, we're explicitly stating that $text may be omitted or set to null, and we handle that case directly in the function body.

Things to Watch Out For

There are a few gotchas when working with union types:

• Type checking order matters
  When checking types inside the function, always check the most specific types first. For example, if you have array|Traversable , make sure to check for Traversable before array , since Traversable is more specific and won't match arrays.

• No duplicate types allowed
  Writing something like int|int will result in a syntax error. You must list each type once.

• Union types don't work with return types yet
  As of PHP 8.1, union types are supported in return types too, but if you're still on PHP 8.0, you'll have to stick to a single return type or use docblocks for documentation.

Also remember that union types are checked strictly at runtime. So if you pass a value that doesn't exactly match one of the types in the union, PHP will throw an error instead of trying to coerce the value.

Summary

Union types in PHP 8 gives you a clean and powerful way to define functions that accept multiple valid types without sacrificing type safety. They're especially handy when dealing with optional parameters, polymorphic behavior, or APIs that expect flexible inputs.

They're not perfect — especially if you're still on PHP 8.0 and can't use them in return types — but they definitely improve code clarity compared to older practices like using mixed or relying solely on docblocks.

That's basically how they work. Not too bad once you get used to the syntax.

The above is the detailed content of How do union types work in PHP 8 function parameters?. For more information, please follow other related articles on the PHP Chinese website!