【PHP8.x】ReflectionMethod::hasTentativeReturnType()メソッドの使い方

Copy
1<?php
2
3/**
4 * リファレンス情報:
5 * 言語: PHP
6 * バージョン: 8
7 * 大分類: extension
8 * 小分類: method
9 * 所属クラス: ReflectionMethod
10 * 名前: hasTentativeReturnType
11 * 引数: 引数なし
12 * 戻り値: bool
13 *
14 * キーワード: phpstan has no return type specified
15 */
16
17/**
18 * このインターフェースのメソッドには、戻り値型が明示的に宣言されていません。
19 * PHPStanのような静的解析ツールは、このようなメソッドに対して
20 * 「Method MyInterface::getData() has no return type specified」
21 * のような警告を出すことがあります。
22 *
23 * この警告は、コードの安全性を高めるために戻り値型を追加することを推奨しています。
24 */
25interface MyInterface
26{
27    public function getData();
28}
29
30/**
31 * MyInterfaceを実装するクラスです。
32 * getData()メソッドに'string'の戻り値型を追加しています。
33 *
34 * 親インターフェース (MyInterface) の getData() には戻り値型がなかったため、
35 * PHP 8 以降では、このように子クラスで戻り値型を追加してもエラーにはなりません。
36 * しかし、この追加された戻り値型は「Tentative（暫定的）」なものと見なされます。
37 */
38class MyClass implements MyInterface
39{
40    public function getData(): string
41    {
42        return "Hello from MyClass!";
43    }
44}
45
46// ReflectionMethod を使用して MyClass の getData メソッドをリフレクションします。
47$reflectionMethod = new ReflectionMethod(MyClass::class, 'getData');
48
49echo "--- ReflectionMethod::hasTentativeReturnType のサンプル ---" . PHP_EOL;
50echo "対象メソッド: " . $reflectionMethod->getName() . PHP_EOL;
51echo "宣言クラス: " . $reflectionMethod->getDeclaringClass()->getName() . PHP_EOL;
52echo "現在の戻り値型: " . ($reflectionMethod->getReturnType()?->getName() ?? 'なし') . PHP_EOL;
53
54// hasTentativeReturnType() を呼び出し、結果を表示します。
55if ($reflectionMethod->hasTentativeReturnType()) {
56    echo "\nこのメソッドには Tentative Return Type (暫定的な戻り値型) があります。" . PHP_EOL;
57    echo "これは、親のインターフェースやクラスで戻り値型が指定されていないにもかかわらず、" . PHP_EOL;
58    echo "子クラスで明示的に戻り値型が追加されたことを意味します。" . PHP_EOL;
59    echo "PHP 8 ではこのような変更が許容されますが、静的解析ツールによっては、" . PHP_EOL;
60    echo "親と子の戻り値型の整合性について注意を促すことがあります。" . PHP_EOL;
61} else {
62    echo "\nこのメソッドには Tentative Return Type がありません。" . PHP_EOL;
63    echo "これは、戻り値型が親のインターフェースやクラスで既に定義されているか、" . PHP_EOL;
64    echo "または、このメソッド自体が新たに導入されたか、" . PHP_EOL;
65    echo "あるいは親にも子にも戻り値型が指定されていない状況を意味します。" . PHP_EOL;
66}

ReflectionMethod::hasTentativeReturnTypeは、PHP 8で導入されたメソッドで、特定のメソッドが「暫定的な戻り値型」を持っているかどうかを判定します。このメソッドは引数を受け取らず、真偽値（bool）を返します。

「暫定的な戻り値型」とは、親となるインターフェースやクラスでメソッドの戻り値型が指定されていないにもかかわらず、子クラスや実装クラスで明示的に戻り値型が追加された場合に、その追加された型を指します。PHP 8以降では、このような型定義が互換性エラーとならず許容されるようになりました。

サンプルコードでは、戻り値型を持たないインターフェースMyInterfaceを定義し、それを実装するMyClassのgetDataメソッドにstring型を追加しています。このgetDataメソッドをReflectionMethodで検査すると、hasTentativeReturnType()はtrueを返します。これは、元の宣言には型がなかったが、子クラスで型が「暫定的に」追加されたことを意味します。

このメソッドを使うことで、プログラムが実行時に、メソッドの戻り値型が親の宣言に由来するものか、それとも後から子で追加されたものかを判別できるようになります。これにより、型ヒントの利用状況を詳細に分析したり、PHPStanなどの静的解析ツールが指摘する「has no return type specified」のような警告の背景にある状況を理解しやすくなります。

Copy
1<?php
2
3// MyClass は、異なる戻り値の型宣言を持つメソッドの例を含みます。
4class MyClass
5{
6    /**
7     * このメソッドは標準的なPHPの型ヒントを持ちます。
8     * PHPランタイムはこの型（string）を強制し、異なる型の値を返すとTypeErrorが発生します。
9     */
10    public function getNormalString(): string
11    {
12        return "Hello World";
13    }
14
15    /**
16     * PHP 8.0 で導入された #[ReturnTypeWillChange] 属性を持つメソッド。
17     * これは「Tentative Return Type（暫定的な戻り値の型）」と呼ばれます。
18     *
19     * この属性は、メソッドが 'int' を返すことを意図しているが、PHPランタイムは
20     * この型ヒントを厳密には強制しないことを示します。
21     * 主に、既存のコードの後方互換性を維持しつつ、静的解析ツール（例: PHPStan）に
22     * より正確な型情報を提供するために使用されます。
23     *
24     * ここではデモのために、実際には int ではない 'string' を返していますが、
25     * PHPは TypeError を発生させません。
26     */
27    #[ReturnTypeWillChange]
28    public function getTentativeInt(): int
29    {
30        return "123"; // 実際は int を返すことを意図するが、ここでは string を返す
31                      // PHPランタイムはエラーを発生させない
32    }
33
34    /**
35     * このメソッドはPHPDocブロックの `@return` アノテーションを使って、
36     * 静的解析ツール向けに戻り値の型（bool）を示します。
37     *
38     * #[ReturnTypeWillChange] 属性がないため、PHPランタイムにとってこれは
39     * 「Tentative Return Type」ではありません。
40     * `hasTentativeReturnType` メソッドは `false` を返します。
41     */
42    public function getBoolViaDocblock()
43    {
44        return true;
45    }
46}
47
48// MyClass のリフレクションを作成し、メソッド情報を調べます。
49$reflectionClass = new ReflectionClass(MyClass::class);
50
51echo "--- メソッド: getNormalString ---\n";
52$reflectionMethodNormal = $reflectionClass->getMethod('getNormalString');
53// hasTentativeReturnType() は、メソッドが #[ReturnTypeWillChange] 属性を持つかどうかをチェックします。
54echo "  Tentative Return Type を持っているか？: " . ($reflectionMethodNormal->hasTentativeReturnType() ? 'はい' : 'いいえ') . "\n";
55// getReturnType() は、PHPが認識する実際の戻り値の型を取得します。
56echo "  PHPが認識する戻り値の型: " . ($reflectionMethodNormal->getReturnType()?->getName() ?? 'なし') . "\n\n";
57
58echo "--- メソッド: getTentativeInt ---\n";
59$reflectionMethodTentative = $reflectionClass->getMethod('getTentativeInt');
60echo "  Tentative Return Type を持っているか？: " . ($reflectionMethodTentative->hasTentativeReturnType() ? 'はい' : 'いいえ') . "\n";
61echo "  PHPが認識する戻り値の型: " . ($reflectionMethodTentative->getReturnType()?->getName() ?? 'なし') . "\n\n";
62
63echo "--- メソッド: getBoolViaDocblock ---\n";
64$reflectionMethodDocblock = $reflectionClass->getMethod('getBoolViaDocblock');
65echo "  Tentative Return Type を持っているか？: " . ($reflectionMethodDocblock->hasTentativeReturnType() ? 'はい' : 'いいえ') . "\n";
66echo "  PHPが認識する戻り値の型: " . ($reflectionMethodDocblock->getReturnType()?->getName() ?? 'なし') . "\n\n";
67
68// 解説:
69// - `getTentativeInt` のみが `true` を返すのは、`#[ReturnTypeWillChange]` 属性を持っているためです。
70//   これはPHP 8.0 で導入され、ランタイムが型ヒントを厳密に強制しないものの、静的解析ツールに情報を提供する意図があります。
71// - `getBoolViaDocblock` はPHPDocの `@return` で型を示していますが、PHPランタイムが直接認識する
72//   Tentative Return Type ではないため、`hasTentativeReturnType()` は `false` を返します。
73//   PHPStanのようなツールは `@return` アノテーションを解析し、型のオーバーライドや確認に利用できますが、
74//   これはPHPのリフレクションAPIが直接扱う「Tentative Return Type」とは別の概念です。
75?>

ReflectionMethod::hasTentativeReturnTypeは、特定のメソッドが「Tentative Return Type（暫定的な戻り値の型）」を持っているかどうかを真偽値（bool）で判定するメソッドです。引数は必要ありません。

「Tentative Return Type」とは、PHP 8.0で導入された#[ReturnTypeWillChange]属性が付けられたメソッドの戻り値の型を指します。この属性が付与されたメソッドでは、PHPランタイムは戻り値の型を厳密に強制しません。これは、既存のコードの後方互換性を保ちながら、PHPStanなどの静的解析ツールに対し、メソッドが本来返すことを意図している正確な型情報を提供する目的で利用されます。

サンプルコードでは、異なる戻り値の型を持つメソッドを通してこの挙動を確認しています。getNormalStringメソッドは標準的な型ヒントを持つため、hasTentativeReturnType()はfalseを返します。一方、getTentativeIntメソッドは#[ReturnTypeWillChange]属性を持つため、hasTentativeReturnType()はtrueを返します。このメソッドはint型を意図しますが、実際にはstringを返してもPHPランタイムはエラーを発生させません。また、getBoolViaDocblockメソッドはPHPDocブロックで型を示していますが、PHPランタイムが直接認識する「Tentative Return Type」ではないため、hasTentativeReturnType()はfalseを返します。

このメソッドは、#[ReturnTypeWillChange]属性の有無をプログラムから確認し、PHPランタイムの型チェックの厳密さを調整しつつ、静的解析ツールに情報提供するメソッドの特性を判断する際に役立ちます。