(PHP 8 >= 8.5.0)
Este atributo pode ser usado para indicar que o valor de retorno de uma função ou método não deve ser descartado. Se o valor de retorno não for usado de nenhuma forma, um aviso será emitido.
Isso é útil para funções onde não verificar o valor de retorno provavelmente é um bug.
Para descartar intencionalmente o valor de retorno de tal função, use a conversão (void) para suprimir o aviso.
Nota: Como os atributos são projetados para serem retrocompatíveis,
#[\NoDiscard]pode ser adicionado a funções e métodos mesmo quando o PHP 8.4 ou versões anteriores são suportados, ele simplesmente não fará nada. No PHP 8.5 e versões posteriores, um aviso será emitido se o resultado não for usado. Para suprimir o aviso sem usar(void), que não é suportado antes do PHP 8.5, considere usar uma variável como$_.
Exemplo #1 Uso básico
<?php
/**
* Processa todos os itens fornecidos e retorna um array com os resultados da
* operação para cada item. `null` indica sucesso e uma exceção indica
* um erro. As chaves do array de resultados correspondem às chaves do array $items.
*
* @param array<string> $items
* @return array<null|Exception>
*/
#[\NoDiscard("pois o processamento pode falhar para itens individuais")]
function bulk_process(array $items): array {
$results = [];
foreach ($items as $key => $item) {
if (\random_int(0, 9999) < 9999) {
// Finge fazer algo útil com $item,
// o que terá sucesso em 99,99% dos casos.
echo "Processando {$item}", PHP_EOL;
$error = null;
} else {
$error = new \Exception("Falha ao processar {$item}.");
}
$results[$key] = $error;
}
return $results;
}
bulk_process($items);
?>A saída do exemplo acima no PHP 8.5 é semelhante a:
Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), pois o processamento pode falhar para itens individuais
Exemplo #2 Descartar intencionalmente o valor de retorno
<?php
#[\NoDiscard]
function some_command(): int {
return 1;
}
// Suprimir o aviso usando (void) - PHP 8.5+
(void) some_command();
// Para compatibilidade com versões do PHP anteriores à 8.5, utilize uma variável temporária
$_ = some_command();
?>