Skip to content

Commit 02bee41

Browse files
sasezakiGirgias
sasezaki
and
Girgias
authored
Add NoDiscard attribute (#5041)
Co-authored-by: Gina Peter Banyard <girgias@php.net>
1 parent 1709768 commit 02bee41

File tree

4 files changed

+233
-0
lines changed

4 files changed

+233
-0
lines changed

‎language/predefined/attributes.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
&language.predefined.attributes.attribute;
1212
&language.predefined.attributes.allowdynamicproperties;
1313
&language.predefined.attributes.deprecated;
14+
&language.predefined.attributes.nodiscard;
1415
&language.predefined.attributes.override;
1516
&language.predefined.attributes.returntypewillchange;
1617
&language.predefined.attributes.sensitiveparameter;

‎language/predefined/attributes/nodiscard.xml‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<reference xml:id="class.nodiscard" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
3+
<title>The NoDiscard attribute</title>
4+
<titleabbrev>NoDiscard</titleabbrev>
5+
6+
<partintro>
7+
8+
<section xml:id="nodiscard.intro">
9+
&reftitle.intro;
10+
<simpara>
11+
This attribute can be used to indicate that the return value of a function
12+
or a method should not be discarded. If the return value is not used in any
13+
way, a warning will be emitted.
14+
</simpara>
15+
<simpara>
16+
This is useful for functions where not checking the return value is likely
17+
to be a bug.
18+
</simpara>
19+
<simpara>
20+
To intentionally discard the return value of such a function, use (void)
21+
cast to suppress the warning.
22+
</simpara>
23+
<note>
24+
<simpara>
25+
Since attributes are designed to be backwards compatible,
26+
<code>#[\NoDiscard]</code> can be added to functions and methods
27+
even when PHP 8.4 or below are supported, it just won't do anything.
28+
On PHP 8.5 and above a warning will be emitted if the result is unused.
29+
To suppress the warning without using <code>(void)</code>,
30+
which is not supported before PHP 8.5,
31+
consider using a variable like <code>$_</code>.
32+
</simpara>
33+
</note>
34+
</section>
35+
36+
<section xml:id="nodiscard.synopsis">
37+
&reftitle.classsynopsis;
38+
39+
<classsynopsis class="class">
40+
<ooclass>
41+
<modifier>final</modifier>
42+
<classname>NoDiscard</classname>
43+
</ooclass>
44+
45+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
46+
<fieldsynopsis>
47+
<modifier>public</modifier>
48+
<modifier>readonly</modifier>
49+
<type class="union"><type>string</type><type>null</type></type>
50+
<varname linkend="nodiscard.props.message">message</varname>
51+
</fieldsynopsis>
52+
53+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
54+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.nodiscard')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='NoDiscard'])">
55+
<xi:fallback/>
56+
</xi:include>
57+
</classsynopsis>
58+
59+
</section>
60+
61+
<section xml:id="nodiscard.props">
62+
&reftitle.properties;
63+
<variablelist>
64+
<varlistentry xml:id="nodiscard.props.message">
65+
<term><varname>message</varname></term>
66+
<listitem>
67+
<simpara>
68+
An optional message explaining why the return value should not be discarded.
69+
</simpara>
70+
</listitem>
71+
</varlistentry>
72+
</variablelist>
73+
</section>
74+
75+
<section>
76+
&reftitle.examples;
77+
<example>
78+
<title>Basic usage</title>
79+
<programlisting role="php">
80+
<![CDATA[
81+
<?php
82+
83+
/**
84+
* Processes all the given items and returns an array with the results of the
85+
* operation for each item. `null` indicates success and an Exception indicates
86+
* an error. The keys of the result array match the keys of the $items array.
87+
*
88+
* @param array<string> $items
89+
* @return array<null|Exception>
90+
*/
91+
#[\NoDiscard("as processing might fail for individual items")]
92+
function bulk_process(array $items): array {
93+
$results = [];
94+
95+
foreach ($items as $key => $item) {
96+
if (\random_int(0, 9999) < 9999) {
97+
// Pretend to do something useful with $item,
98+
// which will succeed in 99.99% of cases.
99+
echo "Processing {$item}", PHP_EOL;
100+
$error = null;
101+
} else {
102+
$error = new \Exception("Failed to process {$item}.");
103+
}
104+
105+
$results[$key] = $error;
106+
}
107+
108+
return $results;
109+
}
110+
111+
bulk_process($items);
112+
113+
?>
114+
]]>
115+
</programlisting>
116+
&example.outputs.85.similar;
117+
<screen>
118+
<![CDATA[
119+
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
120+
]]>
121+
</screen>
122+
</example>
123+
<example>
124+
<title>Intentionally discarding the return value</title>
125+
<programlisting role="php">
126+
<![CDATA[
127+
<?php
128+
129+
#[\NoDiscard]
130+
function some_command(): int {
131+
return 1;
132+
}
133+
134+
// Suppress the warning using (void) - PHP 8.5+
135+
(void) some_command();
136+
137+
// For compatibility with PHP versions before 8.5, use a temporary variable
138+
$_ = some_command();
139+
140+
?>
141+
]]>
142+
</programlisting>
143+
</example>
144+
</section>
145+
146+
<section xml:id="nodiscard.seealso">
147+
&reftitle.seealso;
148+
<simplelist>
149+
<member><link linkend="language.attributes">Attributes overview</link></member>
150+
</simplelist>
151+
</section>
152+
153+
</partintro>
154+
155+
&language.predefined.attributes.nodiscard.construct;
156+
157+
</reference>
158+
<!-- Keep this comment at the end of the file
159+
Local variables:
160+
mode: sgml
161+
sgml-omittag:t
162+
sgml-shorttag:t
163+
sgml-minimize-attributes:nil
164+
sgml-always-quote-attributes:t
165+
sgml-indent-step:1
166+
sgml-indent-data:t
167+
indent-tabs-mode:nil
168+
sgml-parent-document:nil
169+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
170+
sgml-exposed-tags:nil
171+
sgml-local-catalogs:nil
172+
sgml-local-ecat-files:nil
173+
End:
174+
vim600: syn=xml fen fdm=syntax fdl=2 si
175+
vim: et tw=78 syn=sgml
176+
vi: ts=1 sw=1
177+
-->

‎language/predefined/attributes/nodiscard/construct.xml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<refentry xml:id="nodiscard.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<refnamediv>
5+
<refname>NoDiscard::__construct</refname>
6+
<refpurpose>Construct a new NoDiscard attribute instance</refpurpose>
7+
</refnamediv>
8+
9+
<refsect1 role="description">
10+
&reftitle.description;
11+
<constructorsynopsis role="NoDiscard">
12+
<modifier>public</modifier> <methodname>NoDiscard::__construct</methodname>
13+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>message</parameter><initializer>&null;</initializer></methodparam>
14+
</constructorsynopsis>
15+
<simpara>
16+
Constructs a new <classname>NoDiscard</classname> instance.
17+
</simpara>
18+
</refsect1>
19+
20+
<refsect1 role="parameters">
21+
&reftitle.parameters;
22+
<variablelist>
23+
<varlistentry>
24+
<term><parameter>message</parameter></term>
25+
<listitem>
26+
<simpara>
27+
The value of the <property linkend="nodiscard.props.message">message</property> property.
28+
</simpara>
29+
</listitem>
30+
</varlistentry>
31+
</variablelist>
32+
</refsect1>
33+
</refentry>
34+
<!-- Keep this comment at the end of the file
35+
Local variables:
36+
mode: sgml
37+
sgml-omittag:t
38+
sgml-shorttag:t
39+
sgml-minimize-attributes:nil
40+
sgml-always-quote-attributes:t
41+
sgml-indent-step:1
42+
sgml-indent-data:t
43+
indent-tabs-mode:nil
44+
sgml-parent-document:nil
45+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
46+
sgml-exposed-tags:nil
47+
sgml-local-catalogs:nil
48+
sgml-local-ecat-files:nil
49+
End:
50+
vim600: syn=xml fen fdm=syntax fdl=2 si
51+
vim: et tw=78 syn=sgml
52+
vi: ts=1 sw=1
53+
-->

‎language/predefined/versions.xml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,8 @@
183183
<function name="Override::__construct" from="PHP 8 &gt;= 8.3.0"/>
184184
<function name="Deprecated" from="PHP 8 &gt;= 8.4.0"/>
185185
<function name="Deprecated::__construct" from="PHP 8 &gt;= 8.4.0"/>
186+
<function name="NoDiscard" from="PHP 8 &gt;= 8.5.0"/>
187+
<function name="NoDiscard::__construct" from="PHP 8 &gt;= 8.5.0"/>
186188
<function name="__PHP_Incomplete_Class" from="PHP 4 &gt;=4.0.1, PHP 5, PHP 7, PHP 8"/>
187189
</versions>
188190
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)