(PHP 8 >= 8.5.0)
Атрибут указывает, что нельзя игнорировать значение возврата функции или метода. Движок выдаст предупреждение, если значение возврата не обработали: не передали, не вернули, не присвоили переменной и не указали в выражении.
Атрибут полезно нацеливать на функции, результат которых нельзя игнорировать из-за риска пропустить ошибку.
Предупреждение подавляют инструкцией (void), когда требуется преднамеренно проигнорировать обработку результата функции, на которую нацелили атрибут.
Замечание: В PHP 8.4 или ниже движок проигнорирует атрибут
#[\NoDiscard], который добавили к функции или методу, поскольку атрибуты разработали с учётом обратной совместимости. В PHP 8.5 и выше движок выдаст предупреждение, если результат проигнорировали. Присваивание результата переменной наподобие$_не нарушит работу кода на прежних версиях PHP, в которых ещё не добавили поддержку инструкции(void), и подавит предупреждение при переносе кода на PHP 8.5.
Замечание: Атрибут
#[\NoDiscard]применяется к конкретному объявлению функции или метода, на котором его написали, а предупреждение выдаётся на основе того объявления, которое вызвали на самом деле. Поэтому добавление атрибута#[\NoDiscard]к методу интерфейса или абстрактному методу не приводит к предупреждению, поскольку вызывается метод реализации или переопределяющий метод. Аналогично метод, который переопределяет метод с атрибутом#[\NoDiscard], не выдаёт предупреждение, если только его самого не пометили этим атрибутом. Напротив, метод, импортированный из трейта, сохраняет атрибут, поскольку метод трейта копируется в использующий класс, как будто его объявили там.
Пример #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();