Атрибут NoDiscard

(PHP 8 >= 8.5.0)

Введение

Атрибут указывает, что нельзя игнорировать значение возврата функции или метода. Движок выдаст предупреждение, если значение возврата не обработали: не передали, не вернули, не присвоили переменной и не указали в выражении.

Атрибут полезно нацеливать на функции, результат которых нельзя игнорировать из-за риска пропустить ошибку.

Предупреждение подавляют инструкцией (void), когда требуется преднамеренно проигнорировать обработку результата функции, на которую нацелили атрибут.

Замечание: В PHP 8.4 или ниже движок проигнорирует атрибут #[\NoDiscard], который добавили к функции или методу, поскольку атрибуты разработали с учётом обратной совместимости. В PHP 8.5 и выше движок выдаст предупреждение, если результат проигнорировали. Присваивание результата переменной наподобие $_ не нарушит работу кода на прежних версиях PHP, в которых ещё не добавили поддержку инструкции (void), и подавит предупреждение при переносе кода на PHP 8.5.

Обзор класса

#[\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("поскольку вероятна ошибка при обработке отдельного элемента")]
function bulk_process(array $items): array
{
    $results = [];

    foreach ($items as $key => $item) {
        if (\random_int(0, 9999) < 9999) {
            // Имитация полезной операции со значением $item
            // с вероятностью успеха 99,99 %.
            echo "Обработка значения {$item}", PHP_EOL;
            $error = null;
        } else {
            $error = new \Exception("Ошибка обработки значения {$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), поскольку вероятна ошибка при обработке отдельного элемента

Пример #2 Преднамеренное игнорирование значения возврата

<?php

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

// Подавление предупреждения инструкцией (void) — поддерживается в PHP 8.5+
(void) some_command();

// Временная переменная сохранит обратную совместимость с PHP до версии 8.5
$_ = some_command();

Смотрите также

Введение в атрибуты

Содержание

NoDiscard::__construct — Создаёт новый экземпляр атрибута NoDiscard