zak Tue Jun 26 13:24:50 2001 EDT
Modified files:
/phpdoc/en/functions info.xml
Log:
assert()
Corrected minor grammatical and spelling mistakes
Added information on assert callback functions
Added an example of a callback function
Index: phpdoc/en/functions/info.xml
diff -u phpdoc/en/functions/info.xml:1.50 phpdoc/en/functions/info.xml:1.51
--- phpdoc/en/functions/info.xml:1.50 Mon Jun 25 15:39:59 2001
+++ phpdoc/en/functions/info.xml Tue Jun 26 13:24:50 2001
@@ -1,7 +1,7 @@
<reference id="ref.info">
<title>PHP options & 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><?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>
+ </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 @@
</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 @@
<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 @@
</simpara>
</refsect1>
</refentry>
-
+
<refentry id="function.getlastmod">
<refnamediv>
<refname>getlastmod</refname>
@@ -418,8 +463,8 @@
</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 @@
<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_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 @@
<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 @@
</para>
</refsect1>
</refentry>
-
+
<refentry id="function.phpcredits">
<refnamediv>
<refname>phpcredits</refname>
@@ -988,7 +1033,7 @@
<programlisting role="php">
<?php
phpcredits(CREDITS_GROUP + CREDITS_DOCS + CREDITS_FULLPAGE);
-?>
+?>
</programlisting>
</informalexample>
And if you feel like embedding all the credits in your page, then
@@ -1026,7 +1071,7 @@
<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 @@
<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 @@
</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 @@
</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 @@
<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 @@
<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 @@
</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 @@
Required_once/Included_once files
Array
(
- [0] => local.php
+ [0] => local.php
[1] => /full/path/to/inc/global.php
- [2] => util1.php
- [3] => util2.php
- [4] => util3.php
- [5] => util4.php
+ [2] => util1.php
+ [3] => util2.php
+ [4] => util3.php
+ [5] => util4.php
)
</programlisting>
</informalexample>
@@ -1639,7 +1684,7 @@
In PHP 4.0.1pl2 this function assumed that the
<varname>include_once</varname> files end in the extension
".php", 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 @@
</example>
</para>
<para>
- See also <function>phpinfo</function>,
+ See also <function>phpinfo</function>,
<function>phpcredits</function>,
<function>php_logo_guid</function>
<function>phpversion</function>.
