mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 06:18:56 +00:00
4526a0712f
This included moving the guide for the new configuration directives into the assert() page to keep the migration guide snappy. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@337862 c90b9560-bf6c-de11-be94-00142212c4b1
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 if assertion is &false;</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<para>PHP 5</para>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>PHP 7</para>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>Throwable</type><parameter>exception</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>assert</function> will check the given
|
|
<parameter>assertion</parameter> and take appropriate action if
|
|
its result is &false;.
|
|
</para>
|
|
<refsect2>
|
|
<title>Traditional assertions (PHP 5 and 7)</title>
|
|
<para>
|
|
If the <parameter>assertion</parameter> is given as a string it
|
|
will be evaluated as PHP code by <function>assert</function>.
|
|
The advantages of a string <parameter>assertion</parameter> are
|
|
less overhead when assertion checking is off and messages
|
|
containing the <parameter>assertion</parameter> expression when
|
|
an assertion fails. This means that if you pass a boolean condition
|
|
as <parameter>assertion</parameter> this condition will not show up as
|
|
parameter to the assertion function which you may have defined with the
|
|
<function>assert_options</function> function, the condition is converted
|
|
to a string before calling that handler function, and the boolean &false;
|
|
is converted as the empty string.
|
|
</para>
|
|
<para>
|
|
Assertions should be used as a debugging feature only. You may
|
|
use them for sanity-checks that test for conditions that should
|
|
always be &true; and that indicate some programming errors if not
|
|
or to check for the presence of certain features like extension
|
|
functions or certain system limits and features.
|
|
</para>
|
|
<para>
|
|
Assertions should not be used for normal runtime operations like
|
|
input parameter checks. As a rule of thumb your code should
|
|
always be able to work correctly if assertion checking is not
|
|
activated.
|
|
</para>
|
|
<para>
|
|
The behavior of <function>assert</function> may be configured by
|
|
<function>assert_options</function> or by .ini-settings described
|
|
in that functions manual page.
|
|
</para>
|
|
<para>
|
|
The <function>assert_options</function> function and/or
|
|
<constant>ASSERT_CALLBACK</constant> configuration directive allow a
|
|
callback function to be set to handle failed assertions.
|
|
</para>
|
|
<para>
|
|
<function>assert</function> callbacks are particularly useful for
|
|
building automated test suites because they allow you to easily
|
|
capture the code passed to the assertion, along with information
|
|
on where the assertion was made. While this information can be
|
|
captured via other methods, using assertions makes it much faster
|
|
and easier!
|
|
</para>
|
|
<para>
|
|
The callback function should accept three arguments. The first
|
|
argument will contain the file the assertion failed in. The
|
|
second argument will contain the line the assertion failed on and
|
|
the third argument will contain the expression that failed (if
|
|
any — literal values such as 1 or "two" will not be passed via
|
|
this argument). Users of PHP 5.4.8 and later may also provide a fourth
|
|
optional argument, which will contain the
|
|
<parameter>description</parameter> given to <function>assert</function>, if
|
|
it was set.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 xml:id="function.assert.expectations">
|
|
<title>Expectations (PHP 7 only)</title>
|
|
<para>
|
|
<function>assert</function> is a language construct in PHP 7, 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>
|
|
While <function>assert_options</function> can still be used to control
|
|
behaviour as described above for backward compatibility reasons, PHP 7
|
|
only code should use the two new configuration directives to control
|
|
the behaviour of <function>assert</function> and not call
|
|
<function>assert_options</function>.
|
|
</para>
|
|
<table>
|
|
<title>
|
|
PHP 7 configuration directives for <function>assert</function>
|
|
</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Directive</entry>
|
|
<entry>Default value</entry>
|
|
<entry>Possible values</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>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<link linkend="ini.assert.exception">assert.exception</link>
|
|
</entry>
|
|
<entry><literal>0</literal></entry>
|
|
<entry>
|
|
<simplelist>
|
|
<member>
|
|
<literal>1</literal>: throw when the assertion fails, either by
|
|
throwing the object provided as the <parameter>exception</parameter>
|
|
or by throwing a new <classname>AssertionError</classname> object if
|
|
<parameter>exception</parameter> wasn't provided
|
|
</member>
|
|
<member>
|
|
<literal>0</literal>: use or generate a
|
|
<classname>Throwable</classname> as described above, but only
|
|
generate a warning based on that object rather than throwing it
|
|
(compatible with PHP 5 behaviour)
|
|
</member>
|
|
</simplelist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>assertion</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The assertion. In PHP 5, this must be either a <type>string</type> to
|
|
be evaluated or a <type>boolean</type> to be tested. In PHP 7, this may
|
|
also be any expression that returns a value, which will be executed and
|
|
the result used to indicate whether the assertion succeeded or failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
An optional description that will be included in the failure message if
|
|
the <parameter>assertion</parameter> fails.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>exception</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
In PHP 7, the second parameter can be a
|
|
<classname>Throwable</classname> object instead of a descriptive
|
|
<type>string</type>, in which case this is the object that will be
|
|
thrown if the assertion fails and the
|
|
<link linkend="ini.assert.exception">assert.exception</link>
|
|
configuration directive is enabled.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&false; if the assertion 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>7.0.0</entry>
|
|
<entry>
|
|
<function>assert</function> is now a language construct and not a
|
|
function. <function>assertion</function> can now be an expression.
|
|
The second parameter is now interpreted either as an
|
|
<parameter>exception</parameter> (if a
|
|
<classname>Throwable</classname> object is given), or as the
|
|
<parameter>description</parameter> supported from PHP 5.4.8 onwards.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.4.8</entry>
|
|
<entry>
|
|
The <parameter>description</parameter> parameter was added. The
|
|
<parameter>description</parameter> is also now provided to a callback
|
|
function in <constant>ASSERT_CALLBACK</constant> mode as the fourth
|
|
argument.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<refsect2>
|
|
<title>Traditional assertions (PHP 5 and 7)</title>
|
|
<para>
|
|
<example>
|
|
<title>Handle a failed assertion with a custom handler</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Active 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
|
|
assert('mysql_query("")');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Using a custom handler to print a description</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Active 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;
|
|
<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>
|
|
<refsect2>
|
|
<title>Expectations (PHP 7 only)</title>
|
|
<example>
|
|
<title>Expectations without a custom exception</title>
|
|
<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>
|
|
</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
|
|
-->
|