# Атрибут 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 function __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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open