Skip to content

Commit 9283d18

Browse files
lacatoirelacatoire
authored
Sync NoDiscard attribute from EN (PHP 8.5) (#2559)
* Sync NoDiscard attribute from EN (PHP 8.5)
1 parent 6e5b4bf commit 9283d18

File tree

3 files changed

+234
-1
lines changed

3 files changed

+234
-1
lines changed

‎language/predefined/attributes.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<!-- EN-Revision: e890e4a7f97a9ea85e60a38443e7c8eb7ae9383f Maintainer: pierrick Status: ready -->
2+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: pierrick Status: ready -->
33
<!-- Reviewed: no -->
44
<part xml:id="reserved.attributes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
55
<title>Attributs prédéfinis</title>
@@ -13,6 +13,7 @@
1313
&language.predefined.attributes.attribute;
1414
&language.predefined.attributes.allowdynamicproperties;
1515
&language.predefined.attributes.deprecated;
16+
&language.predefined.attributes.nodiscard;
1617
&language.predefined.attributes.override;
1718
&language.predefined.attributes.returntypewillchange;
1819
&language.predefined.attributes.sensitiveparameter;

‎language/predefined/attributes/nodiscard.xml‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: lacatoire Status: ready -->
3+
<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">
4+
<title>L'attribut NoDiscard</title>
5+
<titleabbrev>NoDiscard</titleabbrev>
6+
7+
<partintro>
8+
9+
<section xml:id="nodiscard.intro">
10+
&reftitle.intro;
11+
<simpara>
12+
Cet attribut peut être utilisé pour indiquer que la valeur de retour d'une
13+
fonction ou d'une méthode ne doit pas être ignorée. Si la valeur de retour
14+
n'est utilisée d'aucune manière, un avertissement sera émis.
15+
</simpara>
16+
<simpara>
17+
Cela est utile pour les fonctions où ne pas vérifier la valeur de retour
18+
est probablement un bogue.
19+
</simpara>
20+
<simpara>
21+
Pour ignorer intentionnellement la valeur de retour d'une telle fonction,
22+
il est possible d'utiliser le cast (void) pour supprimer l'avertissement.
23+
</simpara>
24+
<note>
25+
<simpara>
26+
Étant donné que les attributs sont conçus pour être rétrocompatibles,
27+
<code>#[\NoDiscard]</code> peut être ajouté aux fonctions et méthodes
28+
même lorsque PHP 8.4 ou inférieur est supporté, il ne fera simplement rien.
29+
Sur PHP 8.5 et supérieur, un avertissement sera émis si le résultat n'est pas utilisé.
30+
Pour supprimer l'avertissement sans utiliser <code>(void)</code>,
31+
qui n'est pas supporté avant PHP 8.5,
32+
il est possible d'utiliser une variable comme <code>$_</code>.
33+
</simpara>
34+
</note>
35+
</section>
36+
37+
<section xml:id="nodiscard.synopsis">
38+
&reftitle.classsynopsis;
39+
40+
<classsynopsis class="class">
41+
<ooclass>
42+
<modifier>final</modifier>
43+
<classname>NoDiscard</classname>
44+
</ooclass>
45+
46+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
47+
<fieldsynopsis>
48+
<modifier>public</modifier>
49+
<modifier>readonly</modifier>
50+
<type class="union"><type>string</type><type>null</type></type>
51+
<varname linkend="nodiscard.props.message">message</varname>
52+
</fieldsynopsis>
53+
54+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
55+
<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'])">
56+
<xi:fallback/>
57+
</xi:include>
58+
</classsynopsis>
59+
60+
</section>
61+
62+
<section xml:id="nodiscard.props">
63+
&reftitle.properties;
64+
<variablelist>
65+
<varlistentry xml:id="nodiscard.props.message">
66+
<term><varname>message</varname></term>
67+
<listitem>
68+
<simpara>
69+
Un message optionnel expliquant pourquoi la valeur de retour ne doit pas être ignorée.
70+
</simpara>
71+
</listitem>
72+
</varlistentry>
73+
</variablelist>
74+
</section>
75+
76+
<section>
77+
&reftitle.examples;
78+
<example>
79+
<title>Utilisation basique</title>
80+
<programlisting role="php">
81+
<![CDATA[
82+
<?php
83+
84+
/**
85+
* Processes all the given items and returns an array with the results of the
86+
* operation for each item. `null` indicates success and an Exception indicates
87+
* an error. The keys of the result array match the keys of the $items array.
88+
*
89+
* @param array<string> $items
90+
* @return array<null|Exception>
91+
*/
92+
#[\NoDiscard("as processing might fail for individual items")]
93+
function bulk_process(array $items): array {
94+
$results = [];
95+
96+
foreach ($items as $key => $item) {
97+
if (\random_int(0, 9999) < 9999) {
98+
// On prétend faire quelque chose d'utile avec $item,
99+
// ce qui réussira dans 99,99% des cas.
100+
echo "Processing {$item}", PHP_EOL;
101+
$error = null;
102+
} else {
103+
$error = new \Exception("Failed to process {$item}.");
104+
}
105+
106+
$results[$key] = $error;
107+
}
108+
109+
return $results;
110+
}
111+
112+
bulk_process($items);
113+
114+
?>
115+
]]>
116+
</programlisting>
117+
&example.outputs.85.similar;
118+
<screen>
119+
<![CDATA[
120+
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
121+
]]>
122+
</screen>
123+
</example>
124+
<example>
125+
<title>Ignorer intentionnellement la valeur de retour</title>
126+
<programlisting role="php">
127+
<![CDATA[
128+
<?php
129+
130+
#[\NoDiscard]
131+
function some_command(): int {
132+
return 1;
133+
}
134+
135+
// Supprimer l'avertissement avec (void) - PHP 8.5+
136+
(void) some_command();
137+
138+
// Pour la compatibilité avec les versions de PHP antérieures à 8.5, utiliser une variable temporaire
139+
$_ = some_command();
140+
141+
?>
142+
]]>
143+
</programlisting>
144+
</example>
145+
</section>
146+
147+
<section xml:id="nodiscard.seealso">
148+
&reftitle.seealso;
149+
<simplelist>
150+
<member><link linkend="language.attributes">Vue d'ensemble des attributs</link></member>
151+
</simplelist>
152+
</section>
153+
154+
</partintro>
155+
156+
&language.predefined.attributes.nodiscard.construct;
157+
158+
</reference>
159+
<!-- Keep this comment at the end of the file
160+
Local variables:
161+
mode: sgml
162+
sgml-omittag:t
163+
sgml-shorttag:t
164+
sgml-minimize-attributes:nil
165+
sgml-always-quote-attributes:t
166+
sgml-indent-step:1
167+
sgml-indent-data:t
168+
indent-tabs-mode:nil
169+
sgml-parent-document:nil
170+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
171+
sgml-exposed-tags:nil
172+
sgml-local-catalogs:nil
173+
sgml-local-ecat-files:nil
174+
End:
175+
vim600: syn=xml fen fdm=syntax fdl=2 si
176+
vim: et tw=78 syn=sgml
177+
vi: ts=1 sw=1
178+
-->

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

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

0 commit comments

Comments
 (0)