PHP - Union Types and Mixed Types in PHP

Union types and mixed types are modern type system features introduced in PHP 8 to improve code reliability, readability, and flexibility. They allow developers to explicitly define what types of values a variable, parameter, or return value can accept, reducing ambiguity and runtime errors.

Union Types in PHP

A union type allows a variable, function parameter, or return value to accept multiple specified types. Instead of restricting a value to a single type, PHP lets you define a set of acceptable types using the pipe symbol (|).

Syntax

type1|type2|type3

Example

function formatValue(int|string $value): int|string {
    if (is_string($value)) {
        return strtoupper($value);
    }
    return $value * 2;
}

In this example:

The parameter $value can be either an integer or a string.
The function can return either an integer or a string.

Key Characteristics

Multiple allowed types are explicitly declared.
Type checking happens at runtime.
Helps reduce the need for manual type validation.
Improves code clarity by documenting expected input and output types.

Nullable Union Types

You can include null as part of a union type:

function getUser(?int $id): int|null {
    return $id;
}

This can also be written as:

function getUser(int|null $id): int|null {
    return $id;
}

Mixed Type in PHP

The mixed type represents a value that can be of any type. It is essentially a shorthand for all possible PHP types.

Example

function processData(mixed $data): mixed {
    return $data;
}

Here:

$data can be an integer, string, array, object, boolean, or null.
The function returns any type as well.

What Mixed Includes

The mixed type covers:

int
float
string
bool
array
object
callable
resource
null

Differences Between Union Types and Mixed

Union types are specific and restrictive, while mixed is broad and unrestricted.

Union types:

Define a limited set of allowed types
Improve type safety
Make code more predictable

Mixed type:

Allows any type
Offers maximum flexibility
Reduces strict type safety

Example Comparison

Union type:

function calculate(int|float $num): int|float {
    return $num * 2;
}

Mixed type:

function calculate(mixed $num): mixed {
    return $num * 2;
}

In the union type version, only integers and floats are accepted. In the mixed version, any type is accepted, which can lead to unexpected behavior.

When to Use Union Types

Union types should be used when:

A variable or function logically supports multiple specific types
You want stricter type control
You aim to reduce bugs caused by invalid data types

Example:

function find(int|string $id) {
    // Accepts numeric ID or string-based identifier
}

When to Use Mixed Type

Mixed type is useful when:

The type is genuinely unknown or highly dynamic
Writing generic or reusable utilities
Interfacing with external data sources where type cannot be predetermined

Example:

function logData(mixed $data) {
    print_r($data);
}

Limitations and Considerations

Overusing mixed defeats the purpose of type safety.
Too many union types can make code harder to read.
Some combinations are redundant or not allowed (e.g., using mixed with other types is unnecessary).
Proper documentation is still important even with type declarations.

Conclusion

Union types and mixed types enhance PHP’s type system by balancing flexibility and safety. Union types provide controlled flexibility by allowing only specific types, while the mixed type offers complete freedom when strict typing is not feasible. Choosing between them depends on the level of control and predictability required in your application design.