mirror of
https://github.com/macintoshplus/doc-en.git
synced 2026-03-24 17:02:07 +01:00
450 lines
14 KiB
XML
450 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="function.assert" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>assert</refname>
|
|
<refpurpose>Checks an assertion</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<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>
|
|
<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>
|
|
Assertions should be used as a debugging feature only.
|
|
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>
|
|
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>
|
|
<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>
|
|
|
|
<para>
|
|
The behaviour of <function>assert</function> is dictated by the
|
|
following INI settings:
|
|
<table>
|
|
<title>Assert &ConfigureOptions;</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>&Name;</entry>
|
|
<entry>&Default;</entry>
|
|
<entry>&Description;</entry>
|
|
<entry>&Changelog;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><link linkend="ini.zend.assertions">zend.assertions</link></entry>
|
|
<entry><literal>1</literal></entry>
|
|
<entry>
|
|
<simplelist>
|
|
<member>
|
|
<literal>1</literal>: generate and execute code (development mode)
|
|
</member>
|
|
<member>
|
|
<!-- TODO: look up the RFC to figure out why you'd want this -->
|
|
<literal>0</literal>: generate code but jump around it at runtime
|
|
</member>
|
|
<member>
|
|
<literal>-1</literal>: do not generate code (production mode)
|
|
</member>
|
|
</simplelist>
|
|
</entry>
|
|
<entry/>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.assert.active">assert.active</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
If &false;, <function>assert</function> does not check the expectation
|
|
and returns &true;, unconditionally.
|
|
</entry>
|
|
<entry>
|
|
Deprecated as of PHP 8.3.0.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.assert.callback">assert.callback</link></entry>
|
|
<entry>&null;</entry>
|
|
<entry>
|
|
<para>
|
|
A user defined function to call when an assertion fails.
|
|
It's signature should be:
|
|
<methodsynopsis role="procedural">
|
|
<type>void</type><methodname>assert_callback</methodname>
|
|
<methodparam><type>string</type><parameter>file</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>line</parameter></methodparam>
|
|
<methodparam><type>null</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
|
|
</methodsynopsis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
Prior to PHP 8.0.0, the signature of the callback should be:
|
|
<methodsynopsis role="procedural">
|
|
<type>void</type><methodname>assert_callback</methodname>
|
|
<methodparam><type>string</type><parameter>file</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>line</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
|
|
</methodsynopsis>
|
|
</para>
|
|
<simpara>
|
|
Deprecated as of PHP 8.3.0.
|
|
</simpara>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.assert.exception">assert.exception</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
If &true; will throw an <classname>AssertionError</classname> if the
|
|
expectation isn't upheld.
|
|
</entry>
|
|
<entry>
|
|
Deprecated as of PHP 8.3.0.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.assert.bail">assert.bail</link></entry>
|
|
<entry>&false;</entry>
|
|
<entry>
|
|
If &true; will abort execution of the PHP script if the
|
|
expectation isn't upheld.
|
|
</entry>
|
|
<entry>
|
|
Deprecated as of PHP 8.3.0.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><link linkend="ini.assert.warning">assert.warning</link></entry>
|
|
<entry>&true;</entry>
|
|
<entry>
|
|
If &true;, will emit an <constant>E_WARNING</constant> if the
|
|
expectation isn't upheld. This INI setting is ineffective if
|
|
<link linkend="ini.assert.exception">assert.exception</link>
|
|
is enabled.
|
|
</entry>
|
|
<entry>
|
|
Deprecated as of PHP 8.3.0.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>assertion</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
|
|
<warning>
|
|
<para>
|
|
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>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If <parameter>description</parameter> is an instance of
|
|
<classname>Throwable</classname>, it will be thrown only if the
|
|
<parameter>assertion</parameter> is executed and fails.
|
|
<note>
|
|
<para>
|
|
As of PHP 8.0.0, this is done <emphasis>prior</emphasis> to calling
|
|
the potentially defined assertion callback.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
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>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
As of PHP 8.0.0, the
|
|
<link linkend="ini.assert.bail">assert.bail</link>
|
|
setting has no effect in this case.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
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>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
<function>assert</function> will always return &true; if at least one of the following is true:
|
|
</para>
|
|
<simplelist>
|
|
<member><literal>zend.assertions=0</literal></member>
|
|
<member><literal>zend.assertions=-1</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>
|
|
If none of the conditions are true <function>assert</function> will return &true; if
|
|
<parameter>assertion</parameter> is truthy and &false; otherwise.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>8.3.0</entry>
|
|
<entry>
|
|
All <literal>assert.</literal> INI settings have been deprecated.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>8.0.0</entry>
|
|
<entry>
|
|
<function>assert</function> will no longer evaluate string arguments, instead they will be
|
|
treated like any other argument. <code>assert($a == $b)</code> should be used instead of
|
|
<code>assert('$a == $b')</code>. The <literal>assert.quiet_eval</literal> &php.ini; directive and
|
|
the <constant>ASSERT_QUIET_EVAL</constant> constant have also been removed, as they would no longer
|
|
have any effect.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>8.0.0</entry>
|
|
<entry>
|
|
If <parameter>description</parameter> is an instance of
|
|
<classname>Throwable</classname>, the object is thrown if the assertion
|
|
fails, regardless of the value of
|
|
<link linkend="ini.assert.exception">assert.exception</link>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>8.0.0</entry>
|
|
<entry>
|
|
If <parameter>description</parameter> is an instance of
|
|
<classname>Throwable</classname>, no user callback is called even
|
|
if it set.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>8.0.0</entry>
|
|
<entry>
|
|
Declaring a function called <literal>assert()</literal> inside a namespace is
|
|
no longer allowed, and issues <constant>E_COMPILE_ERROR</constant>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.3.0</entry>
|
|
<entry>
|
|
Declaring a function called <literal>assert()</literal> inside a namespace
|
|
became deprecated. Such declaration now emits an <constant>E_DEPRECATED</constant>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.2.0</entry>
|
|
<entry>
|
|
Usage of a <type>string</type> as the <parameter>assertion</parameter>
|
|
became deprecated. It now emits an <constant>E_DEPRECATED</constant>
|
|
notice when both <link linkend="ini.assert.active">assert.active</link>
|
|
and <link linkend="ini.zend.assertions">zend.assertions</link> are set
|
|
to <literal>1</literal>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<example>
|
|
<title><function>assert</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
assert(1 > 2);
|
|
echo 'Hi!';
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
If assertions are enabled (<link linkend="ini.zend.assertions"><literal>zend.assertions=1</literal></link>)
|
|
the above example will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
|
|
Stack trace:
|
|
#0 example.php(2): assert(false, 'assert(1 > 2)')
|
|
#1 {main}
|
|
thrown in example.php on line 2
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
If assertions are disabled (<literal>zend.assertions=0</literal> or <literal>zend.assertions=-1</literal>)
|
|
the above example will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title>Using a custom message</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
assert(1 > 2, "Expected one to be greater than two");
|
|
echo 'Hi!';
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
If assertions are enabled the above example will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
|
|
Stack trace:
|
|
#0 example.php(2): assert(false, 'Expected one to...')
|
|
#1 {main}
|
|
thrown in example.php on line 2
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
If assertions are disabled the above example will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title>Using a custom exception class</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class ArithmeticAssertionError extends AssertionError {}
|
|
|
|
assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
|
|
echo 'Hi!';
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
If assertions are enabled the above example will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
|
|
Stack trace:
|
|
#0 {main}
|
|
thrown in example.php on line 4
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
If assertions are disabled the above example will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>assert_options</function></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|