Атрибут NoDiscard

Введение

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

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

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

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

Замечание: Атрибут #[\NoDiscard] применяется к конкретному объявлению функции или метода, на котором его написали, а предупреждение выдаётся на основе того объявления, которое вызвали на самом деле. Поэтому добавление атрибута #[\NoDiscard] к методу интерфейса или абстрактному методу не приводит к предупреждению, поскольку вызывается метод реализации или переопределяющий метод. Аналогично метод, который переопределяет метод с атрибутом #[\NoDiscard], не выдаёт предупреждение, если только его самого не пометили этим атрибутом. Напротив, метод, импортированный из трейта, сохраняет атрибут, поскольку метод трейта копируется в использующий класс, как будто его объявили там.

Обзор класса

Свойства

message

Необязательное сообщение, которое объясняет, почему нельзя игнорировать значение возврата.

Примеры

<?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);

Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), поскольку вероятна ошибка при обработке отдельного элемента

<?php

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

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

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

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

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