Skip to content

info: fix assert/dl/getrusage return-value docs, E_ALL value, and versions.xml duplicates #5650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
Open

info: fix assert/dl/getrusage return-value docs, E_ALL value, and versions.xml duplicates #5650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 42 additions & 45 deletions reference/info/functions/assert.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,32 +13,32 @@
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>Throwable</type><type>string</type><type>null</type></type><parameter>description</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>assert</function>
allows for the definition of expectations: assertions that take effect
in development and testing environments, but are optimised away to have
zero cost in production.
</para>
<para>
</simpara>
<simpara>
Assertions can be used to aid debugging.
One use case for them is to act as sanity-checks for preconditions
that should always be &true; and that if they aren't upheld this indicates
some programming errors.
Another use case is to ensure the presence of certain features like
extension functions or certain system limits and features.
</para>
<para>
</simpara>
<simpara>
As assertions can be configured to be eliminated, they should
<emphasis>not</emphasis> be used for normal runtime operations like
input parameter checks. As a rule of thumb code should behave as expected
even if assertion checking is deactivated.
</para>
<para>
</simpara>
<simpara>
<function>assert</function> will check that the expectation given in
<parameter>assertion</parameter> holds.
If not, and thus the result is &false;, it will take the appropriate action
depending on how <function>assert</function> was configured.
</para>
</simpara>

<para>
The behaviour of <function>assert</function> is dictated by the
Expand Down Expand Up @@ -121,7 +121,7 @@
<entry><link linkend="ini.assert.exception">assert.exception</link></entry>
<entry>&true;</entry>
<entry>
If &true; will throw an <classname>AssertionError</classname> if the
If &true; will throw an <exceptionname>AssertionError</exceptionname> if the
expectation isn't upheld.
</entry>
<entry>
Expand Down Expand Up @@ -165,20 +165,20 @@
<varlistentry>
<term><parameter>assertion</parameter></term>
<listitem>
<para>
<simpara>
This is any expression that returns a value, which will be executed
and the result is used to indicate whether the assertion succeeded or failed.
</para>
</simpara>

<warning>
<para>
<simpara>
Prior to PHP 8.0.0, if <parameter>assertion</parameter> was a
<type>string</type> it was interpreted as PHP code and executed via
<function>eval</function>.
This string would be passed to the callback as the third argument.
This behaviour was <emphasis>DEPRECATED</emphasis> in PHP 7.2.0,
and <emphasis>REMOVED</emphasis> in PHP 8.0.0.
</para>
</simpara>
</warning>
</listitem>
</varlistentry>
Expand All @@ -187,40 +187,40 @@
<listitem>
<para>
If <parameter>description</parameter> is an instance of
<classname>Throwable</classname>, it will be thrown only if the
<exceptionname>Throwable</exceptionname>, it will be thrown only if the
<parameter>assertion</parameter> is executed and fails.
<note>
<para>
<simpara>
As of PHP 8.0.0, this is done <emphasis>prior</emphasis> to calling
the potentially defined assertion callback.
</para>
</simpara>
</note>
<note>
<para>
<simpara>
As of PHP 8.0.0, the &object; will be thrown regardless of the configuration of
<link linkend="ini.assert.exception">assert.exception</link>.
</para>
</simpara>
</note>
<note>
<para>
<simpara>
As of PHP 8.0.0, the
<link linkend="ini.assert.bail">assert.bail</link>
setting has no effect in this case.
</para>
</simpara>
</note>
</para>
<para>
<simpara>
If <parameter>description</parameter> is a &string; this message
will be used if an exception or a warning is emitted.
An optional description that will be included in the failure message if
the <parameter>assertion</parameter> fails.
</para>
<para>
</simpara>
<simpara>
If <parameter>description</parameter> is omitted.
<!-- This does not happen if &null; is passed ... -->
A default description equal to the source code for the invocation of
<function>assert</function> is created at compile time.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -229,21 +229,18 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
<function>assert</function> will always return &true; if at least one of the following is true:
</para>
</simpara>
<simplelist>
<member><literal>zend.assertions=0</literal></member>
<member><literal>zend.assertions=-1</literal></member>
<member><literal>assert.active=0</literal></member>
<member><literal>assert.exception=1</literal></member>
<member><literal>assert.bail=1</literal></member>
<member>A custom exception object is passed to <parameter>description</parameter>.</member>
</simplelist>
<para>
<simpara>
If none of the conditions are true <function>assert</function> will return &true; if
<parameter>assertion</parameter> is truthy and &false; otherwise.
</para>
</simpara>
</refsect1>

<refsect1 role="changelog">
Expand Down Expand Up @@ -278,7 +275,7 @@
<entry>8.0.0</entry>
<entry>
If <parameter>description</parameter> is an instance of
<classname>Throwable</classname>, the object is thrown if the assertion
<exceptionname>Throwable</exceptionname>, the object is thrown if the assertion
fails, regardless of the value of
<link linkend="ini.assert.exception">assert.exception</link>.
</entry>
Expand All @@ -287,7 +284,7 @@
<entry>8.0.0</entry>
<entry>
If <parameter>description</parameter> is an instance of
<classname>Throwable</classname>, no user callback is called even
<exceptionname>Throwable</exceptionname>, no user callback is called even
if it set.
</entry>
</row>
Expand Down Expand Up @@ -332,10 +329,10 @@ assert(1 > 2);
echo 'Hi!';
]]>
</programlisting>
<para>
<simpara>
If assertions are enabled (<link linkend="ini.zend.assertions"><literal>zend.assertions=1</literal></link>)
the above example will output:
</para>
</simpara>
<screen>
<![CDATA[
Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
Expand All @@ -345,10 +342,10 @@ Stack trace:
thrown in example.php on line 2
]]>
</screen>
<para>
<simpara>
If assertions are disabled (<literal>zend.assertions=0</literal> or <literal>zend.assertions=-1</literal>)
the above example will output:
</para>
</simpara>
<screen>
<![CDATA[
Hi!
Expand All @@ -364,9 +361,9 @@ assert(1 > 2, "Expected one to be greater than two");
echo 'Hi!';
]]>
</programlisting>
<para>
<simpara>
If assertions are enabled the above example will output:
</para>
</simpara>
<screen>
<![CDATA[
Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
Expand All @@ -376,9 +373,9 @@ Stack trace:
thrown in example.php on line 2
]]>
</screen>
<para>
<simpara>
If assertions are disabled the above example will output:
</para>
</simpara>
<screen>
<![CDATA[
Hi!
Expand All @@ -396,9 +393,9 @@ assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"
echo 'Hi!';
]]>
</programlisting>
<para>
<simpara>
If assertions are enabled the above example will output:
</para>
</simpara>
<screen>
<![CDATA[
Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
Expand All @@ -407,9 +404,9 @@ Stack trace:
thrown in example.php on line 4
]]>
</screen>
<para>
<simpara>
If assertions are disabled the above example will output:
</para>
</simpara>
<screen>
<![CDATA[
Hi!
Expand Down
8 changes: 4 additions & 4 deletions reference/info/functions/dl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,15 +92,15 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success; If the functionality of loading modules is not available
or has been disabled (by setting
<link linkend="ini.enable-dl">enable_dl</link> off
in &php.ini;) an <constant>E_ERROR</constant> is emitted
and execution is stopped. If <function>dl</function> fails because the
in &php.ini;) an <constant>E_WARNING</constant> is emitted
and &false; is returned. If <function>dl</function> fails because the
specified library couldn't be loaded, in addition to &false; an
<constant>E_WARNING</constant> message is emitted.
</para>
</simpara>
</refsect1>

<refsect1 role="examples">
Expand Down
4 changes: 2 additions & 2 deletions reference/info/functions/get-defined-constants.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Array
[E_USER_ERROR] => 256
[E_USER_WARNING] => 512
[E_USER_NOTICE] => 1024
[E_ALL] => 2047
[E_ALL] => 30719
[TRUE] => 1
)

Expand Down Expand Up @@ -124,7 +124,7 @@ Array
[E_USER_ERROR] => 256
[E_USER_WARNING] => 512
[E_USER_NOTICE] => 1024
[E_ALL] => 2047
[E_ALL] => 30719
[TRUE] => 1
)
]]>
Expand Down
11 changes: 5 additions & 6 deletions reference/info/functions/getrusage.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,12 +100,11 @@ echo $dat["ru_stime.tv_sec"]; // system time used (seconds)
</member>
</simplelist>
</para>
<para>
If <function>getrusage</function> is called with <parameter>mode</parameter>
set to <literal>1</literal> (<constant>RUSAGE_CHILDREN</constant>), then
resource usage for threads are collected (meaning that internally the function
is called with <constant>RUSAGE_THREAD</constant>).
</para>
<simpara>
If <function>getrusage</function> is called with <parameter>mode</parameter>
set to <literal>1</literal> (<constant>RUSAGE_CHILDREN</constant>), then
resource usage for child processes are collected.
</simpara>
</note>
<note>
<para>
Expand Down
2 changes: 0 additions & 2 deletions reference/info/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
<function name="get_cfg_var" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="get_current_user" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="get_defined_constants" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
<function name="get_defined_functions" from="PHP 4 &gt;= 4.0.4, PHP 5, PHP 7, PHP 8"/>
<function name="get_extension_funcs" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="get_include_path" from="PHP 4 &gt;= 4.3.0, PHP 5, PHP 7, PHP 8"/>
<function name="get_included_files" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
Expand All @@ -28,7 +27,6 @@
<function name="get_loaded_extensions" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="get_magic_quotes_gpc" from="PHP 4, PHP 5, PHP 7" deprecated="PHP 7.4.0" removed="PHP 8"/>
<function name="get_magic_quotes_runtime" from="PHP 4, PHP 5, PHP 7" deprecated="PHP 7.4.0" removed="PHP 8"/>
<function name="get_required_files" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="getenv" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="getlastmod" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
<function name="getmygid" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
Expand Down