PHP 8のユニオン型（Union Types）：複数の型を柔軟に扱う方法を徹底解説

PHP 8で導入されたユニオン型（Union Type）を使うと、単一の型だけでなく、2つ以上の複数の型の値を扱えるようになります。複数の型を指定する際は、縦棒（|）で型同士をつなぎます。

ユニオン型は、関数の引数（パラメータ）、戻り値の型、そしてクラスのプロパティで利用できます。

基本構文

type1|type2|……|type_n

サンプルコード1：ユニオン型の基本

<?php
class Number
{
    private int | float $num;

    public function getNum(): float | int
    {
        return $this->num;
    }

    public function setNum(float | int $num): void
    {
        $this->num = $num;
    }
}
?>

サンプルコード2：ユニオン型を使ったPHP 8プログラム

<?php
class Number
{
    private int|float $number;

    public function setNumber(int|float $number): void
    {
        $this->number = $number;
    }

    public function getNumber(): int|float
    {
        return $this->number;
    }
}

// 数値オブジェクトに整数または浮動小数点数を渡す
$number = new Number();
$number->setNumber(5);
print_r($number->getNumber());

$number->setNumber(11.54);
print_r($number->getNumber());
?>

実行結果

511.54

この例では、同じ setNumber() メソッドに対して整数（5）と浮動小数点数（11.54）の両方を問題なく渡せています。これこそがユニオン型の利便性です。

ユニオン型におけるNull許容型

PHP 7.1では、null許容型をクエスチョンマーク（?type）で表現していました。PHP 8では、type|null という形式でもnull許容型を宣言できるようになっています。たとえば float|int|null のように記述できますが、?float|int のような書き方は認められていません。

null許容型の構文

type1|type2|null

?type1|type2 のような宣言は意味が曖昧になるため、避けるべきです。

• コンパイル時のエラーチェック − 型宣言の中に重複や冗長な型を含むユニオン型は許可されません。このチェックは、クラスやインターフェースをオートロードすることなく、コンパイル時に行われます。

• 重複した型は禁止 − int|int のような重複した宣言や、int|?int のような宣言もできません。これらは「Fatal error: Duplicate type… is redundant in …on line.」という致命的な構文エラーを引き起こします。

• void型は併用不可 − PHP 8では、void型を他のどの型とも組み合わせることはできません。

記述例

function foo(): void|null {} // エラーになる

PHP 8におけるFalse型

false型も、PHP 8のユニオン型の一部です。通常、戻り値の不在やエラーを示すにはnullを返すことが一般的ですが、PHPの慣習では「対象が見つからなかった」という状況を表すのにfalseがよく使われます。

たとえば、学生IDをもとに学生情報を検索するクラスメソッドを考えてみましょう。該当する学生IDが存在しない場合はnullを返してもよさそうですが、PHPでは見つからなかったことを示すのにfalseが使われるのが一般的です。

• false型は、null型の代わりに「失敗」を表すために使用されます。

• falseは単独の型としては使用できず、null許容の単独型も認められません。つまり、false、false|null、?false のような使い方はすべて不可能です。

• falseは、引数・プロパティ・戻り値など、型を受け付けるすべての場所で使用できます。

• trueリテラル型は存在しないため、その用途にはbool型のみを使用できます。

記述例

<?php
class Student
{
    public function find(int $id): User|false
    {
        // 学生が見つかればUserオブジェクトを返し、
        // 見つからなければfalseを返す
    }
}
?>

まとめ

ユニオン型の導入により、これまでdocコメントでしか表現できなかった「複数の型を受け入れる」シグネチャを、言語レベルで厳密に宣言できるようになりました。IDEによる補完や静的解析ツールの精度向上にもつながるため、PHP 8以降の開発では積極的に活用したい機能です。