<?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
-->