(PHP 8 >= 8.5.0)
This attribute can be used to indicate that the return value of a function or a method should not be discarded. If the return value is not used in any way, a warning will be emitted.
This is useful for functions where not checking the return value is likely to be a bug.
To intentionally discard the return value of such a function, use (void) cast to suppress the warning.
Nota: Since attributes are designed to be backwards compatible,
#[\NoDiscard]can be added to functions and methods even when PHP 8.4 or below are supported, it just won't do anything. On PHP 8.5 and above a warning will be emitted if the result is unused. To suppress the warning without using(void), which is not supported before PHP 8.5, consider using a variable like$_.
Example #1 Basic usage
<?php
/**
* Processes all the given items and returns an array with the results of the
* operation for each item. `null` indicates success and an Exception indicates
* an error. The keys of the result array match the keys of the $items array.
*
* @param array<string> $items
* @return array<null|Exception>
*/
#[\NoDiscard("as processing might fail for individual items")]
function bulk_process(array $items): array {
$results = [];
foreach ($items as $key => $item) {
if (\random_int(0, 9999) < 9999) {
// Pretend to do something useful with $item,
// which will succeed in 99.99% of cases.
echo "Processing {$item}", PHP_EOL;
$error = null;
} else {
$error = new \Exception("Failed to process {$item}.");
}
$results[$key] = $error;
}
return $results;
}
bulk_process($items);
?>Output of the above example in PHP 8.5 is similar to:
Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), as processing might fail for individual items
Example #2 Intentionally discarding the return value
<?php
#[\NoDiscard]
function some_command(): int {
return 1;
}
// Suppress the warning using (void) - PHP 8.5+
(void) some_command();
// For compatibility with PHP versions before 8.5, use a temporary variable
$_ = some_command();
?>