assert.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> is not a function but a language construct.
   allowing 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/>
      </row>
      <row>
       <entry><link linkend="ini.assert.callback">assert.callback</link></entry>
       <entry>&null;</entry>
       <entry>
        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>
       </entry>
       <entry>
        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>
       </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/>
      </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/>
      </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/>
      </row>
     </tbody>
    </tgroup>
   </table>

   The options starting with <literal>assert.</literal> can be configured via
   <function>assert_options</function>. However, this is not recommended.
  </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>
   &false; if <parameter>assertion</parameter> is false, &true; 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.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;
  <refsect2>
   <title>Expectations</title>
   <example>
    <programlisting role="php">
<![CDATA[
<?php
assert(true == false);
echo 'Hi!';
?>
]]>
    </programlisting>
    <para>
     With <link linkend="ini.zend.assertions">zend.assertions</link> set to 0,
     the above example will output:
    </para>
    <screen>
<![CDATA[
Hi!
]]>
    </screen>
    <para>
     With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
     and <link linkend="ini.assert.exception">assert.exception</link> set to 0,
     the above example will output:
    </para>
    <screen>
<![CDATA[
Warning: assert(): assert(true == false) failed in - on line 2
Hi!
]]>
    </screen>
    <para>
     With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
     and <link linkend="ini.assert.exception">assert.exception</link> set to 1,
     the above example will output:
    </para>
    <screen>
<![CDATA[
Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
  thrown in - on line 2
]]>
    </screen>
   </example>
   <example>
    <title>Expectations with a custom exception</title>
    <programlisting role="php">
<![CDATA[
<?php
class CustomError extends AssertionError {}

assert(true == false, new CustomError('True is not false!'));
echo 'Hi!';
?>
]]>
    </programlisting>
    <para>
     With <link linkend="ini.zend.assertions">zend.assertions</link> set to 0,
     the above example will output:
    </para>
    <screen>
<![CDATA[
Hi!
]]>
    </screen>
    <para>
     With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
     and <link linkend="ini.assert.exception">assert.exception</link> set to 0,
     the above example will output:
    </para>
    <screen>
<![CDATA[
Warning: assert(): CustomError: True is not false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!
]]>
    </screen>
    <para>
     With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
     and <link linkend="ini.assert.exception">assert.exception</link> set to 1,
     the above example will output:
    </para>
    <screen>
<![CDATA[
Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4
]]>
    </screen>
   </example>
  </refsect2>
  <refsect2>
   <title>Evaluated code assertions (PHP 7 only)</title>

   <para>
    With evaluated code assertions, <function>assert</function> callbacks
    can be particularly useful as the code used for the assertion is passed
    to the callback alongside information on where the assertion was done.
   </para>
   <para>
    <example>
     <title>Handle a failed assertion with a custom handler</title>
     <programlisting role="php">
<![CDATA[
<?php
// Activate assert and make it quiet
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Create a handler function
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Assertion Failed:
        File '$file'<br />
        Line '$line'<br />
        Code '$code'<br /><hr />";
}

// Set up the callback
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Make an assertion that should fail
$array = [];
assert('count($array);');
?>
]]>
     </programlisting>
     &example.outputs.72;
     <screen>
<![CDATA[
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
<hr>Assertion Failed:
        File 'test.php'<br />
        Line '21'<br />
        Code 'count($array);'<br /><hr />
]]>
     </screen>
     &example.outputs.71;
     <screen>
<![CDATA[
<hr>Assertion Failed:
        File 'test.php'<br />
        Line '21'<br />
        Code 'count($array);'<br /><hr />
]]>
     </screen>
    </example>
   </para>
   <para>
    <example>
     <title>Using a custom handler to print a description</title>
     <programlisting role="php">
<![CDATA[
<?php
// Activate assert and make it quiet
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Create a handler function
function my_assert_handler($file, $line, $code, $desc = null)
{
    echo "Assertion failed at $file:$line: $code";
    if ($desc) {
        echo ": $desc";
    }
    echo "\n";
}

// Set up the callback
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Make an assertion that should fail
assert('2 < 1');
assert('2 < 1', 'Two is less than one');
?>
]]>
     </programlisting>
     &example.outputs.72;
     <screen>
<![CDATA[
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
Assertion failed at test.php:21: 2 < 1

Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 22
Assertion failed at test.php:22: 2 < 1: Two is less than one
]]>
     </screen>
     &example.outputs.71;
     <screen>
<![CDATA[
Assertion failed at test.php:21: 2 < 1
Assertion failed at test.php:22: 2 < 1: Two is less than one
]]>
     </screen>
    </example>
   </para>
  </refsect2>
 </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
-->