sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

assert()

Browse source 
Corrected minor grammatical and spelling mistakes
Added information on assert callback functions
Added an example of a callback function


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@50210 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Zak Greant 2001-06-26 11:24:50 +00:00
parent 25aab21991
commit 23cd3f0060
1 changed files with 95 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
functions/info.xml
View file

@ -1,7 +1,7 @@
<reference id="ref.info">
<title>PHP options &amp; information</title>
<titleabbrev>PHP options/info</titleabbrev>
<refentry id="function.assert">
<refnamediv>
<refname>assert</refname>
@ -16,38 +16,83 @@
</funcprototype>
</funcsynopsis>
<para>
<function>assert</function> will check the given
<parameter>assertion</parameter> and take appropriate
<function>assert</function> will check the given
<parameter>assertion</parameter> and take appropriate
action if its result is <literal>FALSE</literal>.
</para>
<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>
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 failes.
an assertion fails.
</para>
<para>
Assertion should be used as a debugging feature only. You may
Assertions should be used as a debugging feature only. You may
use them for sanity-checks that test for conditions that should
always be <literal>TRUE</literal> 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
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 correct if assertion checking
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
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
ASSERT_CALLBACK 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
arugument 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)
</para>
<para>
Handle a failed assertion with a custom handler
<informalexample>
<programlisting>&lt;?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 "&lt;hr&gt;Assertion Failed:
File '$file'&lt;br&gt;
Line '$line'&lt;br&gt;
Code '$code'&lt;br&gt;&lt;hr&gt;";
}
// Set up the callback
assert_options (ASSERT_CALLBACK, 'my_assert_handler');
// Make an assertion that should fail
assert ('mysql_query ("")');
?&gt;</programlisting>
</informalexample>
</para>
</refsect1>
</refentry>
</refentry>
<refentry id="function.assert-options">
<refnamediv>
@ -60,7 +105,7 @@
<funcprototype>
<funcdef>mixed <function>assert_options</function></funcdef>
<paramdef>int <parameter>what</parameter></paramdef>
<paramdef>mixed
<paramdef>mixed
<parameter><optional>value</optional></parameter>
</paramdef>
</funcprototype>
@ -115,7 +160,7 @@
<entry>(null)</entry>
<entry>user function to call on failed assertions</entry>
</row>
</tbody>
</tbody>
</tgroup>
</table>
<para>
@ -123,7 +168,7 @@
setting of any option or <literal>FALSE</literal> on errors.
</para>
</refsect1>
</refentry>
</refentry>
<refentry id="function.extension-loaded">
<refnamediv>
@ -153,7 +198,7 @@
</para>
</refsect1>
</refentry>
<refentry id="function.dl">
<refnamediv>
<refname>dl</refname>
@ -175,7 +220,7 @@
</para>
</refsect1>
</refentry>
<refentry id="function.getenv">
<refnamediv>
<refname>getenv</refname>
@ -194,7 +239,7 @@
<parameter>varname</parameter>, or <literal>FALSE</literal> on an error.
<informalexample>
<programlisting>
$ip = getenv ("REMOTE_ADDR"); // get the ip number of the user
$ip = getenv ("REMOTE_ADDR"); // get the ip number of the user
</programlisting>
</informalexample>
</para>
@ -294,7 +339,7 @@ $ip = getenv ("REMOTE_ADDR"); // get the ip number of the user
</funcprototype>
</funcsynopsis>
<simpara>
Returns the current active configuration setting of
Returns the current active configuration setting of
<link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>.
(0 for off, 1 for on).
</simpara>
@ -317,14 +362,14 @@ $ip = getenv ("REMOTE_ADDR"); // get the ip number of the user
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>long
<funcdef>long
<function>get_magic_quotes_runtime</function>
</funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<simpara>
Returns the current active configuration setting of
Returns the current active configuration setting of
<link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>.
(0 for off, 1 for on).
</simpara>
@ -334,7 +379,7 @@ $ip = getenv ("REMOTE_ADDR"); // get the ip number of the user
</simpara>
</refsect1>
</refentry>
<refentry id="function.getlastmod">
<refnamediv>
<refname>getlastmod</refname>
@ -418,8 +463,8 @@ echo "Last modified: ".date ("F d Y H:i:s.", getlastmod());
</para>
<warning>
<para>
Process IDs are not unique, thus they are a weak entropy
source. We recommend against relying on pids in
Process IDs are not unique, thus they are a weak entropy
source. We recommend against relying on pids in
security-dependent contexts.
</para>
</warning>
@ -467,7 +512,7 @@ echo "Last modified: ".date ("F d Y H:i:s.", getlastmod());
<funcsynopsis>
<funcprototype>
<funcdef>array <function>getrusage</function></funcdef>
<paramdef>int
<paramdef>int
<parameter><optional>who</optional></parameter>
</paramdef>
</funcprototype>
@ -489,7 +534,7 @@ echo $dat["ru_utime.tv_sec"]; # user time used (seconds)
echo $dat["ru_utime.tv_usec"]; # user time used (microseconds)
</programlisting>
</example>
See your system's man page on getrusage(2) for more details.
See your system's man page on getrusage(2) for more details.
</para>
</refsect1>
</refentry>
@ -598,7 +643,7 @@ echo $dat["ru_utime.tv_usec"]; # user time used (microseconds)
<para>
Not all the available options can be changed using
<function>ini_set</function>. Below is a table with a list of all
PHP options (as of PHP 4.0.5-dev), indicating which ones can be
PHP options (as of PHP 4.0.5-dev), indicating which ones can be
changed/set and at what level.
<table>
<title>Configuration options</title>
@ -954,7 +999,7 @@ echo $dat["ru_utime.tv_usec"]; # user time used (microseconds)
</para>
</refsect1>
</refentry>
<refentry id="function.phpcredits">
<refnamediv>
<refname>phpcredits</refname>
@ -988,7 +1033,7 @@ phpcredits(CREDITS_GENERAL);
<programlisting role="php">
&lt;?php
phpcredits(CREDITS_GROUP + CREDITS_DOCS + CREDITS_FULLPAGE);
?&gt;
?&gt;
</programlisting>
</informalexample>
And if you feel like embedding all the credits in your page, then
@ -1026,7 +1071,7 @@ phpcredits(CREDITS_GROUP + CREDITS_DOCS + CREDITS_FULLPAGE);
<row>
<entry>CREDITS_ALL</entry>
<entry>
All the credits, equivalent to using: CREDITS_DOCS + CREDITS_GENERAL +
All the credits, equivalent to using: CREDITS_DOCS + CREDITS_GENERAL +
CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE. It generates a
complete stand-alone HTML page with the appropriate tags.
</entry>
@ -1099,7 +1144,7 @@ phpcredits(CREDITS_GROUP + CREDITS_DOCS + CREDITS_FULLPAGE);
<para>
The output may be customized by passing one or more of the
following values ored together in the optional parameter
<parameter>what</parameter>.
<parameter>what</parameter>.
<itemizedlist>
<listitem><simpara>INFO_GENERAL</simpara></listitem>
<listitem><simpara>INFO_CREDITS</simpara></listitem>
@ -1144,7 +1189,7 @@ echo "Current PHP version: ".phpversion();
</example>
</para>
<para>
See also <function>phpinfo</function>,
See also <function>phpinfo</function>,
<function>phpcredits</function>,
<function>php_logo_guid</function>,
<function>zend_version</function>.
@ -1263,23 +1308,23 @@ if (substr(php_uname(), 0, 7) == "Windows") {
</funcsynopsis>
<para>
Adds <parameter>setting</parameter> to the server environment. The
environment variable will only exist for the duration of the current
request. At the end of the request the environment is restored to
environment variable will only exist for the duration of the current
request. At the end of the request the environment is restored to
its original state.
</para>
<para>
Setting certain environment variables may be a potential security breach.
The <literal>safe_mode_allowed_env_vars</literal> directive contains a
comma-delimited list of prefixes. In Safe Mode, the user may only
alter environment variables whose names begin with the prefixes
supplied by this directive. By default, users will only be able
to set environment variables that begin with <literal>PHP_</literal>
The <literal>safe_mode_allowed_env_vars</literal> directive contains a
comma-delimited list of prefixes. In Safe Mode, the user may only
alter environment variables whose names begin with the prefixes
supplied by this directive. By default, users will only be able
to set environment variables that begin with <literal>PHP_</literal>
(e.g. <literal>PHP_FOO=BAR</literal>). Note: if this directive is empty,
PHP will let the user modify ANY environment variable!
</para>
<para>
The <literal>safe_mode_protected_env_vars</literal> directive
contains a comma-delimited list of environment variables, that
The <literal>safe_mode_protected_env_vars</literal> directive
contains a comma-delimited list of environment variables, that
the end user won't be able to change using <function>putenv</function>.
These variables will be protected even if <literal>safe_mode_allowed_env_vars</literal>
is set to allow to change them.
@ -1311,7 +1356,7 @@ putenv ("UNIQID=$uniqid");
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>long
<funcdef>long
<function>set_magic_quotes_runtime</function>
</funcdef>
<paramdef>int <parameter>new_setting</parameter></paramdef>
@ -1556,7 +1601,7 @@ print_r (get_extension_funcs (&quot;gd&quot;));
<para>
This function returns an array of the names of all
the files that have been loaded into a script using
<function>require_once</function> or <function>include_once</function>.
<function>require_once</function> or <function>include_once</function>.
</para>
<note>
<para>
@ -1597,9 +1642,9 @@ print_r (get_extension_funcs (&quot;gd&quot;));
</funcsynopsis>
<para>
This function returns an array of the names of all
the files that have been loaded into a script using
the files that have been loaded into a script using
<function>require_once</function> or
<function>include_once</function>.
<function>include_once</function>.
</para>
<para>
The example below
@ -1624,12 +1669,12 @@ for ($i=1; $i&lt;5; $i++)
Required_once/Included_once files
Array
(
[0] =&gt; local.php
[0] =&gt; local.php
[1] =&gt; /full/path/to/inc/global.php
[2] =&gt; util1.php
[3] =&gt; util2.php
[4] =&gt; util3.php
[5] =&gt; util4.php
[2] =&gt; util1.php
[3] =&gt; util2.php
[4] =&gt; util3.php
[5] =&gt; util4.php
)
</programlisting>
</informalexample>
@ -1639,7 +1684,7 @@ Array
In PHP 4.0.1pl2 this function assumed that the
<varname>include_once</varname> files end in the extension
&quot;.php&quot;, other extensions do not work. Also, in that
version the array returned was an associative array, and
version the array returned was an associative array, and
listed only the included files.
</para>
</note>
@ -1676,7 +1721,7 @@ echo "Zend engine version: ".zend_version();
</example>
</para>
<para>
See also <function>phpinfo</function>,
See also <function>phpinfo</function>,
<function>phpcredits</function>,
<function>php_logo_guid</function>
<function>phpversion</function>.