Skip to content

Commit e890e4a

Browse files
TimWollaTimWolla
authored
Document #[\Deprecated] attribute (#3894)
1 parent 05b314c commit e890e4a

File tree

5 files changed

+203
-0
lines changed

5 files changed

+203
-0
lines changed

‎language/predefined/attributes.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
&language.predefined.attributes.attribute;
1212
&language.predefined.attributes.allowdynamicproperties;
13+
&language.predefined.attributes.deprecated;
1314
&language.predefined.attributes.override;
1415
&language.predefined.attributes.returntypewillchange;
1516
&language.predefined.attributes.sensitiveparameter;

‎language/predefined/attributes/deprecated.xml

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<reference xml:id="class.deprecated" 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 Deprecated attribute</title>
4+
<titleabbrev>Deprecated</titleabbrev>
5+
6+
<partintro>
7+
8+
<section xml:id="deprecated.intro">
9+
&reftitle.intro;
10+
<simpara>
11+
This attribute is used to mark functionality as deprecated.
12+
Using deprecated functionality will cause an <constant>E_USER_DEPRECATED</constant> error to be emitted.
13+
</simpara>
14+
</section>
15+
16+
<section xml:id="deprecated.synopsis">
17+
&reftitle.classsynopsis;
18+
19+
<classsynopsis class="class">
20+
<ooclass>
21+
<modifier>final</modifier>
22+
<classname>Deprecated</classname>
23+
</ooclass>
24+
25+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
26+
<fieldsynopsis>
27+
<modifier>public</modifier>
28+
<modifier>readonly</modifier>
29+
<type class="union"><type>string</type><type>null</type></type>
30+
<varname linkend="deprecated.props.message">message</varname>
31+
</fieldsynopsis>
32+
<fieldsynopsis>
33+
<modifier>public</modifier>
34+
<modifier>readonly</modifier>
35+
<type class="union"><type>string</type><type>null</type></type>
36+
<varname linkend="deprecated.props.since">since</varname>
37+
</fieldsynopsis>
38+
39+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
40+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.deprecated')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Deprecated'])">
41+
<xi:fallback/>
42+
</xi:include>
43+
</classsynopsis>
44+
</section>
45+
46+
<section xml:id="deprecated.props">
47+
&reftitle.properties;
48+
<variablelist>
49+
<varlistentry xml:id="deprecated.props.message">
50+
<term><varname>message</varname></term>
51+
<listitem>
52+
<para>
53+
An optional message explaining the reason for the deprecation and possible replacement functionality.
54+
Will be included in the emitted deprecation message.
55+
</para>
56+
</listitem>
57+
</varlistentry>
58+
<varlistentry xml:id="deprecated.props.since">
59+
<term><varname>since</varname></term>
60+
<listitem>
61+
<para>
62+
An optional string indicating since when the functionality is deprecated.
63+
The contents are not validated by PHP and may contain a version number,
64+
a date or any other value that is considered appropriate.
65+
Will be included in the emitted deprecation message.
66+
</para>
67+
<para>
68+
Functionality that is part of PHP will use Major.Minor as the <varname>since</varname> value,
69+
for example <literal>'8.4'</literal>.
70+
</para>
71+
</listitem>
72+
</varlistentry>
73+
</variablelist>
74+
</section>
75+
76+
<section>
77+
&reftitle.examples;
78+
<informalexample>
79+
<programlisting role="php">
80+
<![CDATA[
81+
<?php
82+
83+
#[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
84+
function unsafe_function()
85+
{
86+
echo "This is unsafe", PHP_EOL;
87+
}
88+
89+
unsafe_function();
90+
91+
?>
92+
]]>
93+
</programlisting>
94+
&example.outputs.84.similar;
95+
<screen>
96+
<![CDATA[
97+
Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
98+
This is unsafe
99+
]]>
100+
</screen>
101+
</informalexample>
102+
</section>
103+
104+
<section xml:id="deprecated.seealso">
105+
&reftitle.seealso;
106+
<simplelist>
107+
<member><link linkend="language.attributes">Attributes overview</link></member>
108+
<member><methodname>ReflectionFunctionAbstract::isDeprecated</methodname></member>
109+
<member><methodname>ReflectionClassConstant::isDeprecated</methodname></member>
110+
<member><constant>E_USER_DEPRECATED</constant></member>
111+
</simplelist>
112+
</section>
113+
114+
</partintro>
115+
116+
&language.predefined.attributes.deprecated.construct;
117+
118+
</reference>
119+
<!-- Keep this comment at the end of the file
120+
Local variables:
121+
mode: sgml
122+
sgml-omittag:t
123+
sgml-shorttag:t
124+
sgml-minimize-attributes:nil
125+
sgml-always-quote-attributes:t
126+
sgml-indent-step:1
127+
sgml-indent-data:t
128+
indent-tabs-mode:nil
129+
sgml-parent-document:nil
130+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
131+
sgml-exposed-tags:nil
132+
sgml-local-catalogs:nil
133+
sgml-local-ecat-files:nil
134+
End:
135+
vim600: syn=xml fen fdm=syntax fdl=2 si
136+
vim: et tw=78 syn=sgml
137+
vi: ts=1 sw=1
138+
-->

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

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

‎language/predefined/versions.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,8 @@
177177
<function name="SensitiveParameterValue::getValue" from="PHP 8 &gt;= 8.2.0"/>
178178
<function name="Override" from="PHP 8 &gt;= 8.3.0"/>
179179
<function name="Override::__construct" from="PHP 8 &gt;= 8.3.0"/>
180+
<function name="Deprecated" from="PHP 8 &gt;= 8.4.0"/>
181+
<function name="Deprecated::__construct" from="PHP 8 &gt;= 8.4.0"/>
180182
<function name="__PHP_Incomplete_Class" from="PHP 4 &gt;=4.0.1, PHP 5, PHP 7, PHP 8"/>
181183
</versions>
182184
<!-- Keep this comment at the end of the file

‎reference/reflection/reflectionfunctionabstract/isdeprecated.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ bool(true)
5959
&reftitle.seealso;
6060
<para>
6161
<simplelist>
62+
<member><classname>Deprecated</classname></member>
6263
<member><methodname>ReflectionFunctionAbstract::getDocComment</methodname></member>
6364
</simplelist>
6465
</para>

0 commit comments

Comments
 (0)