# The NoDiscard attribute

(PHP 8 >= 8.5.0)

## Introduction

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.

> Note: 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 `$_`.

## Class synopsis

#[\Attribute]
final class NoDiscard {
/* Properties */
public readonly ?string $message;
/* Methods */
public __construct(?string `$message` = `null`)
}

## Properties

message
  An optional message explaining why the return value should not be discarded.

## Examples

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

## See Also

- Attributes overview

## Table of Contents

- NoDiscard::__construct — Construct a new NoDiscard attribute instance

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