Every codebase has a few functions whose return value is the whole point. A batch job that returns the items that failed. A lock attempt that returns false when someone else got there first. A method that returns a new object rather than changing the old one.
Call any of those and ignore the result, and PHP used to say nothing. PHP 8.5 changes that with the #[\NoDiscard] attribute and a new (void) cast. Here is how they work and how to roll them out without fuss.
The short version
- Mark a function or method with
#[\NoDiscard]. - If a caller ignores its return value, PHP raises a warning (
E_USER_WARNINGfor your code,E_WARNINGfor built-in functions). - If ignoring it is intentional, write
(void) the_call();and the warning goes away.
The function still runs either way. This is a warning in the literal sense: a nudge, not a stop.
Adding a message
The attribute takes an optional message, which is added to the warning. Use it to say why the result matters. Example adapted from the PHP RFC:
``` #[\NoDiscard("as processing might fail for individual items")] function bulk_process(array $items): array { // returns [key => null|Exception] }
bulk_process($items); // Warning: The return value of function bulk_process() is expected // to be consumed, as processing might fail for individual items ```
A good message turns a vague warning into a to-do item: "as some emails may have bounced", "as the lock may not have been acquired".
What counts as "using" the result
Almost anything. Assigning it to a variable, passing it to another function, returning it, comparing it, or casting it all count. It does not have to be a useful use.
That's why the (void) cast exists. A throwaway cast such as (bool) bulk_process($items); technically uses the value, but OPcache may optimise that away and bring the warning back. (void) is the reliable, readable way to say "ignored on purpose":
``` (void) bulk_process($items); ```
(void) is a statement on its own. You can't use it inside an expression, so if ((void) bulk_process($items)) is a syntax error.
Rules the engine enforces
The attribute causes a compile-time error if you put it on:
- a function with a
: voidor: neverreturn type, - magic methods that must not return a value, such as
__constructor__clone, - property hooks.
One subtle detail: PHP checks whether the result is used before it calls the function, after evaluating the arguments. If your error handler turns warnings into exceptions, the marked function will not run at all when its result is ignored. The RFC describes this as failing closed, which is the safer outcome for this kind of function.
The DateTimeImmutable catch
The RFC also applies the attribute to the set*() methods of DateTimeImmutable. These methods return a new object and leave the original alone, which trips people up when they move from DateTime:
``` $start = new DateTimeImmutable('2026-11-07 09:00');
$start->setTime(14, 0); // $start is unchanged, and PHP now warns $start = $start->setTime(14, 0); // keep the new object ```
If you have code that moved from DateTime to DateTimeImmutable at some point, upgrading to 8.5 may surface a few of these. That's a good thing: each warning is a bug that was already there.
Where it is worth using
A simple test: if a caller forgets the return value, will something go wrong that your tests probably won't catch?
Good candidates:
- batch or bulk operations that report per-item failures,
- "try" functions that return
falseornullon a soft failure, - methods on immutable objects that return a modified copy,
- functions that return a resource or handle that must be closed.
Poor candidates: pure helpers such as str_contains() or a formatting function. Ignoring the result wastes a little CPU, nothing more, and adding warnings there just creates noise.
Rolling it out safely
- Upgrade a staging environment to 8.5 first and watch the logs for new warnings, especially around
DateTimeImmutable. - Fix real bugs by using the result. Add
(void)only where ignoring it is genuinely fine. - Add
#[\NoDiscard]to a handful of your own high-risk functions, with a clear message. - If you use an error handler that throws on warnings, test those paths deliberately.
Supporting PHP 8.4 and 8.5 together
On PHP 8.4 and earlier the attribute does nothing: unknown attributes aren't checked unless something reads them through reflection, so the code still runs. The (void) cast is new syntax, though, and will not parse before 8.5. If you need one codebase to run on both, assign to a variable instead:
``` $ignored = bulk_process($items); // counts as used on every version ```
Also worth knowing: PHP 8.2 security support ends on 31 December 2026, according to php.net's supported versions page.
Further reading
- [The #[\NoDiscard] RFC](https://wiki.php.net/rfc/marking_return_value_as_important)
- NoDiscard in the PHP manual
- PHP 8.5 release notes
- More PHP 8.5 on this blog: array_first() and array_last() and the pipe operator
Where to go next
PHP Done The Correct Way covers modern PHP habits like this with worked examples: paperback (UK) or Kindle (UK). The companion code page has the free downloads.
Want a hand bringing an older PHP codebase up to date? See PHP AIR services. More from Ian on his blog.