NoDiscard アトリビュート

(PHP 8 >= 8.5.0)

はじめに

このアトリビュートは、関数やメソッドの戻り値を無視すべきでないことを示すために使います。戻り値がまったく使われなかった場合、警告が発生します。

これは、戻り値を確認しないことがバグにつながる可能性が高い関数に役立ちます。

このような関数の戻り値を意図的に無視するには、(void) キャストを使って警告を抑制します。

注意: アトリビュートは後方互換性を持つように設計されているため、 PHP 8.4 以前をサポートする場合でも #[\NoDiscard] を関数やメソッドに追加できます。単に何も起こらないだけです。 PHP 8.5 以降では、戻り値が使われなかった場合に警告が発生します。 PHP 8.5 より前ではサポートされていない (void) を使わずに警告を抑制するには、$_ のような変数を使うことを検討してください。

クラス概要

#[\Attribute]
final class NoDiscard {

/* プロパティ */

public readonly ?string $message;

/* メソッド */

public __construct(?string $message = null)

}

プロパティ

message: 戻り値を無視すべきでない理由を説明する、任意のメッセージ。

例

例1 基本的な使い方

<?php

/**
 * 与えられた全てのアイテムを処理し、各アイテムの処理結果を
 * 配列で返す。`null` は成功を、Exception はエラーを示す。
 * 結果の配列のキーは $items 配列のキーと一致する。
 *
 * @param array<string> $items
 * @return array<null|Exception>
 */
#[\NoDiscard("as processing might fail for individual items")]
function bulk_process(array $items): array {
    $results = [];

    foreach ($items as $key => $item) {
        if (\random_int(0, 9999) < 9999) {
            // $item に対して何か有用な処理を行う想定。
            // 99.99% のケースで成功する。
            echo "Processing {$item}", PHP_EOL;
            $error = null;
        } else {
            $error = new \Exception("Failed to process {$item}.");
        }

        $results[$key] = $error;
    }

    return $results;
}

bulk_process($items);

?>

上の例の PHP 8.5 での出力は、たとえば以下のようになります。:

Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), as processing might fail for individual items

例2 戻り値を意図的に無視する

<?php

#[\NoDiscard]
function some_command(): int {
    return 1;
}

// (void) を使って警告を抑制する - PHP 8.5 以降
(void) some_command();

// PHP 8.5 より前のバージョンとの互換性のため、一時変数を使う
$_ = some_command();

?>

参考

アトリビュートの概要

NoDiscard アトリビュート

はじめに

クラス概要

プロパティ

例

参考

目次