cvs: ZendAPI / Extending_Zend.ent Extending_Zend.xml Extending_Zend_ApiMacros.xml Extending_Zend_Arguments.xml Extending_Zend_Build.xml
Extending_Zend_CallingUserFunctions.xml Extending_Zend_ConfigurationMacros.xml Extending_Zend_CopyConstructor.xml Extending_Zend_Creating.xml
Extending_Zend_IniFileSupport.xml Extending_Zend_Introduction.xml Extending_Zend_Layout.xml Extending_Zend_Overview.xml
Extending_Zend_Possibilities.xml Extending_Zend_Printing.xml Extending_Zend_Returning.xml Extending_Zend_StartupAndShutdown.xml
Extending_Zend_Structure.xml Extending_Zend_Troubleshooting.xml Extending_Zend_Using.xml Extending_Zend_Variables.xml Extending_Zend_WhereToGo.xml
manual.xml

From:	Hartmut Holzgraefe	Date:	Mon, 11 Feb 2002 10:10:34 +0000
Subject:	cvs: ZendAPI / Extending_Zend.ent Extending_Zend.xml Extending_Zend_ApiMacros.xml Extending_Zend_Arguments.xml Extending_Zend_Build.xml Extending_Zend_CallingUserFunctions.xml Extending_Zend_ConfigurationMacros.xml Extending_Zend_CopyConstructor.xml Extending_Zend_Creating.xml Extending_Zend_IniFileSupport.xml Extending_Zend_Introduction.xml Extending_Zend_Layout.xml Extending_Zend_Overview.xml Extending_Zend_Possibilities.xml Extending_Zend_Printing.xml Extending_Zend_Returning.xml Extending_Zend_StartupAndShutdown.xml Extending_Zend_Structure.xml Extending_Zend_Troubleshooting.xml Extending_Zend_Using.xml Extending_Zend_Variables.xml Extending_Zend_WhereToGo.xml manual.xml
Groups:	php.cvs
Request:	Send a blank email to php-cvs+get-9347@lists.php.net to get a copy of this message

hholzgra Mon Feb 11 05:10:34 2002 EDT Modified files: /ZendAPI Extending_Zend.ent Extending_Zend.xml Extending_Zend_ApiMacros.xml Extending_Zend_Arguments.xml Extending_Zend_Build.xml Extending_Zend_CallingUserFunctions.xml Extending_Zend_ConfigurationMacros.xml Extending_Zend_CopyConstructor.xml Extending_Zend_Creating.xml Extending_Zend_IniFileSupport.xml Extending_Zend_Introduction.xml Extending_Zend_Layout.xml Extending_Zend_Overview.xml Extending_Zend_Possibilities.xml Extending_Zend_Printing.xml Extending_Zend_Returning.xml Extending_Zend_StartupAndShutdown.xml Extending_Zend_Structure.xml Extending_Zend_Troubleshooting.xml Extending_Zend_Using.xml Extending_Zend_Variables.xml Extending_Zend_WhereToGo.xml manual.xml Log: warning - this is a big one ... :( - re-indented and formated (using [x]emacs style) - added [x]emacs parameter config comments - removed some obsolete stuff - removed references to "the book" and "the CD-ROM"

Index: ZendAPI/Extending_Zend.ent diff -u ZendAPI/Extending_Zend.ent:1.2 ZendAPI/Extending_Zend.ent:1.3 --- ZendAPI/Extending_Zend.ent:1.2 Sat Jan 26 18:04:18 2002 +++ ZendAPI/Extending_Zend.ent Mon Feb 11 05:10:33 2002 @@ -1,9 +1,9 @@ -<!ENTITY testmod_module_entry ""> +<!ENTITY testmod-module-entry ""> <!ENTITY testparm ""> -<!ENTITY firstmod_module_entry ""> +<!ENTITY firstmod-module-entry ""> <!ENTITY parameter ""> <!ENTITY EG ""> -<!ENTITY function_name ""> +<!ENTITY function-name ""> <!ENTITY retval ""> <!ENTITY zendapi.intro SYSTEM "./Extending_Zend_Introduction.xml"> Index: ZendAPI/Extending_Zend.xml diff -u ZendAPI/Extending_Zend.xml:1.29 ZendAPI/Extending_Zend.xml:1.30 --- ZendAPI/Extending_Zend.xml:1.29 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend.xml Mon Feb 11 05:10:33 2002 @@ -1,26 +1,44 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - -<part id="zend"> - <title>Extending PHP 4.0</title> - <subtitle>Hacking the Core of PHP</subtitle> - &zendapi.intro; - &zendapi.overview; - &zendapi.possibilities; - &zendapi.layout; - &zendapi.build; - &zendapi.creating; - &zendapi.using; - &zendapi.troubleshooting; - &zendapi.structure; - &zendapi.arguments; - &zendapi.variables; - &zendapi.copy-constructor; - &zendapi.returning; - &zendapi.printing; - &zendapi.startup-and-shutdown; - &zendapi.calling-user-functions; - &zendapi.ini-file-support; - &zendapi.where-to-go; - &zendapi.configuration-macros; - &zendapi.api-macros; -</part> + + <part id="zend"> + <title>Extending PHP 4.0</title> + <subtitle>Hacking the Core of PHP</subtitle> + &zendapi.intro; + &zendapi.overview; + &zendapi.possibilities; + &zendapi.layout; + &zendapi.build; + &zendapi.creating; + &zendapi.using; + &zendapi.troubleshooting; + &zendapi.structure; + &zendapi.arguments; + &zendapi.variables; + &zendapi.copy-constructor; + &zendapi.returning; + &zendapi.printing; + &zendapi.startup-and-shutdown; + &zendapi.calling-user-functions; + &zendapi.ini-file-support; + &zendapi.where-to-go; + &zendapi.configuration-macros; + &zendapi.api-macros; + </part> + + Index: ZendAPI/Extending_Zend_ApiMacros.xml diff -u ZendAPI/Extending_Zend_ApiMacros.xml:1.5 ZendAPI/Extending_Zend_ApiMacros.xml:1.6 --- ZendAPI/Extending_Zend_ApiMacros.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_ApiMacros.xml Mon Feb 11 05:10:33 2002 @@ -1,86 +1,105 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.api-macros"> -<title>API Macros</title> -<para>A set of macros was introduced into Zend's API that simplify access to <envar>zval</envar> -containers (see Table 9.19).</para> - -<figure> -<title>Table 9.19. API Macros for Accessing <envar>zval</envar> Containers</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Refers to</entry> -</row> -<row> -<entry colname="col1"><literal>Z_LVAL(zval)</literal></entry> -<entry colname="col2"><envar>(zval).value.lval</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_DVAL(zval)</literal></entry> -<entry colname="col2"><envar>(zval).value.dval</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_STRVAL(zval)</literal></entry> -<entry colname="col2"><envar>(zval).value.str.val</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_STRLEN(zval)</literal></entry> -<entry colname="col2"><envar>(zval).value.str.len</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_ARRVAL(zval)</literal></entry> -<entry colname="col2"><envar>(zval).value.ht</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_LVAL_P(zval)</literal></entry> -<entry colname="col2"><envar>(*zval).value.lval</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_DVAL_P(zval)</literal></entry> -<entry colname="col2"><envar>(*zval).value.dval</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_STRVAL_P(zval_p)</literal></entry> -<entry colname="col2"><envar>(*zval).value.str.val</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_STRLEN_P(zval_p)</literal></entry> -<entry colname="col2"><envar>(*zval).value.str.len</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_ARRVAL_P(zval_p)</literal></entry> -<entry colname="col2"><envar>(*zval).value.ht</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_LVAL_PP(zval_pp)</literal></entry> -<entry colname="col2"><envar>(**zval).value.lval</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_DVAL_PP(zval_pp)</literal></entry> -<entry colname="col2"><envar>(**zval).value.dval</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_STRVAL_PP(zval_pp)</literal></entry> -<entry colname="col2"><envar>(**zval).value.str.val</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_STRLEN_PP(zval_pp)</literal></entry> -<entry colname="col2"><envar>(**zval).value.str.len</envar></entry> -</row> -<row> -<entry colname="col1"><literal>Z_ARRVAL_PP(zval_pp)</literal></entry> -<entry colname="col2"><envar>(**zval).value.ht</envar></entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -</chapter> +  + <chapter id="zend.api-macros"> + <title>API Macros</title> + <para>A set of macros was introduced into Zend's API that simplify access to <envar>zval</envar> + containers (see Table 9.19).</para> + + <figure> + <title>Table 9.19. API Macros for Accessing <envar>zval</envar> Containers</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Refers to</entry> + </row> + <row> + <entry colname="col1"><literal>Z_LVAL(zval)</literal></entry> + <entry colname="col2"><envar>(zval).value.lval</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_DVAL(zval)</literal></entry> + <entry colname="col2"><envar>(zval).value.dval</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_STRVAL(zval)</literal></entry> + <entry colname="col2"><envar>(zval).value.str.val</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_STRLEN(zval)</literal></entry> + <entry colname="col2"><envar>(zval).value.str.len</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_ARRVAL(zval)</literal></entry> + <entry colname="col2"><envar>(zval).value.ht</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_LVAL_P(zval)</literal></entry> + <entry colname="col2"><envar>(*zval).value.lval</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_DVAL_P(zval)</literal></entry> + <entry colname="col2"><envar>(*zval).value.dval</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_STRVAL_P(zval_p)</literal></entry> + <entry colname="col2"><envar>(*zval).value.str.val</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_STRLEN_P(zval_p)</literal></entry> + <entry colname="col2"><envar>(*zval).value.str.len</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_ARRVAL_P(zval_p)</literal></entry> + <entry colname="col2"><envar>(*zval).value.ht</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_LVAL_PP(zval_pp)</literal></entry> + <entry colname="col2"><envar>(**zval).value.lval</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_DVAL_PP(zval_pp)</literal></entry> + <entry colname="col2"><envar>(**zval).value.dval</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_STRVAL_PP(zval_pp)</literal></entry> + <entry colname="col2"><envar>(**zval).value.str.val</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_STRLEN_PP(zval_pp)</literal></entry> + <entry colname="col2"><envar>(**zval).value.str.len</envar></entry> + </row> + <row> + <entry colname="col1"><literal>Z_ARRVAL_PP(zval_pp)</literal></entry> + <entry colname="col2"><envar>(**zval).value.ht</envar></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + </chapter>  + Index: ZendAPI/Extending_Zend_Arguments.xml diff -u ZendAPI/Extending_Zend_Arguments.xml:1.6 ZendAPI/Extending_Zend_Arguments.xml:1.7 --- ZendAPI/Extending_Zend_Arguments.xml:1.6 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Arguments.xml Mon Feb 11 05:10:33 2002 @@ -1,185 +1,217 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.arguments"> -<title>Accepting Arguments</title> -<para>One of the most important issues for language extensions is accepting and -dealing with data passed via arguments. Most extensions are built to deal -with specific input data (or require parameters to perform their specific -actions), and function arguments are the only real way to exchange data between -the PHP level and the C level. Of course, there's also the possibility of -exchanging data using predefined global values (which is also discussed later), -but this should be avoided by all means, as it's -extremely bad practice. For details, refer to Chapter 1, "Development -Concepts."</para> -<para>PHP doesn't make use of any formal function declarations; this is why -call syntax is always completely dynamic and never checked for errors. Checking -for correct call syntax is left to the user code. For example, it's possible -to call a function using only one argument at one time and four arguments the -next time - both invocations are syntactically absolutely correct.</para> -<section id="zend.arguments.count"> -<title>Determining the Number of Arguments</title> -<para>Since PHP doesn't have formal function definitions with support for call -syntax checking, and since PHP features variable arguments, sometimes -you need to find out with how many arguments your function has been called. -You can use the <literal>ZEND_NUM_ARGS</literal> macro in this case. In previous versions -of PHP, this macro retrieved the number of arguments with which the function has been -called based on the function's hash table entry, <envar>ht</envar>, which -is passed in the <literal>INTERNAL_FUNCTION_PARAMETERS</literal> list. As -<envar>ht</envar> itself now contains the number of arguments that -have been passed to the function, <literal>ZEND_NUM_ARGS</literal> has been -stripped down to a dummy macro (see its definition in -<filename>zend_API.h</filename>). But it's still good practice to use it, -to remain compatible with future changes in the call interface. <emphasis>Note:</emphasis> The old PHP equivalent of this macro -is <literal>ARG_COUNT</literal>.</para> -<para>The following code checks for the correct number of arguments: -<programlisting>if(ZEND_NUM_ARGS() != 2) - WRONG_PARAM_COUNT;</programlisting>If the function is not called with two arguments, it exits with an error message. The code snippet above makes use of the tool macro -<literal>WRONG_PARAM_COUNT</literal>, which can be used to generate a -standard error message (see Figure 9.4).</para> -<figure> -<title>Figure 9.4. <literal>WRONG_PARAM_COUNT</literal> in action.</title><graphic fileref="figures/Extending_Zend_3_wrong_parameter_count.png"/> -</figure> -<para>This macro prints a default error message and then returns to the caller. -Its definition can also be found in <filename>zend_API.h</filename> and looks -like this: -<programlisting>ZEND_API void wrong_param_count(void); - -#define WRONG_PARAM_COUNT { wrong_param_count(); return; }</programlisting>As you can see, it calls an internal function -named <function>wrong_param_count</function> that's responsible for printing -the warning. For details on generating customized error -messages, see the later section "Printing Information."</para> -</section> - -<section id="zend.arguments.retrieval"> - <title>Retrieving Arguments</title> - - <note> - <title> - New parameter parsing API - </title> - <para> - This chapter documents the new Zend parameter parsing API - introduced by Andrei Zmievski. It was introduced in the - development stage between PHP 4.0.6 and 4.1.0 . - </para> - </note> - - <para> - Parsing parameters is a very common operation and it may get a bit - tedious. It would also be nice to have standardized error checking - and error messages. Since PHP 4.1.0, there is a way to do just - that by using the new parameter parsing API. It greatly simplifies - the process of receiving parameteres, but it has a drawback in - that it can't be used for functions that expect variable number of - parameters. But since the vast majority of functions do not fall - into those categories, this parsing API is recommended as the new - standard way. - </para> - - <para> - The prototype for parameter parsing function looks like this: - <programlisting>int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);</programlisting> - The first argument to this function is supposed to be the number - of actual parameters passed to your function, so - <literal>ZEND_NUM_ARGS()</literal> can be used for that. The - second parameter should always be <literal>TSRMLS_CC</literal> - macro. The third argument is a string that specifies the number - and types of arguments your function is expecting, similar to how - printf format string specifies the number and format of the output - values it should operate on. And finally the rest of the arguments - are pointers to variables which should receive the values from the - parameters. - </para> - - <para> - <function>zend_parse_parameters</function> also performs type - conversions whenever possible, so that you always receive the data - in the format you asked for. Any type of scalar can be converted - to another one, but conversions between complex types (arrays, - objects, and resources) and scalar types are not allowed. - </para> - - <para> - If the parameters could be obtained successfully and there were no - errors during type conversion, the function will return - <literal>SUCCESS</literal>, otherwise it will return - <literal>FAILURE</literal>. The function will output informative - error messages, if the number of received parameters does not - match the requested number, or if type conversion could not be - performed. - </para> - - <para> - Here are some sample error messages: - <screen>Warning - ini_get_all() requires at most 1 parameter, 2 given - -Warning - wddx_deserialize() expects parameter 1 to be string, array given</screen> - Of course each error message is accompanied by the filename and - line number on which it occurs. - </para> - - <para> - Here is the full list of type specifiers: - <itemizedlist> - <listitem> - <para><literal>l - </literal>long</para> - </listitem> - <listitem> - <para><literal>d - </literal>double</para> - </listitem> - <listitem> - <para><literal>s - </literal>string (with possible null bytes) and its length</para> - </listitem> - <listitem> - <para><literal>b - </literal>boolean</para> - </listitem> - <listitem> - <para><literal>r - </literal>resource, stored in <literal>zval*</literal></para> - </listitem> - <listitem> - <para><literal>a - </literal>array, stored in <literal>zval*</literal></para> - </listitem> - <listitem> - <para><literal>o - </literal>object (of any class), stored in <literal>zval*</literal></para> - </listitem> - <listitem> - <para><literal>O - </literal>object (of class specified by class entry), stored in <literal>zval*</literal></para> - </listitem> - <listitem> - <para><literal>z - </literal>the actual <literal>zval*</literal></para> - </listitem> - </itemizedlist> - The following characters also have a meaning in the specifier - string: - <itemizedlist> - <listitem> - <para><literal>| - </literal>indicates that the remaining - parameters are optional. The storage variables - corresponding to these parameters should be initialized to - default values by the extension, since they will not be - touched by the parsing function if the parameters are not - passed.</para> - </listitem> - <listitem> - <para><literal>/ - </literal>the parsing function will - call <function>SEPARATE_ZVAL_IF_NOT_REF</function> on - the parameter it follows, to provide a copy of the - parameter, unless it's a reference. </para> - </listitem> - <listitem> - <para><literal>! - </literal>the parameter it follows can - be of specified type or <literal>NULL</literal> (only - applies to a, o, O, r, and z). If <literal>NULL</literal> - value is passed by the user, the storage pointer will be - set to <literal>NULL</literal>.</para> - </listitem> - </itemizedlist> - </para> - - <para> - The best way to illustrate the usage of this function is through - examples: - <programlisting><![CDATA[/* Gets a long, a string and its length, and a zval. */ +  + <chapter id="zend.arguments"> + <title>Accepting Arguments</title> + <para> + One of the most important issues for language extensions is + accepting and dealing with data passed via arguments. Most + extensions are built to deal with specific input data (or require + parameters to perform their specific actions), and function + arguments are the only real way to exchange data between the PHP + level and the C level. Of course, there's also the possibility of + exchanging data using predefined global values (which is also + discussed later), but this should be avoided by all means, as it's + extremely bad practice. + </para> + <para> + PHP doesn't make use of any formal function declarations; this is + why call syntax is always completely dynamic and never checked for + errors. Checking for correct call syntax is left to the user code. + For example, it's possible to call a function using only one + argument at one time and four arguments the next time - both + invocations are syntactically absolutely correct. + </para> + <section id="zend.arguments.count"> + <title>Determining the Number of Arguments</title> + <para> + Since PHP doesn't have formal function definitions with support + for call syntax checking, and since PHP features variable + arguments, sometimes you need to find out with how many arguments + your function has been called. You can use the + <literal>ZEND_NUM_ARGS</literal> macro in this case. In previous + versions of PHP, this macro retrieved the number of arguments with + which the function has been called based on the function's hash + table entry, <envar>ht</envar>, which is passed in the + <literal>INTERNAL_FUNCTION_PARAMETERS</literal> list. As + <envar>ht</envar> itself now contains the number of arguments that + have been passed to the function, <literal>ZEND_NUM_ARGS</literal> + has been stripped down to a dummy macro (see its definition in + <filename>zend_API.h</filename>). But it's still good practice to + use it, to remain compatible with future changes in the call + interface. <emphasis>Note:</emphasis> The old PHP equivalent of + this macro is <literal>ARG_COUNT</literal>. + </para> + <para> + The following code checks for the correct number of arguments: + <programlisting> +if(ZEND_NUM_ARGS() != 2) WRONG_PARAM_COUNT; + </programlisting> + If the function is not called with two + arguments, it exits with an error message. The code snippet above + makes use of the tool macro <literal>WRONG_PARAM_COUNT</literal>, + which can be used to generate a standard error message (see Figure 9.4). + </para> + <figure> + <title>Figure 9.4. <literal>WRONG_PARAM_COUNT</literal> in action.</title> + <graphic fileref="figures/Extending_Zend_3_wrong_parameter_count.png"/> + </figure> + <para> + This macro prints a default error message and then returns to the caller. + Its definition can also be found in <filename>zend_API.h</filename> and looks + like this: + <programlisting> +ZEND_API void wrong_param_count(void); + +#define WRONG_PARAM_COUNT { wrong_param_count(); return; } + </programlisting> + As you can see, it calls an internal function + named <function>wrong_param_count</function> that's responsible for printing + the warning. For details on generating customized error + messages, see the later section "Printing Information." + </para> + </section> + + <section id="zend.arguments.retrieval"> + <title>Retrieving Arguments</title> + + <note> + <title> + New parameter parsing API + </title> + <para> + This chapter documents the new Zend parameter parsing API + introduced by Andrei Zmievski. It was introduced in the + development stage between PHP 4.0.6 and 4.1.0 . + </para> + </note> + + <para> + Parsing parameters is a very common operation and it may get a bit + tedious. It would also be nice to have standardized error checking + and error messages. Since PHP 4.1.0, there is a way to do just + that by using the new parameter parsing API. It greatly simplifies + the process of receiving parameteres, but it has a drawback in + that it can't be used for functions that expect variable number of + parameters. But since the vast majority of functions do not fall + into those categories, this parsing API is recommended as the new + standard way. + </para> + + <para> + The prototype for parameter parsing function looks like this: + <programlisting> +int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...); + </programlisting> + The first argument to this function is supposed to be the number + of actual parameters passed to your function, so + <literal>ZEND_NUM_ARGS()</literal> can be used for that. The + second parameter should always be <literal>TSRMLS_CC</literal> + macro. The third argument is a string that specifies the number + and types of arguments your function is expecting, similar to how + printf format string specifies the number and format of the output + values it should operate on. And finally the rest of the arguments + are pointers to variables which should receive the values from the + parameters. + </para> + + <para> + <function>zend_parse_parameters</function> also performs type + conversions whenever possible, so that you always receive the data + in the format you asked for. Any type of scalar can be converted + to another one, but conversions between complex types (arrays, + objects, and resources) and scalar types are not allowed. + </para> + + <para> + If the parameters could be obtained successfully and there were no + errors during type conversion, the function will return + <literal>SUCCESS</literal>, otherwise it will return + <literal>FAILURE</literal>. The function will output informative + error messages, if the number of received parameters does not + match the requested number, or if type conversion could not be + performed. + </para> + + <para> + Here are some sample error messages: + <screen> + Warning - ini_get_all() requires at most 1 parameter, 2 given + Warning - wddx_deserialize() expects parameter 1 to be string, array given + </screen> + Of course each error message is accompanied by the filename and + line number on which it occurs. + </para> + + <para> + Here is the full list of type specifiers: + <itemizedlist> + <listitem> + <para><literal>l - </literal>long</para> + </listitem> + <listitem> + <para><literal>d - </literal>double</para> + </listitem> + <listitem> + <para><literal>s - </literal>string (with possible null bytes) and its length</para> + </listitem> + <listitem> + <para><literal>b - </literal>boolean</para> + </listitem> + <listitem> + <para><literal>r - </literal>resource, stored in <literal>zval*</literal></para> + </listitem> + <listitem> + <para><literal>a - </literal>array, stored in <literal>zval*</literal></para> + </listitem> + <listitem> + <para><literal>o - </literal>object (of any class), stored in <literal>zval*</literal></para> + </listitem> + <listitem> + <para><literal>O - </literal>object (of class specified by class entry), stored in <literal>zval*</literal></para> + </listitem> + <listitem> + <para><literal>z - </literal>the actual <literal>zval*</literal></para> + </listitem> + </itemizedlist> + The following characters also have a meaning in the specifier + string: + <itemizedlist> + <listitem> + <para> + <literal>| - </literal>indicates that the remaining + parameters are optional. The storage variables + corresponding to these parameters should be initialized to + default values by the extension, since they will not be + touched by the parsing function if the parameters are not + passed. + </para> + </listitem> + <listitem> + <para> + <literal>/ - </literal>the parsing function will + call <function>SEPARATE_ZVAL_IF_NOT_REF</function> on + the parameter it follows, to provide a copy of the + parameter, unless it's a reference. + </para> + </listitem> + <listitem> + <para> + <literal>! - </literal>the parameter it follows can + be of specified type or <literal>NULL</literal> (only + applies to a, o, O, r, and z). If <literal>NULL</literal> + value is passed by the user, the storage pointer will be + set to <literal>NULL</literal>. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + The best way to illustrate the usage of this function is through + examples: + <programlisting> +<![CDATA[ +/* Gets a long, a string and its length, and a zval. */ long l; char *s; int s_len; @@ -189,7 +221,7 @@ return; } -* Gets an object of class specified by my_ce, and an optional double. */ +/* Gets an object of class specified by my_ce, and an optional double. */ zval *obj; double d = 0.5; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, @@ -217,37 +249,43 @@ zval *r; if (zend_parse_parameters(3, "zbr!", &z, &b, &r) == FAILURE) { return; -}]]></programlisting> - </para> - - <para> - Note that in the last example we pass 3 for the number of received - parameters, instead of <function>ZEND_NUM_ARGS</function>. What - this lets us do is receive the least number of parameters if our - function expects a variable number of them. Of course, if you want - to operate on the rest of the parameters, you will have to use - <function>zend_get_parameters_array_ex</function> to obtain - them. - </para> - - <para> - The parsing function has an extended version that allows for an - additional flags argument that controls its actions. - <programlisting>int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);</programlisting> - </para> - - <para> - The only flag you can pass currently is <literal>ZEND_PARSE_PARAMS_QUIET</literal>, - which instructs the function to not output any error messages - during its operation. This is useful for functions that expect - several sets of completely different arguments, but you will have - to output your own error messages. - </para> - - <para> - For example, here is how you would get either a set of three longs - or a string: - <programlisting><![CDATA[long l1, l2, l3; +} +]]> + </programlisting> + </para> + + <para> + Note that in the last example we pass 3 for the number of received + parameters, instead of <function>ZEND_NUM_ARGS</function>. What + this lets us do is receive the least number of parameters if our + function expects a variable number of them. Of course, if you want + to operate on the rest of the parameters, you will have to use + <function>zend_get_parameters_array_ex</function> to obtain + them. + </para> + + <para> + The parsing function has an extended version that allows for an + additional flags argument that controls its actions. + <programlisting> +int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...); + </programlisting> + </para> + + <para> + The only flag you can pass currently is <literal>ZEND_PARSE_PARAMS_QUIET</literal>, + which instructs the function to not output any error messages + during its operation. This is useful for functions that expect + several sets of completely different arguments, but you will have + to output your own error messages. + </para> + + <para> + For example, here is how you would get either a set of three longs + or a string: + <programlisting> +<![CDATA[ +long l1, l2, l3; char *s; if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC, @@ -260,73 +298,106 @@ php_error(E_WARNING, "%s() takes either three long values or a string as argument", get_active_function_name(TSRMLS_C)); return; -}]]></programlisting> - </para> +}]]> + </programlisting> + </para> - <para> - With all the abovementioned ways of receiving function parameters - you should have a good handle on this process. For even more - example, look through the source code for extensions that are - shipped with PHP - they illustrate every conceivable situation. - </para> -</section> - -<section id="zend.arguments.deprecated-retrieval"> -<title>Old way of retrieving arguments (deprecated)</title> - <note> - <title> - Deprecated parameter parsing API - </title> - <para> - This API is deprecated and superseded by the new ZEND - parameter parsing API. - </para> - </note> -<para>After having checked the number of arguments, you need to get access -to the arguments themselves. This is done with the help of <function>zend_get_parameters_ex</function>: -<programlisting><![CDATA[zval **parameter; + <para> + With all the abovementioned ways of receiving function parameters + you should have a good handle on this process. For even more + example, look through the source code for extensions that are + shipped with PHP - they illustrate every conceivable situation. + </para> + </section> + + <section id="zend.arguments.deprecated-retrieval"> + <title>Old way of retrieving arguments (deprecated)</title> + <note> + <title> + Deprecated parameter parsing API + </title> + <para> + This API is deprecated and superseded by the new ZEND + parameter parsing API. + </para> + </note> + <para> + After having checked the number of arguments, you need to get access + to the arguments themselves. This is done with the help of + <function>zend_get_parameters_ex</function>: + <programlisting> +<![CDATA[ +zval **parameter; if(zend_get_parameters_ex(1, &parameter) != SUCCESS) - WRONG_PARAM_COUNT;]]></programlisting>All arguments are stored in a <envar>zval</envar> container, -which needs to be pointed to <emphasis>twice</emphasis>. The snippet above -tries to retrieve one argument and make it available to us via the -<envar>parameter</envar> pointer.</para> -<para><function>zend_get_parameters_ex</function> accepts at least two -arguments. The first argument is the number of arguments to retrieve (which should -match the number of arguments with which the function has been called; this is why it's important to check for correct call syntax). The second argument (and all -following arguments) are pointers to pointers to pointers to -<envar>zval</envar>s. (Confusing, isn't it?) All these pointers are required -because Zend works internally with <envar>**zval</envar>; to adjust a -local <envar>**zval</envar> in our -function,<function>zend_get_parameters_ex</function> requires a pointer to -it.</para> -<para>The return value of <function>zend_get_parameters_ex</function> can -either be <literal>SUCCESS</literal> or <literal>FAILURE</literal>, indicating -(unsurprisingly) success or failure of the argument processing. A failure is most -likely related to an incorrect number of arguments being specified, in which -case you should exit with <literal>WRONG_PARAM_COUNT</literal>.</para> -<para>To retrieve more than one argument, you can use a similar snippet: -<programlisting><![CDATA[zval **param1, **param2, **param3, **param4; - + WRONG_PARAM_COUNT; +]]> + </programlisting> + All arguments are stored in a <envar>zval</envar> container, + which needs to be pointed to <emphasis>twice</emphasis>. The snippet above + tries to retrieve one argument and make it available to us via the + <envar>parameter</envar> pointer. + </para> + <para> + <function>zend_get_parameters_ex</function> accepts at least two + arguments. The first argument is the number of arguments to + retrieve (which should match the number of arguments with which + the function has been called; this is why it's important to check + for correct call syntax). The second argument (and all following + arguments) are pointers to pointers to pointers to + <envar>zval</envar>s. (Confusing, isn't it?) All these pointers + are required because Zend works internally with + <envar>**zval</envar>; to adjust a local <envar>**zval</envar> in + our function,<function>zend_get_parameters_ex</function> requires + a pointer to it. + </para> + <para> + The return value of <function>zend_get_parameters_ex</function> + can either be <literal>SUCCESS</literal> or + <literal>FAILURE</literal>, indicating (unsurprisingly) success or + failure of the argument processing. A failure is most likely + related to an incorrect number of arguments being specified, in + which case you should exit with + <literal>WRONG_PARAM_COUNT</literal>. + </para> + <para> + To retrieve more than one argument, you can use a similar snippet: + <programlisting> +<![CDATA[ +zval **param1, **param2, **param3, **param4; + if(zend_get_parameters_ex(4, &param1, &param2, &param3, &param4) != SUCCESS) - WRONG_PARAM_COUNT;]]></programlisting></para> -<para><function>zend_get_parameters_ex</function> only checks whether you're trying to retrieve too many -parameters. If the function is called -with five arguments, but you're only retrieving three of them with -<function>zend_get_parameters_ex</function>, you won't get an error but -will get the first three parameters instead. Subsequent calls of -<function>zend_get_parameters_ex</function> won't retrieve the remaining -arguments, but will get the same arguments again.</para> -</section> -<section id="zend.arguments.variable"> -<title>Dealing with a Variable Number of Arguments/Optional Parameters</title> -<para>If your function is meant to accept a variable number of arguments, the snippets just described are sometimes suboptimal solutions. You have -to create a line calling <function>zend_get_parameters_ex</function> for -every possible number of arguments, which is often unsatisfying.</para> -<para>For this case, you can use the -function <function>zend_get_parameters_array_ex</function>, which accepts the -number of parameters to retrieve and an array in which to store them: -<programlisting><![CDATA[zval **parameter_array[4]; + WRONG_PARAM_COUNT; +]]> + </programlisting> + </para> + <para> + <function>zend_get_parameters_ex</function> only checks whether + you're trying to retrieve too many parameters. If the function is + called with five arguments, but you're only retrieving three of + them with <function>zend_get_parameters_ex</function>, you won't + get an error but will get the first three parameters instead. + Subsequent calls of <function>zend_get_parameters_ex</function> + won't retrieve the remaining arguments, but will get the same + arguments again. + </para> + </section> + <section id="zend.arguments.variable"> + <title>Dealing with a Variable Number of Arguments/Optional Parameters</title> + <para> + If your function is meant to accept a variable number of + arguments, the snippets just described are sometimes suboptimal + solutions. You have to create a line calling + <function>zend_get_parameters_ex</function> for every possible + number of arguments, which is often unsatisfying. + </para> + <para> + For this case, you can use the + function <function>zend_get_parameters_array_ex</function>, which accepts the + number of parameters to retrieve and an array in which to store them: + <programlisting> +<![CDATA[ +zval **parameter_array[4]; /* get the number of arguments */ argument_count = ZEND_NUM_ARGS(); @@ -338,19 +409,26 @@ /* argument count is correct, now retrieve arguments */ if(zend_get_parameters_array_ex(argument_count, parameter_array) != SUCCESS) - WRONG_PARAM_COUNT;]]></programlisting>First, the number of arguments is checked to make sure that it's in the accepted range. After that, -<function>zend_get_parameters_array_ex</function> is used to -fill <envar>parameter_array</envar> with valid pointers to the argument -values.</para> -<para>A very clever implementation of this can be found in the code handling -PHP's <function>fsockopen</function> located -in <filename>ext/standard/fsock.c</filename>, as shown in Listing 9.7. Don't worry if -you don't know all the functions used in this source yet; we'll get to them -shortly.</para> - -<figure> -<title>Listing 9.7. PHP's implementation of variable arguments in fsockopen().</title> -<programlisting><![CDATA[ + WRONG_PARAM_COUNT; +]]> + </programlisting> + First, the number of arguments is checked to make sure that it's in the accepted range. After that, + <function>zend_get_parameters_array_ex</function> is used to + fill <envar>parameter_array</envar> with valid pointers to the argument + values. + </para> + <para> + A very clever implementation of this can be found in the code + handling PHP's <function>fsockopen</function> located in + <filename>ext/standard/fsock.c</filename>, as shown in Listing + 9.7. Don't worry if you don't know all the functions used in this + source yet; we'll get to them shortly. + </para> + + <figure> + <title>Listing 9.7. PHP's implementation of variable arguments in fsockopen().</title> + <programlisting> +<![CDATA[ pval **args[5]; int *sock=emalloc(sizeof(int)); int *sockp; @@ -395,115 +473,167 @@ convert_to_long_ex(args[1]); portno = (unsigned short) Z_LVAL_P(args[1]); -key = emalloc(Z_STRLEN_P(args[0]) + 10);]]></programlisting> -</figure> -<para><function>fsockopen</function> accepts two, three, four, or five parameters. After -the obligatory variable declarations, the function checks for the correct range -of arguments. Then it uses a fall-through mechanism in a -<literal>switch()</literal> statement to deal with all arguments. -The <literal>switch()</literal> statement starts with the maximum number of arguments being passed (five). After that, it automatically -processes the case of four arguments being passed, then three, by omitting the -otherwise obligatory <literal>break</literal> keyword in all stages. After -having processed the last case, it exits the -<literal>switch()</literal> statement and does the minimal argument processing -needed if the function is invoked with only two arguments.</para> -<para>This multiple-stage type of processing, similar to a stairway, allows -convenient processing of a variable number of arguments.</para> -</section> -<section id="zend.arguments.access"> -<title>Accessing Arguments</title> -<para>To access arguments, it's necessary for each argument to have a clearly defined -type. Again, PHP's extremely dynamic nature introduces some quirks. Because PHP never does any kind of type checking, it's possible for a -caller to pass any kind of data to your functions, whether you want it or not. -If you expect an integer, for example, the caller might pass an array, and vice versa - -PHP simply won't notice.</para> -<para>To work around this, you have to use a set of API functions to force a -type conversion on every argument that's being passed (see Table 9.4).</para><para><emphasis>Note:</emphasis> All conversion functions expect a <envar>**zval</envar> as -parameter.</para> -<figure> -<title>Table 9.4. Argument Conversion Functions</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.02*"/><colspec colnum="2" colname="col2" colwidth="1.00*"/> -<tbody> -<row> -<entry colname="col1">Function</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><function>convert_to_boolean_ex</function></entry> -<entry colname="col2">Forces conversion to a Boolean type. Boolean values remain untouched. Longs, doubles, and strings containing <literal>0</literal> as -well as NULL values will result in Boolean <literal>0</literal> (FALSE). Arrays -and objects are converted based on the number of entries or properties, -respectively, that they have. Empty arrays and objects are converted to FALSE; -otherwise, to TRUE. All other values result in a Boolean -<literal>1</literal> (TRUE).</entry> -</row> -<row> -<entry colname="col1"><function>convert_to_long_ex</function></entry> -<entry colname="col2">Forces conversion to a long, the default integer type. -NULL values, Booleans, resources, and of course longs remain untouched. -Doubles are truncated. Strings containing an integer are -converted to their corresponding numeric representation, otherwise resulting in -<literal>0</literal>. Arrays and objects are converted to <literal>0</literal> if empty, <literal>1</literal> otherwise.</entry> -</row> -<row> -<entry colname="col1"><function>convert_to_double_ex</function></entry> -<entry colname="col2">Forces conversion to a double, the default floating-point type. NULL values, Booleans, resources, longs, and of course doubles remain untouched. Strings containing a number are converted to their -corresponding numeric representation, otherwise resulting in -<literal>0.0</literal>. Arrays and objects are converted -to <literal>0.0</literal> if empty, -<literal>1.0</literal> otherwise.</entry> -</row> -<row> -<entry colname="col1"><function>convert_to_string_ex</function></entry> -<entry colname="col2">Forces conversion to a string. Strings remain untouched. -NULL values are converted to an empty string. Booleans containing TRUE are converted to <literal>"1"</literal>, otherwise resulting in an empty string. -Longs and doubles are converted to their corresponding string -representation. Arrays are converted to the string -<literal>"Array"</literal> and objects to the -string <literal>"Object"</literal>.</entry> -</row> -<row> -<entry colname="col1"><literal>convert_to_array_ex(value)</literal></entry> -<entry colname="col2">Forces conversion to an array. Arrays remain untouched. -Objects are converted to an array by assigning all their properties to the -array table. All property names are used as keys, property contents as -values. NULL values are converted to an empty array. All other values are converted to an array that contains the specific source value in the element -with the key <literal>0</literal>.</entry> -</row> -<row> -<entry colname="col1"><literal>convert_to_object_ex(value)</literal></entry> -<entry colname="col2">Forces conversion to an object. Objects remain untouched. -NULL values are converted to an empty object. Arrays are converted to -objects by introducing their keys as properties into the objects and their -values as corresponding property contents in the object. All other types result in an object with the property <literal>scalar</literal> , having the -corresponding source value as content.</entry> -</row> -<row> -<entry colname="col1"><literal>convert_to_null_ex(value)</literal></entry> -<entry colname="col2">Forces the type to become a NULL value, meaning -empty.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<note> -<para>You can find a demonstration of the behavior -in <filename>cross_conversion.php</filename> on the accompanying CD-ROM. Figure 9.5 shows the output.</para> -</note> -<figure> -<title>Figure 9.5. Cross-conversion behavior of -PHP.</title><graphic fileref="figures/Extending_Zend_4_cross_converter.png"/> -</figure> -<para>Using these functions on your arguments will ensure type safety for all -data that's passed to you. If the supplied type doesn't match the -required type, PHP forces dummy contents on the resulting value (empty -strings, arrays, or objects, <literal>0</literal> for numeric -values, <literal>FALSE</literal> for Booleans) to ensure a defined state.</para> -<para>Following is a quote from the sample module discussed -previously, which makes use of the conversion functions: -<programlisting><![CDATA[zval **parameter; +key = emalloc(Z_STRLEN_P(args[0]) + 10); +]]> + </programlisting> + </figure> + <para> + <function>fsockopen</function> accepts two, three, four, or five + parameters. After the obligatory variable declarations, the + function checks for the correct range of arguments. Then it uses a + fall-through mechanism in a <literal>switch()</literal> statement + to deal with all arguments. The <literal>switch()</literal> + statement starts with the maximum number of arguments being passed + (five). After that, it automatically processes the case of four + arguments being passed, then three, by omitting the otherwise + obligatory <literal>break</literal> keyword in all stages. After + having processed the last case, it exits the + <literal>switch()</literal> statement and does the minimal + argument processing needed if the function is invoked with only + two arguments. + </para> + <para> + This multiple-stage type of processing, similar to a stairway, allows + convenient processing of a variable number of arguments. + </para> + </section> + <section id="zend.arguments.access"> + <title>Accessing Arguments</title> + <para> + To access arguments, it's necessary for each argument to have a + clearly defined type. Again, PHP's extremely dynamic nature + introduces some quirks. Because PHP never does any kind of type + checking, it's possible for a caller to pass any kind of data to + your functions, whether you want it or not. If you expect an + integer, for example, the caller might pass an array, and vice + versa - PHP simply won't notice. + </para> + <para> + To work around this, you have to use a set of API functions to + force a type conversion on every argument that's being passed (see + Table 9.4). + </para> + <para> + <emphasis>Note:</emphasis> All conversion functions expect a + <envar>**zval</envar> as parameter. + </para> + <figure> + <title>Table 9.4. Argument Conversion Functions</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.02*"/> + <colspec colnum="2" colname="col2" colwidth="1.00*"/> + <tbody> + <row> + <entry colname="col1">Function</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><function>convert_to_boolean_ex</function></entry> + <entry colname="col2"> + Forces conversion to a Boolean type. Boolean values remain + untouched. Longs, doubles, and strings containing + <literal>0</literal> as well as NULL values will result in + Boolean <literal>0</literal> (FALSE). Arrays and objects are + converted based on the number of entries or properties, + respectively, that they have. Empty arrays and objects are + converted to FALSE; otherwise, to TRUE. All other values + result in a Boolean <literal>1</literal> (TRUE). + </entry> + </row> + <row> + <entry colname="col1"><function>convert_to_long_ex</function></entry> + <entry colname="col2"> + Forces conversion to a long, the default integer type. NULL + values, Booleans, resources, and of course longs remain + untouched. Doubles are truncated. Strings containing an + integer are converted to their corresponding numeric + representation, otherwise resulting in <literal>0</literal>. + Arrays and objects are converted to <literal>0</literal> if + empty, <literal>1</literal> otherwise. + </entry> + </row> + <row> + <entry colname="col1"><function>convert_to_double_ex</function></entry> + <entry colname="col2"> + Forces conversion to a double, the default floating-point + type. NULL values, Booleans, resources, longs, and of course + doubles remain untouched. Strings containing a number are + converted to their corresponding numeric representation, + otherwise resulting in <literal>0.0</literal>. Arrays and + objects are converted to <literal>0.0</literal> if empty, + <literal>1.0</literal> otherwise. + </entry> + </row> + <row> + <entry colname="col1"><function>convert_to_string_ex</function></entry> + <entry colname="col2"> + Forces conversion to a string. Strings remain untouched. NULL + values are converted to an empty string. Booleans containing + TRUE are converted to <literal>"1"</literal>, otherwise + resulting in an empty string. Longs and doubles are converted + to their corresponding string representation. Arrays are + converted to the string <literal>"Array"</literal> and + objects to the string <literal>"Object"</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>convert_to_array_ex(value)</literal></entry> + <entry colname="col2"> + Forces conversion to an array. Arrays remain untouched. + Objects are converted to an array by assigning all their + properties to the array table. All property names are used as + keys, property contents as values. NULL values are converted + to an empty array. All other values are converted to an array + that contains the specific source value in the element with + the key <literal>0</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>convert_to_object_ex(value)</literal></entry> + <entry colname="col2"> + Forces conversion to an object. Objects remain untouched. + NULL values are converted to an empty object. Arrays are + converted to objects by introducing their keys as properties + into the objects and their values as corresponding property + contents in the object. All other types result in an object + with the property <literal>scalar</literal> , having the + corresponding source value as content. + </entry> + </row> + <row> + <entry colname="col1"><literal>convert_to_null_ex(value)</literal></entry> + <entry colname="col2">Forces the type to become a NULL value, meaning empty.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <note> + <para> + You can find a demonstration of the behavior in + <filename>cross_conversion.php</filename> on the accompanying + CD-ROM. Figure 9.5 shows the output. + </para> + </note> + <figure> + <title>Figure 9.5. Cross-conversion behavior of PHP.</title> + <graphic fileref="figures/Extending_Zend_4_cross_converter.png"/> + </figure> + <para> + Using these functions on your arguments will ensure type safety + for all data that's passed to you. If the supplied type doesn't + match the required type, PHP forces dummy contents on the + resulting value (empty strings, arrays, or objects, + <literal>0</literal> for numeric values, <literal>FALSE</literal> + for Booleans) to ensure a defined state. + </para> + <para> + Following is a quote from the sample module discussed + previously, which makes use of the conversion functions: + <programlisting> +<![CDATA[ +zval **parameter; if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, &parameter) != SUCCESS)) { @@ -512,15 +642,21 @@ convert_to_long_ex(parameter); -RETURN_LONG(Z_LVAL_P(parameter));]]></programlisting>After retrieving the parameter pointer, the parameter value is -converted to a long (an integer), which also forms the return value of -this function. Understanding access to the contents of the value requires a -short discussion of the <envar>zval</envar> type, whose definition is shown in Listing 9.8.</para> - -<figure> -<title>Listing 9.8. PHP/Zend <envar>zval</envar> type definition.</title> -<programlisting>typedef pval zval; - +RETURN_LONG(Z_LVAL_P(parameter)); +]]> + </programlisting> + After retrieving the parameter pointer, the parameter value is + converted to a long (an integer), which also forms the return value of + this function. Understanding access to the contents of the value requires a + short discussion of the <envar>zval</envar> type, whose definition is shown in Listing 9.8. + </para> + + <figure> + <title>Listing 9.8. PHP/Zend <envar>zval</envar> type definition.</title> + <programlisting> +<![CDATA[ +typedef pval zval; + typedef struct _zval_struct zval; typedef union _zvalue_value { @@ -543,209 +679,264 @@ unsigned char type; /* active type */ unsigned char is_ref; short refcount; -};</programlisting> -</figure> -<para>Actually, <envar>pval</envar> (defined in <filename>php.h</filename>) is -only an alias of <envar>zval</envar> (defined in <filename>zend.h</filename>), -which in turn refers to <envar>_zval_struct</envar>. This is a most interesting -structure. <envar>_zval_struct</envar> is the "master" structure, containing -the value structure, type, and reference information. The substructure -<envar>zvalue_value</envar> is a union that contains the variable's contents. -Depending on the variable's type, you'll have to access different members of -this union. For a description of both structures, see Tables 9.5, 9.6, and 9.7.</para> -<figure> -<title>Table 9.5. Zend <envar>zval</envar> Structure</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.66*"/> -<tbody> -<row> -<entry colname="col1">Entry</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><envar>value</envar></entry> -<entry colname="col2">Union containing this variable's contents. See Table 9.6 -for a description.</entry> -</row> -<row> -<entry colname="col1"><envar>type</envar></entry> -<entry colname="col2">Contains this variable's type. For a list of available -types, see Table 9.7.</entry> -</row> -<row> -<entry colname="col1"><envar>is_ref</envar></entry> -<entry colname="col2">0 means that this variable is not a reference; 1 means that this variable is a reference to another variable.</entry> -</row> -<row> -<entry colname="col1"><envar>refcount</envar></entry> -<entry colname="col2">The number of references that exist for this variable. -For every new reference to the value stored in this variable, this counter is -increased by 1. For every lost reference, this counter is decreased by 1. When the reference counter reaches 0, no references exist to this value -anymore, which causes automatic freeing of the value.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<figure> -<title>Table 9.6. Zend <envar>zvalue_value</envar> Structure</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.66*"/> -<tbody> -<row> -<entry colname="col1">Entry</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><envar>lval</envar></entry> -<entry colname="col2">Use this property if the variable is of the -type <literal>IS_LONG</literal>, -<literal>IS_BOOLEAN</literal>, or <literal>IS_RESOURCE</literal>.</entry> -</row> -<row> -<entry colname="col1"><envar>dval</envar></entry> -<entry colname="col2">Use this property if the variable is of the -type <literal>IS_DOUBLE</literal>.</entry> -</row> -<row> -<entry colname="col1"><envar>str</envar></entry> -<entry colname="col2">This structure can be used to access variables of -the type <literal>IS_STRING</literal>. The member <envar>len</envar> contains the -string length; the member <envar>val</envar> points to the string itself. Zend -uses C strings; thus, the string length contains a trailing -<literal>0x00</literal>.</entry> -</row> -<row> -<entry colname="col1"><envar>ht</envar></entry> -<entry colname="col2">This entry points to the variable's hash table entry if the variable is an array.</entry> -</row> -<row> -<entry colname="col1"><envar>obj</envar></entry> -<entry colname="col2">Use this property if the variable is of the -type <literal>IS_OBJECT</literal>.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<figure> -<title>Table 9.7. Zend Variable Type Constants</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.65*"/> -<tbody> -<row> -<entry colname="col1">Constant</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>IS_NULL</literal></entry> -<entry colname="col2">Denotes a NULL (empty) value.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_LONG</literal></entry> -<entry colname="col2">A long (integer) value.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_DOUBLE</literal></entry> -<entry colname="col2">A double (floating point) value.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_STRING</literal></entry> -<entry colname="col2">A string.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_ARRAY</literal></entry> -<entry colname="col2">Denotes an array.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_OBJECT</literal></entry> -<entry colname="col2">An object.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_BOOL</literal></entry> -<entry colname="col2">A Boolean value.</entry> -</row> -<row> -<entry colname="col1"><literal>IS_RESOURCE</literal></entry> -<entry colname="col2">A resource (for a discussion of resources, see the -appropriate section below).</entry> -</row> -<row> -<entry colname="col1"><literal>IS_CONSTANT</literal></entry> -<entry colname="col2">A constant (defined) value.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<para>To access a long you access <envar>zval.value.lval</envar>, to access a double you use <envar>zval.value.dval</envar>, and so on. Because -all values are stored in a union, trying to access data with incorrect union -members results in meaningless output.</para> -<para>Accessing arrays and objects is a bit more complicated and -is discussed later.</para> -</section> -<section id="zend.arguments.by-reference"> -<title>Dealing with Arguments Passed by Reference</title> -<para>If your function accepts arguments passed by reference that you -intend to modify, you need to take some precautions.</para> -<para>What we didn't say yet is that under the circumstances presented so -far, you don't have write access to any <envar>zval</envar> containers -designating function parameters that have been passed to you. Of course, you -can change any <envar>zval</envar> containers that you created within -your function, but you mustn't change any <envar>zval</envar>s that refer to -Zend-internal data!</para> -<para>We've only discussed the so-called <function>*_ex</function> API so far. You may have noticed that the API -functions we've used are called -<function>zend_get_parameters_ex</function> instead -of <function>zend_get_parameters</function>, <function>convert_to_long_ex</function> instead -of <function>convert_to_long</function>, etc. -The <function>*_ex</function> functions form the so-called new "extended" Zend -API. They give a minor speed increase over the old API, but as a tradeoff are -only meant for providing read-only access.</para> -<para>Because Zend works internally with references, different -variables may reference the same value. Write access to a -<envar>zval</envar> container requires this container to contain an isolated -value, meaning a value that's not referenced by any other containers. -If a <envar>zval</envar> container were referenced by other containers and -you changed the referenced <envar>zval</envar>, you would automatically change the contents of the other containers referencing this -<envar>zval</envar> (because they'd simply point to the changed value and thus -change their own value as well).</para> -<para><function>zend_get_parameters_ex</function> doesn't care about this -situation, but simply returns a pointer to the desired -<envar>zval</envar> containers, whether they consist of references or not. -Its corresponding function in the traditional API, -<function>zend_get_parameters</function>, immediately checks for referenced -values. If it finds a reference, it creates a new, isolated -<envar>zval</envar> container; copies the referenced data into this newly -allocated space; and then returns a pointer to the new, isolated value.</para> -<para>This action is called <emphasis>zval -separation</emphasis> (or pval separation). Because the <function>*_ex</function> API doesn't perform zval separation, it's -considerably faster, while at the same time disabling write access.</para> -<para>To change parameters, however, write access is required. Zend deals -with this situation in a special way: Whenever a parameter to a function is -passed by reference, it performs automatic zval separation. This means that -whenever you're calling a function like -this in PHP, Zend will automatically ensure -that <envar>$parameter</envar> is being passed as an isolated value, rendering it -to a write-safe state:<programlisting>my_function(&$parameter);</programlisting></para> -<para>But this <emphasis>is not</emphasis> the case with regular parameters! -All other parameters that are not passed by reference are in a read-only -state.</para> +}; +]]> + </programlisting> + </figure> + <para> + Actually, <envar>pval</envar> (defined in <filename>php.h</filename>) is + only an alias of <envar>zval</envar> (defined in <filename>zend.h</filename>), + which in turn refers to <envar>_zval_struct</envar>. This is a most interesting + structure. <envar>_zval_struct</envar> is the "master" structure, containing + the value structure, type, and reference information. The substructure + <envar>zvalue_value</envar> is a union that contains the variable's contents. + Depending on the variable's type, you'll have to access different members of + this union. For a description of both structures, see Tables 9.5, 9.6, and 9.7. + </para> + <figure> + <title>Table 9.5. Zend <envar>zval</envar> Structure</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.66*"/> + <tbody> + <row> + <entry colname="col1">Entry</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><envar>value</envar></entry> + <entry colname="col2"> + Union containing this variable's contents. See Table 9.6 for + a description. + </entry> + </row> + <row> + <entry colname="col1"><envar>type</envar></entry> + <entry colname="col2"> + Contains this variable's type. For a list of available + types, see Table 9.7. + </entry> + </row> + <row> + <entry colname="col1"><envar>is_ref</envar></entry> + <entry colname="col2"> + 0 means that this variable is not a reference; 1 means that this variable is a reference to another variable. + </entry> + </row> + <row> + <entry colname="col1"><envar>refcount</envar></entry> + <entry colname="col2"> + The number of references that exist for this variable. For + every new reference to the value stored in this variable, + this counter is increased by 1. For every lost reference, + this counter is decreased by 1. When the reference counter + reaches 0, no references exist to this value anymore, which + causes automatic freeing of the value. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <figure> + <title>Table 9.6. Zend <envar>zvalue_value</envar> Structure</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.66*"/> + <tbody> + <row> + <entry colname="col1">Entry</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><envar>lval</envar></entry> + <entry colname="col2">Use this property if the variable is of the + type <literal>IS_LONG</literal>, + <literal>IS_BOOLEAN</literal>, or <literal>IS_RESOURCE</literal>.</entry> + </row> + <row> + <entry colname="col1"><envar>dval</envar></entry> + <entry colname="col2">Use this property if the variable is of the + type <literal>IS_DOUBLE</literal>.</entry> + </row> + <row> + <entry colname="col1"><envar>str</envar></entry> + <entry colname="col2"> + This structure can be used to access variables of + the type <literal>IS_STRING</literal>. The member <envar>len</envar> contains the + string length; the member <envar>val</envar> points to the string itself. Zend + uses C strings; thus, the string length contains a trailing + <literal>0x00</literal>.</entry> + </row> + <row> + <entry colname="col1"><envar>ht</envar></entry> + <entry colname="col2">This entry points to the variable's hash table entry if the variable is an array.</entry> + </row> + <row> + <entry colname="col1"><envar>obj</envar></entry> + <entry colname="col2">Use this property if the variable is of the + type <literal>IS_OBJECT</literal>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> -<para>This requires you to make sure that you're really working with a -reference - otherwise you might produce unwanted results. To check for a -parameter being passed by reference, you can use the macro -<literal>PZVAL_IS_REF</literal>. This macro accepts a <literal>zval*</literal> -to check if it is a reference or not. Examples are given in -in Listing 9.6 and Figure 9.9 (see the -CD-ROM for the full source).</para> -<figure> -<title>Listing 9.6. Testing for referenced parameter passing.</title> -<programlisting><![CDATA[zval *parameter; + <figure> + <title>Table 9.7. Zend Variable Type Constants</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.65*"/> + <tbody> + <row> + <entry colname="col1">Constant</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>IS_NULL</literal></entry> + <entry colname="col2">Denotes a NULL (empty) value.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_LONG</literal></entry> + <entry colname="col2">A long (integer) value.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_DOUBLE</literal></entry> + <entry colname="col2">A double (floating point) value.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_STRING</literal></entry> + <entry colname="col2">A string.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_ARRAY</literal></entry> + <entry colname="col2">Denotes an array.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_OBJECT</literal></entry> + <entry colname="col2">An object.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_BOOL</literal></entry> + <entry colname="col2">A Boolean value.</entry> + </row> + <row> + <entry colname="col1"><literal>IS_RESOURCE</literal></entry> + <entry colname="col2">A resource (for a discussion of resources, see the + appropriate section below).</entry> + </row> + <row> + <entry colname="col1"><literal>IS_CONSTANT</literal></entry> + <entry colname="col2">A constant (defined) value.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <para> + To access a long you access <envar>zval.value.lval</envar>, to + access a double you use <envar>zval.value.dval</envar>, and so on. + Because all values are stored in a union, trying to access data + with incorrect union members results in meaningless output. + </para> + <para> + Accessing arrays and objects is a bit more complicated and + is discussed later. + </para> + </section> + <section id="zend.arguments.by-reference"> + <title>Dealing with Arguments Passed by Reference</title> + <para> + If your function accepts arguments passed by reference that you + intend to modify, you need to take some precautions. + </para> + <para> + What we didn't say yet is that under the circumstances presented so + far, you don't have write access to any <envar>zval</envar> containers + designating function parameters that have been passed to you. Of course, you + can change any <envar>zval</envar> containers that you created within + your function, but you mustn't change any <envar>zval</envar>s that refer to + Zend-internal data! + </para> + <para> + We've only discussed the so-called <function>*_ex</function> API + so far. You may have noticed that the API functions we've used are + called <function>zend_get_parameters_ex</function> instead of + <function>zend_get_parameters</function>, + <function>convert_to_long_ex</function> instead of + <function>convert_to_long</function>, etc. The + <function>*_ex</function> functions form the so-called new + "extended" Zend API. They give a minor speed increase over the old + API, but as a tradeoff are only meant for providing read-only + access. + </para> + <para> + Because Zend works internally with references, different variables + may reference the same value. Write access to a + <envar>zval</envar> container requires this container to contain + an isolated value, meaning a value that's not referenced by any + other containers. If a <envar>zval</envar> container were + referenced by other containers and you changed the referenced + <envar>zval</envar>, you would automatically change the contents + of the other containers referencing this <envar>zval</envar> + (because they'd simply point to the changed value and thus change + their own value as well). + </para> + <para> + <function>zend_get_parameters_ex</function> doesn't care about + this situation, but simply returns a pointer to the desired + <envar>zval</envar> containers, whether they consist of references + or not. Its corresponding function in the traditional API, + <function>zend_get_parameters</function>, immediately checks for + referenced values. If it finds a reference, it creates a new, + isolated <envar>zval</envar> container; copies the referenced data + into this newly allocated space; and then returns a pointer to the + new, isolated value. + </para> + <para> + This action is called <emphasis>zval separation</emphasis> + (or pval separation). Because the <function>*_ex</function> API + doesn't perform zval separation, it's considerably faster, while + at the same time disabling write access. + </para> + <para> + To change parameters, however, write access is required. Zend deals + with this situation in a special way: Whenever a parameter to a function is + passed by reference, it performs automatic zval separation. This means that + whenever you're calling a function like + this in PHP, Zend will automatically ensure + that <envar>$parameter</envar> is being passed as an isolated value, rendering it + to a write-safe state: + <programlisting> +my_function(&$parameter); + </programlisting> + </para> + <para> + But this <emphasis>is not</emphasis> the case with regular parameters! + All other parameters that are not passed by reference are in a read-only + state. + </para> + + <para> + This requires you to make sure that you're really working with a + reference - otherwise you might produce unwanted results. To check for a + parameter being passed by reference, you can use the macro + <literal>PZVAL_IS_REF</literal>. This macro accepts a <literal>zval*</literal> + to check if it is a reference or not. Examples are given in + in Listing 9.6 and Figure 9.9 (see the + CD-ROM for the full source). + </para> + <figure> + <title>Listing 9.6. Testing for referenced parameter passing.</title> + <programlisting> +<![CDATA[ +zval *parameter; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &parameter) == FAILURE) return; -} /* check for parameter being passed by reference */ if (!PZVAL_IS_REF(*parameter)) { @@ -755,18 +946,26 @@ } /* make changes to the parameter */ -ZVAL_LONG(*parameter, 10);]]></programlisting><graphic fileref="figures/Extending_Zend_5_reference_test.png"/> -</figure> -</section> -<section id="zend.arguments.write-safety"> -<title>Assuring Write Safety for Other Parameters</title> -<para>You might run into a situation in which you need write access to a -parameter that's retrieved with <function>zend_get_parameters_ex</function> but not passed by reference. For this case, you can use the macro -<literal>SEPARATE_ZVAL</literal>, which does a zval separation on the provided -container. The newly generated <envar>zval</envar> is detached from internal -data and has only a local scope, meaning that it can be changed or destroyed -without implying global changes in the script context:<programlisting><![CDATA[zval **parameter; - +ZVAL_LONG(*parameter, 10); +]]> + </programlisting> + <graphic fileref="figures/Extending_Zend_5_reference_test.png"/> + </figure> + </section> + <section id="zend.arguments.write-safety"> + <title>Assuring Write Safety for Other Parameters</title> + <para> + You might run into a situation in which you need write access to a + parameter that's retrieved with <function>zend_get_parameters_ex</function> + but not passed by reference. For this case, you can use the macro + <literal>SEPARATE_ZVAL</literal>, which does a zval separation on the provided + container. The newly generated <envar>zval</envar> is detached from internal + data and has only a local scope, meaning that it can be changed or destroyed + without implying global changes in the script context: + <programlisting> +<![CDATA[ +zval **parameter; + /* retrieve parameter */ zend_get_parameters_ex(1, &parameter); @@ -777,16 +976,43 @@ SEPARATE_ZVAL(parameter); /* now we can safely modify <parameter> */ -/* without implying global changes */]]></programlisting><literal>SEPARATE_ZVAL</literal> uses <function>emalloc</function> -to allocate the new <envar>zval</envar> container, which means that even if you -don't deallocate this memory yourself, it will be destroyed automatically upon -script termination. However, doing a lot of calls to this macro -without freeing the resulting containers will clutter up your RAM.</para><para><emphasis>Note:</emphasis> As you can easily work around the lack of write access in the "traditional" API -(with <function>zend_get_parameters</function> and so on), this API seems to be obsolete, and is not discussed further in this chapter.</para> -</section> -</chapter> +/* without implying global changes */ +]]> + </programlisting> + <literal>SEPARATE_ZVAL</literal> uses <function>emalloc</function> + to allocate the new <envar>zval</envar> container, which means that even if you + don't deallocate this memory yourself, it will be destroyed automatically upon + script termination. However, doing a lot of calls to this macro + without freeing the resulting containers will clutter up your RAM. + </para> + <para> + <emphasis>Note:</emphasis> As you can easily work around the lack + of write access in the "traditional" API (with + <function>zend_get_parameters</function> and so on), this API + seems to be obsolete, and is not discussed further in this + chapter. + </para> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_Build.xml diff -u ZendAPI/Extending_Zend_Build.xml:1.4 ZendAPI/Extending_Zend_Build.xml:1.5 --- ZendAPI/Extending_Zend_Build.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Build.xml Mon Feb 11 05:10:33 2002 @@ -1,126 +1,185 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  - <chapter id="zend.build"> - <title>PHP's Automatic Build System</title> - <para>PHP 4.0 features an automatic build system that's very flexible. - All modules reside in a subdirectory of the <filename>ext</filename> directory. - In addition to its own sources, each module consists of an M4 file (for example, see - <ulink url="http://www.gnu.org/manual/m4/html_mono/m4.html">http://www.gnu.org/manual/m4/html_mono/m4.html</ulink>) - for - configuration and a Makefile.in file, - which is responsible for compilation (the results of autoconf and automake; for example, see - <ulink url="http://sourceware.cygnus.com/autoconf/autoconf.html">http://sourceware.cygnus.com/autoconf/autoconf.html</ulink> - and - <ulink url="http://sourceware.cygnus.com/automake/automake.html">http://sourceware.cygnus.com/automake/automake.html</ulink>).</para> - <para>Both files are generated automatically, along with - <filename>.cvsignore</filename>, by a little shell script named <filename>ext_skel</filename> that resides in the - <filename>ext</filename> directory. As - argument it takes the name of the module that you want to create. The shell - script then creates a directory of the same name, along with the appropriate - <filename>config.m4</filename> and <filename>Makefile.in</filename> - files.</para> - <para>Step by step, the process looks like this:<programlisting>root@dev:/usr/local/src/php4/ext > ./ext_skel my_module -Creating directory -Creating basic files: config.m4 Makefile.in .cvsignore [done]. - -To use your new extension, you will have to execute the following steps: - - $ cd .. - $ ./buildconf - $ ./configure (your extension is automatically enabled) - $ vi ext/my_module/my_module.c +  + <chapter id="zend.build"> + <title>PHP's Automatic Build System</title> + <para> + PHP 4 features an automatic build system that's very flexible. + All modules reside in a subdirectory of the + <filename>ext</filename> directory. In addition to its own sources, + each module consists of an M4 file (for example, see + <ulink url="http://www.gnu.org/manual/m4/html_mono/m4.html">http://www.gnu.org/manual/m4/html_mono/m4.html</ulink>) + for configuration and a Makefile.in file, which is responsible for compilation + (the results of autoconf and automake; for example, see + <ulink url="http://sourceware.cygnus.com/autoconf/autoconf.html">http://sourceware.cygnus.com/autoconf/autoconf.html</ulink> + and <ulink url="http://sourceware.cygnus.com/automake/automake.html">http://sourceware.cygnus.com/automake/automake.html</ulink>). + </para> + <para> + Both files are generated automatically, along with + <filename>.cvsignore</filename>, by a little shell script named + <filename>ext_skel</filename> that resides in the + <filename>ext</filename> directory. As argument it takes the name + of the module that you want to create. The shell script then + creates a directory of the same name, along with the appropriate + <filename>config.m4</filename> and <filename>Makefile.in</filename> + files. + </para> + <para> + Step by step, the process looks like + this: + <screen> +root@dev:/usr/local/src/php4/ext > ./ext_skel my_module +Creating directory +Creating basic files: config.m4 Makefile.in .cvsignore [done]. +To use your new extension, you will have to execute the following steps: + $ cd .. + $ ./buildconf + $ ./configure # (your extension is automatically enabled) + $ vi ext/my_module/my_module.c $ make - -Repeat the last two steps as often as necessary.</programlisting>This instruction creates the aforementioned files. To - include the new module in the automatic configuration and build process, -you have to run <filename>buildconf</filename>, which regenerates the - <filename>configure</filename> script by searching through the - <filename>ext</filename> directory and including all found - <filename>config.m4</filename> files.</para> - <para>Finally, running <filename>configure</filename> parses all - configuration options and generates a makefile based on those options and the options you - specify in <filename>Makefile.in</filename>.</para> - <para>Listing 9.1 shows the previously generated <filename>Makefile.in</filename>:</para> - <figure> - <title>Listing 9.1. The default <filename>Makefile.in</filename>.</title> - <programlisting># $Id: Extending_Zend_Build.xml,v 1.4 2002/02/08 17:02:46 hholzgra Exp $ - +Repeat the last two steps as often as necessary. + </screen> + This instruction creates the + aforementioned files. To include the new module in the automatic + configuration and build process, you have to run + <filename>buildconf</filename>, which regenerates the + <filename>configure</filename> script by searching through the + <filename>ext</filename> directory and including all found + <filename>config.m4</filename> files. + </para> + <para> + Finally, running <filename>configure</filename> parses all + configuration options and generates a makefile based on those + options and the options you specify in + <filename>Makefile.in</filename>. + </para> + <para> + Listing 9.1 shows the previously generated + <filename>Makefile.in</filename>: + </para> + <figure> + <title>Listing 9.1. The default <filename>Makefile.in</filename>.</title> + <programlisting> +# $Id: Extending_Zend_Build.xml,v 1.5 2002/02/11 10:10:33 hholzgra Exp $ LTLIBRARY_NAME = libmy_module.la -LTLIBRARY_SOURCES = my_module.c -LTLIBRARY_SHARED_NAME = my_module.la - -include $(top_srcdir)/build/dynlib.mk</programlisting> +LTLIBRARY_SOURCES = my_module.c +LTLIBRARY_SHARED_NAME = my_module.la include +$(top_srcdir)/build/dynlib.mk + </programlisting> </figure> - <para>There's not much to tell about this one: It contains the names of the - input and output files. You could also specify build instructions for - other files if your module is built from multiple source files.</para> - <para>The default <filename>config.m4</filename> shown in Listing 9.2 is a - bit more complex:</para> + <para> + There's not much to tell about this one: It contains the names + of the input and output files. You could also specify build + instructions for other files if your module is built from multiple + source files. + </para> + <para> + The default <filename>config.m4</filename> shown in Listing + 9.2 is a bit more complex: + </para> <figure> <title>Listing 9.2. The default <filename>config.m4</filename>.</title> - <programlisting>dnl $Id: Extending_Zend_Build.xml,v 1.4 2002/02/08 17:02:46 hholzgra Exp $ -dnl config.m4 for extension my_module -dnl don't forget to call PHP_EXTENSION(my_module) - + <programlisting> +dnl $Id: Extending_Zend_Build.xml,v 1.5 2002/02/11 10:10:33 hholzgra Exp $ +dnl config.m4 for extension my_module +dnl don't forget to call PHP_EXTENSION(my_module) dnl If your extension references something external, use with: - -PHP_ARG_WITH(my_module, for my_module support, -dnl Make sure that the comment is aligned: -[ --with-my_module Include my_module support]) - +PHP_ARG_WITH(my_module, for my_module support, +dnl Make sure that the comment is aligned: + [ --with-my_module Include my_module support]) dnl Otherwise use enable: - -PHP_ARG_ENABLE(my_module, whether to enable my_module support, -dnl Make sure that the comment is aligned: -[ --enable-my_module Enable my_module support]) - +PHP_ARG_ENABLE(my_module, whether to enable my_module support, +dnl Make sure that the comment is aligned: + [ --enable-my_module Enable my_module support]) if test "$PHP_MY_MODULE" != "no"; then - dnl Action.. - PHP_EXTENSION(my_module, $ext_shared) -fi</programlisting> -</figure> -<para>If you're unfamiliar with M4 files (now is certainly a - good time to get familiar), this might be a bit confusing at first; but it's actually quite easy.</para> -<para><emphasis>Note:</emphasis> Everything prefixed with <literal>dnl</literal> is treated as a comment - and is not parsed.</para> -<para>The <filename>config.m4</filename> file is responsible for parsing the - command-line options passed to <filename>configure</filename> at configuration - time. This means that it has to check for required external files - and do similar configuration and setup tasks.</para> -<para>The default file creates two configuration directives in the - <filename>configure</filename> script: - <literal>--with-my_module</literal> and <literal>--enable-my_module</literal>. - Use the first option when referring external files (such as the - <literal>--with-apache</literal> directive that refers to the Apache - directory). Use the second option when the user simply has to decide - whether to enable your extension. Regardless of which option you use, you should uncomment the other, unnecessary one; that is, if you're using <literal>--enable-my_module</literal>, you should remove support for <literal>--with-my_module</literal>, and vice versa.</para> -<para>By default, the <filename>config.m4</filename> file created by - <filename>ext_skel</filename> accepts both directives and automatically - enables your extension. Enabling the extension is done by using the - <literal>PHP_EXTENSION</literal> macro. To change the default behavior to include your module into the PHP binary when desired - by the user (by explicitly specifying <literal>--enable-my_module</literal> or - <literal>--with-my_module</literal>), change the test for - <literal>$PHP_MY_MODULE</literal> to <literal>== "yes"</literal>: - <programlisting>if test "$PHP_MY_MODULE" == "yes"; then - dnl Action.. - PHP_EXTENSION(my_module, $ext_shared) -fi</programlisting>This would require you to use - <literal>--enable-my_module</literal> each time when reconfiguring and - recompiling PHP.</para> -<para><emphasis>Note:</emphasis> Be sure to run <filename>buildconf</filename> every time you change - <filename>config.m4</filename>!</para> -<para>We'll go into more details on the M4 macros available to -your configuration scripts later in this chapter. For now, we'll simply -use the default files. The sample sources on the CD-ROM all have working -<filename>config.m4</filename> files. To include them into the PHP build -process, simply copy the source directories to your PHP -<filename>ext</filename> directory, run <filename>buildconf</filename>, and then -include the sample modules you want by using the appropriate -<literal>--enable-*</literal> directives -with <filename>configure</filename>.</para> -</chapter> +dnl Action.. +PHP_EXTENSION(my_module, $ext_shared) +fi + </programlisting> + </figure> + <para> + If you're unfamiliar with M4 files (now is certainly a good + time to get familiar), this might be a bit confusing at first; but + it's actually quite easy. + </para> + <para> + <emphasis>Note:</emphasis> Everything prefixed with + <literal>dnl</literal> is treated as a comment and is not + parsed. + </para> + <para> + The <filename>config.m4</filename> file is responsible for + parsing the command-line options passed to + <filename>configure</filename> at configuration time. This means + that it has to check for required external files and do similar + configuration and setup tasks. + </para> + <para> + The default file creates two configuration directives in the + <filename>configure</filename> script: + <literal>--with-my_module</literal> and + <literal>--enable-my_module</literal>. Use the first option when + referring external files (such as the + <literal>--with-apache</literal> directive that refers to the + Apache directory). Use the second option when the user simply has + to decide whether to enable your extension. Regardless of which + option you use, you should uncomment the other, unnecessary one; + that is, if you're using <literal>--enable-my_module</literal>, you + should remove support for <literal>--with-my_module</literal>, and + vice versa. + </para> + <para> + By default, the <filename>config.m4</filename> file created by + <filename>ext_skel</filename> accepts both directives and + automatically enables your extension. Enabling the extension is + done by using the <literal>PHP_EXTENSION</literal> macro. To change + the default behavior to include your module into the PHP binary + when desired by the user (by explicitly specifying + <literal>--enable-my_module</literal> or + <literal>--with-my_module</literal>), change the test for + <literal>$PHP_MY_MODULE</literal> to <literal>== "yes"</literal>: + <programlisting>if test "$PHP_MY_MODULE" == "yes"; then dnl + Action.. PHP_EXTENSION(my_module, $ext_shared) + fi</programlisting>This would require you to use + <literal>--enable-my_module</literal> each time when reconfiguring + and recompiling PHP. + </para> + <para> + <emphasis>Note:</emphasis> Be sure to run + <filename>buildconf</filename> every time you change + <filename>config.m4</filename>! + </para> + <para> + We'll go into more details on the M4 macros available to your + configuration scripts later in this chapter. For now, we'll simply + use the default files. The sample sources on the CD-ROM all have + working <filename>config.m4</filename> files. To include them into + the PHP build process, simply copy the source directories to your + PHP <filename>ext</filename> directory, run + <filename>buildconf</filename>, and then include the sample modules + you want by using the appropriate <literal>--enable-*</literal> + directives with <filename>configure</filename>. + </para> + </chapter>  + + \ No newline at end of file Index: ZendAPI/Extending_Zend_CallingUserFunctions.xml diff -u ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.6 ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.7 --- ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.6 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_CallingUserFunctions.xml Mon Feb 11 05:10:33 2002 @@ -1,50 +1,78 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.calling-user-functions"> -<title>Calling User Functions</title> -<para>You can call user functions from your own modules, which is very -handy when implementing callbacks; for example, for array walking, searching, or -simply for event-based programs.</para> -<para>User functions can be called with the -function <function>call_user_function_ex</function>. It requires a hash value -for the function table you want to access, a pointer to an object (if you want -to call a method), the function name, return value, number of arguments, -argument array, and a flag indicating whether you want to perform zval separation. -<programlisting>ZEND_API int call_user_function_ex(HashTable *function_table, zval *object, - zval *function_name, zval **retval_ptr_ptr, - int param_count, zval **params[], - int no_separation);</programlisting>Note that you don't have to specify -both <envar>function_table</envar> and <envar>object</envar>; -either will do. If you want to call a method, you have to supply -the object that contains this method, in which case <function>call_user_function</function>automatically -sets the function table to this object's function table. Otherwise, you only -need to specify <envar>function_table</envar> and can set <envar>object</envar> to -<literal>NULL</literal>.</para> -<para>Usually, the default function table is the "root" function table -containing all function entries. This function table is part of the compiler -globals and can be accessed using the macro <literal>CG</literal>. To introduce -the compiler globals to your function, call the macro <literal>CLS_FETCH</literal> once.</para> -<para>The function name is specified in a <envar>zval</envar> container. This -might be a bit surprising at first, but is quite a logical step, since most -of the time you'll accept function names as parameters from calling functions -within your script, which in turn are contained in <envar>zval</envar> containers -again. Thus, you only have to pass your arguments through to this function. This <envar>zval</envar> must be of type <literal>IS_STRING</literal>.</para> -<para>The next argument consists of a pointer to the return value. You don't have to allocate memory for this container; the function will do so by -itself. However, you have to destroy this container (using -<function>zval_dtor</function>) afterward!</para> -<para>Next is the parameter count as integer and an array containing all -necessary parameters. The last argument specifies whether the function should perform zval -separation - this should always be set to <literal>0</literal>. If set -to <literal>1</literal>, the function consumes less memory but fails if any of the parameters need separation.</para> -<para>Listing 9.16 and Figure 9.11 show a small demonstration of calling a user -function. The code calls a function that's supplied to it as argument and -directly passes this function's return value through as its own return value. -Note the use of the constructor and destructor calls at the end - it might -not be necessary to do it this way here (since they should be separate values, -the assignment might be safe), but this is bulletproof.</para> -<figure> -<title>Listing 9.16. Calling user functions.</title> -<programlisting>zval **function_name; +  + <chapter id="zend.calling-user-functions"> + <title>Calling User Functions</title> + <para> + You can call user functions from your own modules, which is very + handy when implementing callbacks; for example, for array walking, searching, or + simply for event-based programs. + </para> + <para> + User functions can be called with the + function <function>call_user_function_ex</function>. It requires a hash value + for the function table you want to access, a pointer to an object (if you want + to call a method), the function name, return value, number of arguments, + argument array, and a flag indicating whether you want to perform zval separation. + </para> + <programlisting> +ZEND_API int call_user_function_ex(HashTable *function_table, zval *object, +zval *function_name, zval **retval_ptr_ptr, +int param_count, zval **params[], +int no_separation); + </programlisting> + <para> + Note that you don't have to specify both + <envar>function_table</envar> and <envar>object</envar>; either + will do. If you want to call a method, you have to supply the + object that contains this method, in which case + <function>call_user_function</function>automatically sets the + function table to this object's function table. Otherwise, you only + need to specify <envar>function_table</envar> and can set + <envar>object</envar> to <literal>NULL</literal>. + </para> + <para> + Usually, the default function table is the "root" function table + containing all function entries. This function table is part of the + compiler globals and can be accessed using the macro + <literal>CG</literal>. To introduce the compiler globals to your + function, call the macro <literal>CLS_FETCH</literal> once. + </para> + <para> + The function name is specified in a <envar>zval</envar> + container. This might be a bit surprising at first, but is quite a + logical step, since most of the time you'll accept function names + as parameters from calling functions within your script, which in + turn are contained in <envar>zval</envar> containers again. Thus, + you only have to pass your arguments through to this function. This + <envar>zval</envar> must be of type <literal>IS_STRING</literal>. + </para> + <para> + The next argument consists of a pointer to the return value. You + don't have to allocate memory for this container; the function will + do so by itself. However, you have to destroy this container (using + <function>zval_dtor</function>) afterward! + </para> + <para> + Next is the parameter count as integer and an array containing all + necessary parameters. The last argument specifies whether the + function should perform zval separation - this should always be set + to <literal>0</literal>. If set to <literal>1</literal>, the + function consumes less memory but fails if any of the parameters + need separation. + </para> + <para> + Listing 9.16 and Figure 9.11 show a small demonstration of + calling a user function. The code calls a function that's supplied + to it as argument and directly passes this function's return value + through as its own return value. Note the use of the constructor + and destructor calls at the end - it might not be necessary to do + it this way here (since they should be separate values, the + assignment might be safe), but this is bulletproof. + </para> + <figure> + <title>Listing 9.16. Calling user functions.</title> + <programlisting> +zval **function_name; zval *retval; if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, &function_name) != SUCCESS)) @@ -68,10 +96,12 @@ *return_value = *retval; zval_copy_ctor(return_value); -zval_ptr_dtor(&retval);</programlisting> -</figure> -<para/> -<programlisting><?php +zval_ptr_dtor(&retval); + </programlisting> + </figure> + <para/> + <programlisting> +<?php dl("call_userland.so"); @@ -87,10 +117,29 @@ $return_value = call_userland("test_function"); print("Return value: \"$return_value\"<br>"); -?></programlisting><graphic fileref="figures/Extending_Zend_11_userland.png"/> -</chapter> +?> + </programlisting> + <graphic fileref="figures/Extending_Zend_11_userland.png"/> + </chapter>  + Index: ZendAPI/Extending_Zend_ConfigurationMacros.xml diff -u ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.4 ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.5 --- ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_ConfigurationMacros.xml Mon Feb 11 05:10:33 2002 @@ -1,82 +1,108 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.configuration-macros"> -<title>Reference: Some Configuration Macros</title> -<section id="zend.configuration-macros.config-m4"> -<title><filename>config.m4</filename></title> -<para>The file <filename>config.m4</filename> is processed by -<filename>buildconf</filename> and must contain all the instructions to be -executed during configuration. For example, these can include tests for required -external files, such as header files, libraries, and so on. PHP defines a set of macros -that can be used in this process, the most useful of which are described in Table 9.18.</para> -<figure> -<title>Table 9.18. M4 Macros for <filename>config.m4</filename></title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.63*"/><colspec colnum="2" colname="col2" colwidth="1.00*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>AC_MSG_CHECKING(message)</literal></entry> -<entry colname="col2">Prints a "checking <message>" text -during <filename>configure</filename>.</entry> -</row> -<row> -<entry colname="col1"><literal>AC_MSG_RESULT(value)</literal></entry> -<entry colname="col2">Gives the result to <literal>AC_MSG_CHECKING</literal>; -should specify either <literal>yes</literal> or <literal>no</literal> as <envar>value</envar>.</entry> - -</row> -<row> -<entry colname="col1"><literal>AC_MSG_ERROR(message)</literal></entry> -<entry colname="col2">Prints <envar>message</envar> as error message -during <filename>configure</filename> and aborts the script.</entry> -</row> -<row> -<entry colname="col1"><literal>AC_DEFINE(name,value,description)</literal></entry> -<entry colname="col2">Adds -<literal>#define</literal> to <filename>php_config.h</filename> with the value of -<envar>value</envar> and a comment that says <envar>description</envar> (this -is useful for conditional compilation of your module).</entry> -</row> -<row> -<entry colname="col1"><literal>AC_ADD_INCLUDE(path)</literal></entry> -<entry colname="col2">Adds a compiler include path; for example, used if the -module needs to add search paths for header files.</entry> -</row> -<row> -<entry colname="col1"><literal>AC_ADD_LIBRARY_WITH_PATH(libraryname,librarypath)</literal></entry> -<entry colname="col2">Specifies an additional library to link.</entry> -</row> -<row> -<entry colname="col1"><literal>AC_ARG_WITH(modulename,description,unconditionaltest,conditionaltest)</literal></entry> -<entry colname="col2">Quite a powerful macro, adding the module with -<envar>description</envar> to the <filename>configure --help</filename> output. -PHP checks whether the option <literal>--with-<modulename></literal> is -given to the <filename>configure</filename> script. If so, it runs the -script <literal>unconditionaltest</literal> (for example, <literal>--with-myext=yes</literal>), in which case the value of -the option is contained in the variable <envar>$withval</envar>. Otherwise, it -executes <literal>conditionaltest</literal>.</entry> -</row> -<row> -<entry colname="col1"><literal>PHP_EXTENSION(modulename, -[shared])</literal></entry> -<entry colname="col2">This macro is a <emphasis>must</emphasis> to call for PHP -to configure your extension. You can supply a second argument -in addition to your module name, indicating whether you intend compilation as a -shared module. This will result in a definition at compile time for your -source as <literal>COMPILE_DL_<modulename></literal>.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -</section> -</chapter> +  + <chapter id="zend.configuration-macros"> + <title>Reference: Some Configuration Macros</title> + <section id="zend.configuration-macros.config-m4"> + <title><filename>config.m4</filename></title> + <para> + The file <filename>config.m4</filename> is processed by + <filename>buildconf</filename> and must contain all the instructions to be + executed during configuration. For example, these can include tests for required + external files, such as header files, libraries, and so on. PHP defines a set of macros + that can be used in this process, the most useful of which are described in Table 9.18. + </para> + <figure> + <title>Table 9.18. M4 Macros for <filename>config.m4</filename></title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.63*"/> + <colspec colnum="2" colname="col2" colwidth="1.00*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>AC_MSG_CHECKING(message)</literal></entry> + <entry colname="col2">Prints a "checking <message>" text + during <filename>configure</filename>.</entry> + </row> + <row> + <entry colname="col1"><literal>AC_MSG_RESULT(value)</literal></entry> + <entry colname="col2">Gives the result to <literal>AC_MSG_CHECKING</literal>; + should specify either <literal>yes</literal> or <literal>no</literal> as <envar>value</envar>.</entry> + + </row> + <row> + <entry colname="col1"><literal>AC_MSG_ERROR(message)</literal></entry> + <entry colname="col2">Prints <envar>message</envar> as error message + during <filename>configure</filename> and aborts the script.</entry> + </row> + <row> + <entry colname="col1"><literal>AC_DEFINE(name,value,description)</literal></entry> + <entry colname="col2">Adds + <literal>#define</literal> to <filename>php_config.h</filename> with the value of + <envar>value</envar> and a comment that says <envar>description</envar> (this + is useful for conditional compilation of your module).</entry> + </row> + <row> + <entry colname="col1"><literal>AC_ADD_INCLUDE(path)</literal></entry> + <entry colname="col2">Adds a compiler include path; for example, used if the + module needs to add search paths for header files.</entry> + </row> + <row> + <entry colname="col1"><literal>AC_ADD_LIBRARY_WITH_PATH(libraryname,librarypath)</literal></entry> + <entry colname="col2">Specifies an additional library to link.</entry> + </row> + <row> + <entry colname="col1"><literal>AC_ARG_WITH(modulename,description,unconditionaltest,conditionaltest)</literal></entry> + <entry colname="col2">Quite a powerful macro, adding the + module with <envar>description</envar> to the + <filename>configure --help</filename> output. PHP checks + whether the option + <literal>--with-<modulename></literal> is given to the + <filename>configure</filename> script. If so, it runs the + script <literal>unconditionaltest</literal> (for example, + <literal>--with-myext=yes</literal>), in which case the value + of the option is contained in the variable + <envar>$withval</envar>. Otherwise, it executes + <literal>conditionaltest</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>PHP_EXTENSION(modulename, + [shared])</literal></entry> + <entry colname="col2">This macro is a <emphasis>must</emphasis> to call for PHP + to configure your extension. You can supply a second argument + in addition to your module name, indicating whether you intend compilation as a + shared module. This will result in a definition at compile time for your + source as <literal>COMPILE_DL_<modulename></literal>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_CopyConstructor.xml diff -u ZendAPI/Extending_Zend_CopyConstructor.xml:1.5 ZendAPI/Extending_Zend_CopyConstructor.xml:1.6 --- ZendAPI/Extending_Zend_CopyConstructor.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_CopyConstructor.xml Mon Feb 11 05:10:33 2002 @@ -1,64 +1,111 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.copy-constructor"> -<title>Duplicating Variable Contents: The Copy Constructor</title> -<para>Sooner or later, you may need to -assign the contents of one <envar>zval</envar> container to another. This is -easier said than done, since the <envar>zval</envar> container doesn't contain only type information, but also references to places in Zend's internal -data. For example, depending on their size, arrays and objects may be nested with lots of hash table entries. By assigning one <envar>zval</envar> to -another, you avoid duplicating the hash table entries, using only a reference to -them (at most).</para> -<para>To copy this complex kind of data, use the <emphasis>copy -constructor</emphasis>. Copy constructors are typically defined in languages -that support operator overloading, with the express purpose of copying complex types. If you define an object in such -a language, you have the possibility of overloading the "=" operator, which is -usually responsible for assigning the contents of the lvalue (result of the -evaluation of the left side of the operator) to the rvalue (same for the right -side).</para> -<para><emphasis>Overloading</emphasis> means assigning a different meaning to this operator, and is -usually used to assign a function call to an operator. Whenever this operator -would be used on such an object in a program, this function would -be called with the lvalue and rvalue as parameters. Equipped with that -information, it can perform the operation it intends the "=" -operator to have (usually an extended form of copying).</para> -<para>This same form of "extended copying" is also necessary for -PHP's <envar>zval</envar> containers. Again, in the case of an array, this -extended copying would imply re-creation of all hash table entries relating to -this array. For strings, proper memory allocation would have to be assured, and so on.</para> -<para>Zend ships with such a function, -called <function>zend_copy_ctor</function> (the previous PHP equivalent -was <function>pval_copy_constructor</function>).</para> -<para>A most useful demonstration is a function that accepts a complex type as -argument, modifies it, and then returns the argument: -<programlisting>zval *parameter; - +  + <chapter id="zend.copy-constructor"> + <title>Duplicating Variable Contents: The Copy Constructor</title> + <para> + Sooner or later, you may need to assign the contents of one + <envar>zval</envar> container to another. This is easier said than + done, since the <envar>zval</envar> container doesn't contain only + type information, but also references to places in Zend's internal + data. For example, depending on their size, arrays and objects may + be nested with lots of hash table entries. By assigning one + <envar>zval</envar> to another, you avoid duplicating the hash + table entries, using only a reference to them (at most). + </para> + <para> + To copy this complex kind of data, use the <emphasis>copy + constructor</emphasis>. Copy constructors are typically defined in + languages that support operator overloading, with the express + purpose of copying complex types. If you define an object in such a + language, you have the possibility of overloading the "=" operator, + which is usually responsible for assigning the contents of the + lvalue (result of the evaluation of the left side of the operator) + to the rvalue (same for the right side). + </para> + <para> + <emphasis>Overloading</emphasis> means assigning a different + meaning to this operator, and is usually used to assign a function + call to an operator. Whenever this operator would be used on such + an object in a program, this function would be called with the + lvalue and rvalue as parameters. Equipped with that information, it + can perform the operation it intends the "=" operator to have + (usually an extended form of copying). + </para> + <para> + This same form of "extended copying" is also necessary for PHP's + <envar>zval</envar> containers. Again, in the case of an array, + this extended copying would imply re-creation of all hash table + entries relating to this array. For strings, proper memory + allocation would have to be assured, and so on. + </para> + <para> + Zend ships with such a function, + called <function>zend_copy_ctor</function> (the previous PHP equivalent + was <function>pval_copy_constructor</function>). + </para> + <para> + A most useful demonstration is a function that accepts a complex type as + argument, modifies it, and then returns the argument: + </para> + <programlisting> +zval *parameter; + if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &parameter) == FAILURE) - return; + return; } - + // do modifications to the parameter here // now we want to return the modified container: *return_value == *parameter; -zval_copy_ctor(return_value);</programlisting>The first part of the function is plain-vanilla argument -retrieval. After the (left out) modifications, however, it gets interesting: The -container of <envar>parameter</envar> is assigned to the -(predefined) <envar>return_value</envar> container. Now, in order to effectively -duplicate its contents, the copy constructor is called. The copy -constructor works directly with the supplied argument, and the standard return -values are <literal>FAILURE</literal> on failure and <literal>SUCCESS</literal> on -success.</para> -<para>If you omit the call to the copy constructor in this example, -both <envar>parameter</envar> and <envar>return_value</envar> would point -to the same internal data, meaning that <envar>return_value</envar> would be an -illegal additional reference to the same data structures. Whenever changes -occurred in the data that <envar>parameter</envar> points to, <envar>return_value</envar> might -be affected. Thus, in order to create separate copies, the copy -constructor must be used.</para><para>The copy constructor's counterpart in the Zend API, the -destructor <function>zval_dtor</function>, does the opposite of the constructor.</para> -</chapter> +zval_copy_ctor(return_value); + </programlisting> + <para> + The first part of the function is plain-vanilla argument retrieval. + After the (left out) modifications, however, it gets interesting: + The container of <envar>parameter</envar> is assigned to the + (predefined) <envar>return_value</envar> container. Now, in order + to effectively duplicate its contents, the copy constructor is + called. The copy constructor works directly with the supplied + argument, and the standard return values are + <literal>FAILURE</literal> on failure and + <literal>SUCCESS</literal> on success. + </para> + <para> + If you omit the call to the copy constructor in this example, both + <envar>parameter</envar> and <envar>return_value</envar> would + point to the same internal data, meaning that + <envar>return_value</envar> would be an illegal additional + reference to the same data structures. Whenever changes occurred in + the data that <envar>parameter</envar> points to, + <envar>return_value</envar> might be affected. Thus, in order to + create separate copies, the copy constructor must be used. + </para> + <para> + The copy constructor's counterpart in the Zend API, the destructor + <function>zval_dtor</function>, does the opposite of the + constructor. + </para> + </chapter>  + Index: ZendAPI/Extending_Zend_Creating.xml diff -u ZendAPI/Extending_Zend_Creating.xml:1.4 ZendAPI/Extending_Zend_Creating.xml:1.5 --- ZendAPI/Extending_Zend_Creating.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Creating.xml Mon Feb 11 05:10:33 2002 @@ -1,14 +1,16 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.creating"> -<title>Creating Extensions</title> -<para>We'll start with the creation of a very simple extension at first, which -basically does nothing more than implement a function that returns the -integer it receives as parameter. Listing 9.3 shows the -source.</para> -<figure> -<title>Listing 9.3. A simple extension.</title> -<programlisting>/* include standard header */ +  + <chapter id="zend.creating"> + <title>Creating Extensions</title> + <para> + We'll start with the creation of a very simple extension at first, which + basically does nothing more than implement a function that returns the + integer it receives as parameter. Listing 9.3 shows the source. + </para> + <figure> + <title>Listing 9.3. A simple extension.</title> + <programlisting role="C"> +/* include standard header */ #include "php.h" /* declaration of functions to be exported */ @@ -27,7 +29,11 @@ STANDARD_MODULE_HEADER, "First Module", firstmod_functions, - NULL, NULL, NULL, NULL, NULL, + NULL, + NULL, + NULL, + NULL, + NULL, NO_VERSION_YET, STANDARD_MODULE_PROPERTIES }; @@ -47,105 +53,163 @@ } RETURN_LONG(parmeter); -}</programlisting> -</figure> -<para>This code contains a complete PHP module. We'll explain the source code in detail shortly, but first we'd like to -discuss the build process. (This will allow the impatient to experiment -before we dive into API discussions.)</para> -<section id="zend.creating.compiling"> -<title>Compiling Modules</title> -<para>There are basically three ways to compile modules: -<itemizedlist> - <listitem> - <para>Use the provided "make" mechanism in the <filename>dl</filename> - directory.</para> - </listitem> - <listitem> - <para>Use the provided "make" mechanism in the <filename>ext</filename> - directory, which also allows building of dynamic loadable modules.</para> - </listitem> - <listitem> - <para>Compile the sources manually.</para> - </listitem> -</itemizedlist>The second method should definitely be favored, since, as -of PHP 4.0, this has been standardized into a sophisticated build process. The -fact that it is so sophisticated is also its drawback, unfortunately - it's hard to understand at first. We'll provide a more -detailed introduction to this later in the chapter, but first let's work with the default files.</para> -<para>The make process contained in the <filename>dl</filename> directory is a -bit of a dirty hack, outdated and planned for removal from the source tree. To be -honest, it's much simpler to use this at first to build dynamic extensions, but because it doesn't have the possibilities of the -<filename>ext</filename> directory and it's scheduled for deletion anyway, usage of -the <filename>dl</filename> directory is deprecated.</para> -<para>The third method is good for those who (for some reason) don't have the -full PHP source tree available, don't have access to all files, or just like to -juggle with their keyboard. These cases should be extremely rare, but for the -sake of completeness we'll also describe this method.</para> -<formalpara> -<title>Compiling Using Make</title> -<para>To compile the sample sources using the standard mechanism, copy all their subdirectories to the <filename>ext</filename> directory of your - PHP source tree. Then run <filename>buildconf</filename>, which will create a - new <filename>configure</filename> script containing appropriate options. By default, all the sample sources are disabled, so you don't have to - fear breaking your build process.</para> -</formalpara> -<para>After you run <filename>buildconf</filename>, <filename>configure ---help</filename> shows the following additional modules: -<programlisting> --enable-array_experiments BOOK: Enables array experiments +} + </programlisting> + </figure> + <para> + This code contains a complete PHP module. We'll explain the source + code in detail shortly, but first we'd like to discuss the build + process. (This will allow the impatient to experiment before we + dive into API discussions.) + </para> + <note> + <para> + The example source makes use of some features introduced with the Zend version + used in PHP 4.1.0 and above, it won't compile with older PHP 4.0.x versions. + </para> + </note> + <section id="zend.creating.compiling"> + <title>Compiling Modules</title> + <para> + There are basically two ways to compile modules: + <itemizedlist> + <listitem> + <para> + Use the provided "make" mechanism in the + <filename>ext</filename> directory, which also allows building + of dynamic loadable modules. + </para> + </listitem> + <listitem> + <para>Compile the sources manually.</para> + </listitem> + </itemizedlist> + The first method should definitely be favored, + since, as of PHP 4.0, this has been standardized into a + sophisticated build process. The fact that it is so sophisticated + is also its drawback, unfortunately - it's hard to understand at + first. We'll provide a more detailed introduction to this later in + the chapter, but first let's work with the default files. + </para> + <para> + The second method is good for those who (for some reason) don't + have the full PHP source tree available, don't have access to all + files, or just like to juggle with their keyboard. These cases + should be extremely rare, but for the sake of completeness we'll + also describe this method. + </para> + <formalpara> + <title>Compiling Using Make</title> + <para> + To compile the sample sources using the standard mechanism, copy + all their subdirectories to the <filename>ext</filename> + directory of your PHP source tree. Then run + <filename>buildconf</filename>, which will create an updated + <filename>configure</filename> script containing appropriate + options for the new extension. By default, all the sample sources + are disabled, so you don't have to fear breaking your build + process. + </para> + </formalpara> + <para> + After you run <filename>buildconf</filename>, <filename>configure + --help</filename> shows the following additional modules: + </para> + <screen> + --enable-array_experiments BOOK: Enables array experiments --enable-call_userland BOOK: Enables userland module --enable-cross_conversion BOOK: Enables cross-conversion module --enable-first_module BOOK: Enables first module --enable-infoprint BOOK: Enables infoprint module --enable-reference_test BOOK: Enables reference test module --enable-resource_test BOOK: Enables resource test module - --enable-variable_creation BOOK: Enables variable-creation module</programlisting>The module shown earlier in Listing 9.3 can -be enabled with <literal>--enable-first_module</literal> or <literal>--enable-first_module=yes</literal>.</para> -<formalpara> -<title>Compiling Manually</title> -<para>To compile your modules manually, you need the following commands: - -<informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="3.94*"/> - <tbody> - <row> - <entry colname="col1">Action</entry> - <entry colname="col2">Command</entry> + --enable-variable_creation BOOK: Enables variable-creation module + </screen> + <para> + The module shown earlier in Listing 9.3 can be enabled with + <literal>--enable-first_module</literal> or + <literal>--enable-first_module=yes</literal>. + </para> + <formalpara> + <title>Compiling Manually</title> + <para> + To compile your modules manually, you need the following commands: + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="3.94*"/> + <tbody> + <row> + <entry colname="col1">Action</entry> + <entry colname="col2">Command</entry> + </row> + <row> + <entry colname="col1">Compiling</entry> + <entry colname="col2">cc -fpic -DCOMPILE_DL=1 -I/usr/local/include -I. + -I.. -I../Zend -c -o <filename><your_object_file></filename> + <filename><your_c_file></filename></entry> </row> - <row> - <entry colname="col1">Compiling</entry> - <entry colname="col2">cc -fpic -DCOMPILE_DL=1 -I/usr/local/include -I. - -I.. -I../Zend -c -o <filename><your_object_file></filename> - <filename><your_c_file></filename></entry> - </row> - <row> + <row> <entry colname="col1">Linking</entry> <entry colname="col2">cc -shared -L/usr/local/lib -rdynamic -o <filename><your_module_file></filename> <filename><your_object_file(s)></filename></entry> </row> - </tbody> - </tgroup> -</informaltable>The command to compile the module simply instructs the compiler -to generate position-independent code (<literal>-fpic</literal> shouldn't be -omitted) and additionally defines the constant <literal>COMPILE_DL</literal> to -tell the module code that it's compiled as a dynamically loadable module (the -test module above checks for this; we'll discuss it shortly). After these -options, it specifies a number of standard include paths that should be used -as the minimal set to compile the source files. -</para> -</formalpara> -<para><emphasis>Note:</emphasis> All include paths in the example are relative to the directory - <filename>ext</filename>. If you're compiling from another directory, change the pathnames accordingly. Required items are the PHP - directory, the <filename>Zend</filename> directory, and (if necessary), the directory in which your module resides.</para> - <para>The link command is also a plain vanilla command instructing linkage as a dynamic module.</para> - <para>You can include optimization options in the compilation -command, although these have been omitted in this example (but some are included in the makefile -template described in an earlier section).</para> -<para><emphasis>Note:</emphasis> Compiling and linking manually as a static module into the PHP binary involves very -long instructions and thus is not discussed here. (It's not very -efficient to type all those commands.)</para> -</section> -</chapter> + </tbody> + </tgroup> + </informaltable> + The command to compile the module simply instructs the compiler + to generate position-independent code (<literal>-fpic</literal> shouldn't be + omitted) and additionally defines the constant <literal>COMPILE_DL</literal> to + tell the module code that it's compiled as a dynamically loadable module (the + test module above checks for this; we'll discuss it shortly). After these + options, it specifies a number of standard include paths that should be used + as the minimal set to compile the source files. + </para> + </formalpara> + <para> + <emphasis>Note:</emphasis> All include paths in the example are + relative to the directory <filename>ext</filename>. If you're + compiling from another directory, change the pathnames + accordingly. Required items are the PHP directory, the + <filename>Zend</filename> directory, and (if necessary), the + directory in which your module resides. + </para> + <para> + The link command is also a plain vanilla command instructing linkage as a dynamic module. + </para> + <para> + You can include optimization options in the compilation + command, although these have been omitted in this example (but some are included in the makefile + template described in an earlier section). + </para> + <para> + <emphasis>Note:</emphasis> Compiling and linking manually as a + static module into the PHP binary involves very long instructions + and thus is not discussed here. (It's not very efficient to type + all those commands.) + </para> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_IniFileSupport.xml diff -u ZendAPI/Extending_Zend_IniFileSupport.xml:1.4 ZendAPI/Extending_Zend_IniFileSupport.xml:1.5 --- ZendAPI/Extending_Zend_IniFileSupport.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_IniFileSupport.xml Mon Feb 11 05:10:33 2002 @@ -1,36 +1,48 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.ini-file-support"> -<title>Initialization File Support</title> -<para>PHP 4 features a redesigned initialization file support. It's now -possible to specify default initialization entries directly in your code, read -and change these values at runtime, and create message handlers for change -notifications.</para> -<para>To create an .ini section in your own module, use the -macros <literal>PHP_INI_BEGIN()</literal> to mark the beginning of such a -section and <literal>PHP_INI_END()</literal> to mark its end. In between you can -use <literal>PHP_INI_ENTRY()</literal> to create entries.<programlisting>PHP_INI_BEGIN() - PHP_INI_ENTRY("first_ini_entry", "has_string_value", PHP_INI_ALL, NULL) - PHP_INI_ENTRY("second_ini_entry", "2", PHP_INI_SYSTEM, OnChangeSecond) - PHP_INI_ENTRY("third_ini_entry", "xyz", PHP_INI_USER, NULL) -PHP_INI_END()</programlisting>The <literal>PHP_INI_ENTRY()</literal> macro accepts four -parameters: the entry name, the entry value, its change permissions, and a -pointer to a change-notification handler. Both entry name and value must be -specified as strings, regardless of whether they really are strings or -integers.</para> -<para>The permissions are grouped into three -sections:<literal>PHP_INI_SYSTEM</literal> allows a change only directly in -the <filename>php3.ini</filename> file; <literal>PHP_INI_USER</literal> allows -a change to be overridden by a user at runtime using additional -configuration files, such as <filename>.htaccess</filename>; and <literal>PHP_INI_ALL</literal> allows -changes to be made without restrictions. There's also a fourth level, -<literal>PHP_INI_PERDIR</literal>, for which we couldn't verify its behavior -yet.</para> -<para>The fourth parameter consists of a pointer to a change-notification -handler. Whenever one of these initialization entries is changed, this handler -is called. Such a handler can be declared using the -<literal>PHP_INI_MH</literal> macro: -<programlisting>PHP_INI_MH(OnChangeSecond); // handler for ini-entry "second_ini_entry" +  + <chapter id="zend.ini-file-support"> + <title>Initialization File Support</title> + <para> + PHP 4 features a redesigned initialization file support. It's now + possible to specify default initialization entries directly in your code, read + and change these values at runtime, and create message handlers for change + notifications. + </para> + <para> + To create an .ini section in your own module, use the + macros <literal>PHP_INI_BEGIN()</literal> to mark the beginning of such a + section and <literal>PHP_INI_END()</literal> to mark its end. In between you can + use <literal>PHP_INI_ENTRY()</literal> to create entries. +<programlisting> +PHP_INI_BEGIN() +PHP_INI_ENTRY("first_ini_entry", "has_string_value", PHP_INI_ALL, NULL) +PHP_INI_ENTRY("second_ini_entry", "2", PHP_INI_SYSTEM, OnChangeSecond) +PHP_INI_ENTRY("third_ini_entry", "xyz", PHP_INI_USER, NULL) +PHP_INI_END() +</programlisting> + The <literal>PHP_INI_ENTRY()</literal> macro accepts four + parameters: the entry name, the entry value, its change permissions, and a + pointer to a change-notification handler. Both entry name and value must be + specified as strings, regardless of whether they really are strings or + integers. + </para> + <para> + The permissions are grouped into three + sections:<literal>PHP_INI_SYSTEM</literal> allows a change only directly in + the <filename>php3.ini</filename> file; <literal>PHP_INI_USER</literal> allows + a change to be overridden by a user at runtime using additional + configuration files, such as <filename>.htaccess</filename>; and <literal>PHP_INI_ALL</literal> allows + changes to be made without restrictions. There's also a fourth level, + <literal>PHP_INI_PERDIR</literal>, for which we couldn't verify its behavior + yet. + </para> + <para> + The fourth parameter consists of a pointer to a change-notification + handler. Whenever one of these initialization entries is changed, this handler + is called. Such a handler can be declared using the + <literal>PHP_INI_MH</literal> macro: + <programlisting> +PHP_INI_MH(OnChangeSecond); // handler for ini-entry "second_ini_entry" // specify ini-entries here @@ -41,90 +53,102 @@ return(SUCCESS); -}</programlisting>The new value is given to the change handler as string in -the variable <envar>new_value</envar>. When looking at the definition -of <literal>PHP_INI_MH</literal>, you actually have a few parameters to use: -<programlisting>#define PHP_INI_MH(name) int name(php_ini_entry *entry, char *new_value, +} + </programlisting> + The new value is given to the change handler as string in + the variable <envar>new_value</envar>. When looking at the definition + of <literal>PHP_INI_MH</literal>, you actually have a few parameters to use: + <programlisting> +#define PHP_INI_MH(name) int name(php_ini_entry *entry, char *new_value, uint new_value_length, void *mh_arg1, - void *mh_arg2, void *mh_arg3)</programlisting>All these definitions can be found -in <filename>php_ini.h</filename>. Your message handler will have access to a -structure that contains the full entry, the new value, its length, and three -optional arguments. These optional arguments can be specified with the additional -macros <literal>PHP_INI_ENTRY1</literal> (allowing one additional -argument), <literal>PHP_INI_ENTRY2</literal> (allowing two additional arguments), -and <literal>PHP_INI_ENTRY3</literal> (allowing three additional -arguments).</para> -<para>The change-notification handlers should be used to cache initialization -entries locally for faster access or to perform certain tasks that are -required if a value changes. For example, if a constant connection to a -certain host is required by a module and someone changes the hostname, -automatically terminate the old connection and attempt a new one.</para> -<para>Access to initialization entries -can also be handled with the macros shown in Table 9.17.</para> -<figure> -<title>Table 9.17. Macros to Access Initialization Entries in PHP</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.66*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>INI_INT(name)</literal></entry> -<entry colname="col2">Returns the current value of -entry <literal>name</literal> as integer (long).</entry> -</row> -<row> -<entry colname="col1"><literal>INI_FLT(name)</literal></entry> -<entry colname="col2">Returns the current value of -entry <literal>name</literal> as float (double).</entry> -</row> -<row> -<entry colname="col1"><literal>INI_STR(name)</literal></entry> -<entry colname="col2">Returns the current value of -entry <literal>name</literal> as string. <emphasis>Note:</emphasis> This string is not duplicated, but -instead points to internal data. Further access requires duplication to local -memory.</entry> -</row> -<row> -<entry colname="col1"><literal>INI_BOOL(name)</literal></entry> -<entry colname="col2">Returns the current value of -entry <literal>name</literal> as Boolean (defined as <envar>zend_bool</envar>, -which currently means <envar>unsigned char</envar>).</entry> -</row> -<row> -<entry colname="col1"><literal>INI_ORIG_INT(name)</literal></entry> -<entry colname="col2">Returns the original value of -entry <literal>name</literal> as integer (long).</entry> -</row> -<row> -<entry colname="col1"><literal>INI_ORIG_FLT(name)</literal></entry> -<entry colname="col2">Returns the original value of -entry <literal>name</literal> as float (double).</entry> -</row> -<row> -<entry colname="col1"><literal>INI_ORIG_STR(name)</literal></entry> -<entry colname="col2">Returns the original value of -entry <literal>name</literal> as string. Note: This string is not duplicated, but -instead points to internal data. Further access requires duplication to local -memory.</entry> -</row> -<row> -<entry colname="col1"><literal>INI_ORIG_BOOL(name)</literal></entry> -<entry colname="col2">Returns the original value of -entry <literal>name</literal> as Boolean (defined as <envar>zend_bool</envar>, which -currently means <envar>unsigned char</envar>).</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<para>Finally, you have to introduce your initialization entries to PHP. -This can be done in the module startup and shutdown functions, using the macros -<literal>REGISTER_INI_ENTRIES()</literal> and <literal>UNREGISTER_INI_ENTRIES()</literal>: - -<programlisting>ZEND_MINIT_FUNCTION(mymodule) + void *mh_arg2, void *mh_arg3) + </programlisting> + All these definitions can be found + in <filename>php_ini.h</filename>. Your message handler will have access to a + structure that contains the full entry, the new value, its length, and three + optional arguments. These optional arguments can be specified with the additional + macros <literal>PHP_INI_ENTRY1</literal> (allowing one additional + argument), <literal>PHP_INI_ENTRY2</literal> (allowing two additional arguments), + and <literal>PHP_INI_ENTRY3</literal> (allowing three additional + arguments). + </para> + <para> + The change-notification handlers should be used to cache initialization + entries locally for faster access or to perform certain tasks that are + required if a value changes. For example, if a constant connection to a + certain host is required by a module and someone changes the hostname, + automatically terminate the old connection and attempt a new one. + </para> + <para> + Access to initialization entries + can also be handled with the macros shown in Table 9.17.</para> + <figure> + <title>Table 9.17. Macros to Access Initialization Entries in PHP</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.66*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>INI_INT(name)</literal></entry> + <entry colname="col2">Returns the current value of + entry <literal>name</literal> as integer (long).</entry> + </row> + <row> + <entry colname="col1"><literal>INI_FLT(name)</literal></entry> + <entry colname="col2">Returns the current value of + entry <literal>name</literal> as float (double).</entry> + </row> + <row> + <entry colname="col1"><literal>INI_STR(name)</literal></entry> + <entry colname="col2">Returns the current value of + entry <literal>name</literal> as string. <emphasis>Note:</emphasis> This string is not duplicated, but + instead points to internal data. Further access requires duplication to local + memory.</entry> + </row> + <row> + <entry colname="col1"><literal>INI_BOOL(name)</literal></entry> + <entry colname="col2">Returns the current value of + entry <literal>name</literal> as Boolean (defined as <envar>zend_bool</envar>, + which currently means <envar>unsigned char</envar>).</entry> + </row> + <row> + <entry colname="col1"><literal>INI_ORIG_INT(name)</literal></entry> + <entry colname="col2">Returns the original value of + entry <literal>name</literal> as integer (long).</entry> + </row> + <row> + <entry colname="col1"><literal>INI_ORIG_FLT(name)</literal></entry> + <entry colname="col2">Returns the original value of + entry <literal>name</literal> as float (double).</entry> + </row> + <row> + <entry colname="col1"><literal>INI_ORIG_STR(name)</literal></entry> + <entry colname="col2">Returns the original value of + entry <literal>name</literal> as string. Note: This string is not duplicated, but + instead points to internal data. Further access requires duplication to local + memory.</entry> + </row> + <row> + <entry colname="col1"><literal>INI_ORIG_BOOL(name)</literal></entry> + <entry colname="col2">Returns the original value of + entry <literal>name</literal> as Boolean (defined as <envar>zend_bool</envar>, which + currently means <envar>unsigned char</envar>).</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <para> + Finally, you have to introduce your initialization entries to PHP. + This can be done in the module startup and shutdown functions, using the macros + <literal>REGISTER_INI_ENTRIES()</literal> and <literal>UNREGISTER_INI_ENTRIES()</literal>: + <programlisting> +ZEND_MINIT_FUNCTION(mymodule) { REGISTER_INI_ENTRIES(); @@ -136,10 +160,29 @@ UNREGISTER_INI_ENTRIES(); -}</programlisting></para> -</chapter> +} + </programlisting> + </para> + </chapter>  + Index: ZendAPI/Extending_Zend_Introduction.xml diff -u ZendAPI/Extending_Zend_Introduction.xml:1.4 ZendAPI/Extending_Zend_Introduction.xml:1.5 --- ZendAPI/Extending_Zend_Introduction.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Introduction.xml Mon Feb 11 05:10:33 2002 @@ -1,47 +1,44 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  - <partintro> - <abstract> - <para>Those who know don't talk.</para> - <para>Those who talk don't know.</para> - </abstract> - - <para> - Sometimes, PHP "as is" simply isn't enough. Although these cases are rare - for the average user, professional applications will soon lead PHP to the edge - of its capabilities, in terms of either speed or functionality. New - functionality cannot always be implemented natively due to language - restrictions and inconveniences that arise when having to carry around a huge - library of default code appended to every single script, so another method - needs to be found for overcoming these eventual lacks in PHP. - </para> - <para> - As soon as this point is reached, it's time to touch the heart of PHP - and take a look at its core, the C code that makes PHP go. - </para> - <para> - <emphasis>Note:</emphasis> This chapter only deals with the - extension of PHP 4.0. Although a lot of the information is - relevant to PHP 3.0, none of the examples are designed to be - compatible with PHP 3.0. We believe that, if someone makes the - effort to extend PHP, PHP 4.0 will be installed anyway. - (Recompiling old PHP 3.0 servers doesn't make sense, considering - the benefits of the new PHP version). - </para> - <para> - Also, at the time of this writing, quite a few things in PHP 4.0 - were not completely finished and working yet (one of the major - things is the thread-safe version of Zend). - </para> - <note> - <para> - Updates of this chapter can be found at <ulink - url="http://www.zend.com">http://www.zend.com</ulink>. - </para> - </note> - </partintro> +  +<partintro> + <abstract> + <para>Those who know don't talk.</para> + <para>Those who talk don't know.</para> + </abstract> + + <para> + Sometimes, PHP "as is" simply isn't enough. Although these cases are rare + for the average user, professional applications will soon lead PHP to the edge + of its capabilities, in terms of either speed or functionality. New + functionality cannot always be implemented natively due to language + restrictions and inconveniences that arise when having to carry around a huge + library of default code appended to every single script, so another method + needs to be found for overcoming these eventual lacks in PHP. + </para> + <para> + As soon as this point is reached, it's time to touch the heart of PHP + and take a look at its core, the C code that makes PHP go. + </para> +</partintro>  + Index: ZendAPI/Extending_Zend_Layout.xml diff -u ZendAPI/Extending_Zend_Layout.xml:1.5 ZendAPI/Extending_Zend_Layout.xml:1.6 --- ZendAPI/Extending_Zend_Layout.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Layout.xml Mon Feb 11 05:10:33 2002 @@ -1,262 +1,337 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  +  - <chapter id="zend.layout"> - <title>Source Layout</title> - <sidebar> - <formalpara> - <title>Prerequisites</title> - <para>Prior to working through the rest of this chapter, you should retrieve - clean, unmodified source trees of your favorite Web server. We're working with - Apache (available at - <ulink url="http://www.apache.org">http://www.apache.org</ulink>) - and, of course, with PHP (available at - <ulink url="http://www.php.net">http://www.php.net</ulink> - does - it need to be said?).</para> - </formalpara> - <para>Alternatively, you can use the provided source archives on the - CD-ROM accompanying this book. All the examples in this book work with the source - archives on the CD-ROM; we can't guarantee this for every version retrieved - from the Net. However, as Open Source software develops extremely rapidly, - chances are that the versions on the CD-ROM are already outdated and don't have - all the functionality you need. If you can't get the official archives - from the corresponding Web sites to work, experiment with the CD-ROM archives and - then try to go on from there.</para> - <para>Make sure that you can compile a working PHP environment by - yourself! We won't go into this issue here, however, as you should already have this most basic ability when studying this chapter.</para> - </sidebar> - <para>Before we start discussing code issues, you should familiarize yourself with the source tree to be able to quickly navigate - through PHP's files. This is a must-have ability to implement and debug - extensions.</para> - <para>After extracting the PHP archive, you'll see a directory layout similar to that in Figure 9.2.</para> - <figure> - <title>Figure 9.2. Main directory layout of the PHP source tree.</title><graphic fileref="figures/Extending_Zend_1a_Directory_Layout.png"/> - </figure> - <para>The following table describes the contents of the major directories.</para> - <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="3.74*"/> - <tbody> - <row> - <entry colname="col1">Directory</entry> - <entry colname="col2">Contents</entry> - </row> - <row> - <entry colname="col1"><filename>php-4</filename></entry> - <entry colname="col2">Main PHP source files and main header files; here you'll find all of PHP's API definitions, macros, etc. - (important).</entry> - </row> - <row> - <entry colname="col1"><filename>ext</filename></entry> - <entry colname="col2">Repository for dynamic and built-in - modules; by default, these are the "official" PHP modules that have been - integrated into the main source tree. In PHP 4.0, it's possible to compile these standard extensions as dynamic loadable modules (at least, - those that support it).</entry> - </row> - <row> - <entry colname="col1"><filename>pear</filename></entry> - <entry colname="col2">Directory for the PHP class repository. - At the time of this writing, this is still in the design phase, but it's being - tried to establish something similar to CPAN for Perl here.</entry> - </row> - <row> - <entry colname="col1"><filename>sapi</filename></entry> - <entry colname="col2">Contains the code for the different - server abstraction layers.</entry> - </row> - <row> - <entry colname="col1"><filename>TSRM</filename></entry> - <entry colname="col2">Location of the "Thread Safe - Resource Manager" (TSRM) for Zend and PHP.</entry> - </row> - <row> - <entry colname="col1"><filename>Zend</filename></entry> - <entry colname="col2">Location of Zend's file; here you'll - find all of Zend's API definitions, macros, etc. (important).</entry> - </row> - </tbody> - </tgroup> - </informaltable> - <para>Discussing all the files included in the PHP package is beyond the scope of this chapter. - However, you should take a close look at the following files:<itemizedlist> - <listitem> - <para><filename>php.h</filename>, located in the main PHP - directory. This file contains most of PHP's macro and API definitions.</para> - </listitem> - <listitem> - <para><filename>zend.h</filename>, located in the main Zend - directory. This file contains most of Zend's macros and definitions.</para> - </listitem> - <listitem> - <para><filename>zend_API.h</filename>, also located in the Zend - directory, which defines Zend's API.</para> - </listitem> - </itemizedlist>You should also follow some sub-inclusions from these - files; for example, the ones relating to the Zend executor, the PHP - initialization file support, and such. After reading these files, take - the time to navigate around the package a little to see the interdependencies - of all files and modules - how they relate to each other and especially how they - make use of each other. This also helps you to adapt to the coding style in which PHP is authored. To extend PHP, you should quickly adapt to this style.</para> - - <section id="zend.layout.conventions"> - <title>Extension Conventions</title> - <para>Zend is - built using certain conventions; to avoid breaking its standards, you should follow the rules described in the following sections.</para> - </section> - <section id="zend.layout.macros"> - <title>Macros</title> - <para>For almost every important task, Zend ships predefined macros - that are extremely handy. The tables and figures - in the following sections describe most of the basic - functions, structures, and macros. The macro definitions can be found mainly in - <filename>zend.h</filename> and <filename>zend_API.h</filename>. We suggest - that you take a close look at these files after having studied this chapter. - (Although you can go ahead and read them now, not everything will - make sense to you yet.)</para> - </section> - <section id="zend.layout.memory-management"> - <title>Memory Management</title> - <para>Resource management is a crucial issue, especially in server - software. One of the most valuable resources is memory, and memory management - should be handled with extreme care. Memory management has been partially - abstracted in Zend, and you should stick to this abstraction for obvious - reasons: Due to the abstraction, Zend gets full control over all memory - allocations. Zend is able to determine whether a block is in use, - automatically freeing unused blocks and blocks with lost references, and - thus prevent memory leaks. The functions to be used are described in the following table: - <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.62*"/> - <tbody> - <row> - <entry colname="col1">Function</entry> - <entry colname="col2">Description</entry> - </row> - <row> - <entry colname="col1"><function>emalloc</function></entry> - <entry colname="col2">Serves as replacement for - <function>malloc</function>.</entry> - </row> - <row> - <entry colname="col1"><function>efree</function></entry> - <entry colname="col2">Serves as replacement for - <function>free</function>.</entry> - </row> - <row> - <entry colname="col1"><function>estrdup</function></entry> - <entry colname="col2">Serves as replacement for - <function>strdup</function>.</entry> - </row> - <row> - <entry colname="col1"><function>estrndup</function></entry> - - <entry colname="col2">Serves as replacement for - <function>strndup</function>. Faster than - <function>estrdup</function> and binary-safe. This is the recommended - function to use if you know the string length prior to duplicating - it.</entry> - </row> - <row> - <entry colname="col1"><function>ecalloc</function></entry> - <entry colname="col2">Serves as replacement for - <function>calloc</function>.</entry> - </row> - <row> - <entry colname="col1"><function>erealloc</function></entry> - - <entry colname="col2">Serves as replacement for - <function>realloc</function>.</entry> - </row> - </tbody> - </tgroup> - </informaltable><function>emalloc</function>, <function>estrdup</function>, <function>estrndup</function>, - <function>ecalloc</function>, and <function>erealloc</function> allocate - internal memory; <function>efree</function> frees these previously allocated - blocks. Memory handled by the <function>e*</function> functions is considered local to the current process and is discarded as soon as the - script executed by this process is terminated. - <warning> - <para>To allocate resident memory that survives termination of the - current script, you can use <function>malloc</function> and - <function>free</function>. This should only be done with extreme care, however, and - only in conjunction with demands of the Zend API; otherwise, you risk - memory leaks.</para> - </warning>Zend also features a thread-safe resource manager to - provide better native support for multithreaded Web servers. This requires you - to allocate local structures for all of your global variables to allow - concurrent threads to be run. Because the thread-safe mode of Zend is not - finished yet, we could not include coverage in this book.</para> - </section> - <section id="zend.layout.dir-and-file"> - <title>Directory and File Functions</title> - <para>The following directory and file functions should be used in Zend - modules (they behave exactly like their C counterparts): - <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> - <tbody> - <row> - <entry colname="col1">Zend Function</entry> - <entry colname="col2">Regular C Function</entry> - </row> - <row> - <entry colname="col1"><function>V_GETCWD</function></entry> - - <entry colname="col2"><function>getcwd</function></entry> - </row> - <row> - <entry colname="col1"><function>V_FOPEN</function></entry> - <entry colname="col2"><function>fopen</function></entry> - </row> - <row> - <entry colname="col1"><function>V_OPEN</function></entry> - <entry colname="col2"><function>open</function></entry> - </row> - <row> - <entry colname="col1"><function>V_CHDIR</function></entry> - <entry colname="col2"><function>chdir</function></entry> - </row> - <row> - <entry colname="col1"><function>V_GETWD</function></entry> - <entry colname="col2"><function>getwd</function></entry> - </row> - <row> - <entry colname="col1"><function>V_CHDIR_FILE</function></entry> - <entry colname="col2">Takes a file path as an argument and - changes the current working directory to that file's directory.</entry> - </row> - <row> - <entry colname="col1"><function>V_STAT</function></entry> - <entry colname="col2"><function>stat</function></entry> - </row> - <row> - <entry colname="col1"><function>V_LSTAT</function></entry> - <entry colname="col2"><function>lstat</function></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - </section> - <section id="zend.layout.string-handling"> - <title>String Handling</title> - <para>Strings are handled a bit differently by the Zend engine - than other values such as integers, Booleans, etc., which don't require - additional memory allocation for storing their values. If you want to - return a string from a function, introduce a new string variable to the symbol - table, or do something similar, you have to make sure that the memory the - string will be occupying has previously been allocated, using the - aforementioned <function>e*</function> functions for allocation. (This might - not make much sense to you yet; just keep it somewhere in your head for now - we'll get - back to it shortly.)</para> - </section> - <section id="zend.layout.complex-types"> - <title>Complex Types</title> - <para>Complex types such as arrays and objects require - different treatment. Zend features a single API for these types - they're - stored using hash tables.</para> - <para><emphasis>Note:</emphasis> To reduce complexity in the following source examples, we're only - working with simple types such as integers at first. A discussion about - creating more advanced types follows later in this chapter.</para> - </section> - </chapter> + <chapter id="zend.layout"> + <title>Source Layout</title> + <note> + <para> + Prior to working through the rest of this chapter, you should retrieve + clean, unmodified source trees of your favorite Web server. We're working with + Apache (available at + <ulink url="http://www.apache.org/">http://www.apache.org/</ulink>) + and, of course, with PHP (available at + <ulink url="http://www.php.net/">http://www.php.net/</ulink> - does + it need to be said?). + </para> + <para> + Make sure that you can compile a working PHP environment by + yourself! We won't go into this issue here, however, as you should + already have this most basic ability when studying this chapter. + </para> + </note> + <para> + Before we start discussing code issues, you should familiarize + yourself with the source tree to be able to quickly navigate + through PHP's files. This is a must-have ability to implement and + debug extensions. + </para> + <para> + After extracting the PHP archive, you'll see a directory layout similar to that in Figure 9.2. + </para> + <figure> + <title>Figure 9.2. Main directory layout of the PHP source tree.</title> + <graphic fileref="figures/Extending_Zend_1a_Directory_Layout.png"/> + </figure> + <para> + The following table describes the contents of the major directories. + </para> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="3.74*"/> + <tbody> + <row> + <entry colname="col1">Directory</entry> + <entry colname="col2">Contents</entry> + </row> + <row> + <entry colname="col1"><filename>php-4</filename></entry> + <entry colname="col2"> + Main PHP source files and main header files; here you'll find + all of PHP's API definitions, macros, etc. (important). + </entry> + </row> + <row> + <entry colname="col1"><filename>ext</filename></entry> + <entry colname="col2"> + Repository for dynamic and built-in modules; by default, these + are the "official" PHP modules that have been integrated into + the main source tree. In PHP 4.0, it's possible to compile + these standard extensions as dynamic loadable modules (at + least, those that support it). + </entry> + </row> + <row> + <entry colname="col1"><filename>pear</filename></entry> + <entry colname="col2"> + Directory for the PHP class repository. + At the time of this writing, this is still in the design phase, but it's being + tried to establish something similar to CPAN for Perl here. + </entry> + </row> + <row> + <entry colname="col1"><filename>sapi</filename></entry> + <entry colname="col2"> + Contains the code for the different server abstraction layers. + </entry> + </row> + <row> + <entry colname="col1"><filename>TSRM</filename></entry> + <entry colname="col2"> + Location of the "Thread Safe Resource Manager" (TSRM) for Zend + and PHP. + </entry> + </row> + <row> + <entry colname="col1"><filename>Zend</filename></entry> + <entry colname="col2"> + Location of Zend's file; here you'll + find all of Zend's API definitions, macros, etc. (important). + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + Discussing all the files included in the PHP package is beyond the + scope of this chapter. However, you should take a close look at the + following files:<itemizedlist> + <listitem> + <para> + <filename>php.h</filename>, located in the main PHP directory. + This file contains most of PHP's macro and API definitions. + </para> + </listitem> + <listitem> + <para> + <filename>zend.h</filename>, located in the main Zend directory. + This file contains most of Zend's macros and definitions. + </para> + </listitem> + <listitem> + <para> + <filename>zend_API.h</filename>, also located in the Zend + directory, which defines Zend's API. + </para> + </listitem> + </itemizedlist> You should also follow some sub-inclusions from + these files; for example, the ones relating to the Zend executor, + the PHP initialization file support, and such. After reading these + files, take the time to navigate around the package a little to see + the interdependencies of all files and modules - how they relate to + each other and especially how they make use of each other. This + also helps you to adapt to the coding style in which PHP is + authored. To extend PHP, you should quickly adapt to this style. + </para> + + <section id="zend.layout.conventions"> + <title>Extension Conventions</title> + <para> + Zend is built using certain conventions; to avoid breaking its + standards, you should follow the rules described in the following + sections. + </para> + </section> + <section id="zend.layout.macros"> + <title>Macros</title> + <para> + For almost every important task, Zend ships predefined macros that + are extremely handy. The tables and figures in the following + sections describe most of the basic functions, structures, and + macros. The macro definitions can be found mainly in + <filename>zend.h</filename> and <filename>zend_API.h</filename>. + We suggest that you take a close look at these files after having + studied this chapter. (Although you can go ahead and read them + now, not everything will make sense to you yet.) + </para> + </section> + + <section id="zend.layout.memory-management"> + <title>Memory Management</title> + <para> + Resource management is a crucial issue, especially in server + software. One of the most valuable resources is memory, and memory + management should be handled with extreme care. Memory management + has been partially abstracted in Zend, and you should stick to + this abstraction for obvious reasons: Due to the abstraction, Zend + gets full control over all memory allocations. Zend is able to + determine whether a block is in use, automatically freeing unused + blocks and blocks with lost references, and thus prevent memory + leaks. The functions to be used are described in the following + table: + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.62*"/> + <tbody> + <row> + <entry colname="col1">Function</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><function>emalloc</function></entry> + <entry colname="col2">Serves as replacement for + <function>malloc</function>.</entry> + </row> + <row> + <entry colname="col1"><function>efree</function></entry> + <entry colname="col2">Serves as replacement for + <function>free</function>.</entry> + </row> + <row> + <entry colname="col1"><function>estrdup</function></entry> + <entry colname="col2">Serves as replacement for + <function>strdup</function>.</entry> + </row> + <row> + <entry colname="col1"><function>estrndup</function></entry> + <entry colname="col2">Serves as replacement for + <function>strndup</function>. Faster than + <function>estrdup</function> and binary-safe. This is the + recommended function to use if you know the string length + prior to duplicating it.</entry> + </row> + <row> + <entry colname="col1"><function>ecalloc</function></entry> + <entry colname="col2">Serves as replacement for + <function>calloc</function>.</entry> + </row> + <row> + <entry colname="col1"><function>erealloc</function></entry> + <entry colname="col2">Serves as replacement for + <function>realloc</function>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> <function>emalloc</function>, + <function>estrdup</function>, <function>estrndup</function>, + <function>ecalloc</function>, and <function>erealloc</function> + allocate internal memory; <function>efree</function> frees these + previously allocated blocks. Memory handled by the + <function>e*</function> functions is considered local to the + current process and is discarded as soon as the script executed by + this process is terminated. + <warning> + <para> + To allocate resident memory that survives termination of + the current script, you can use <function>malloc</function> and + <function>free</function>. This should only be done with extreme + care, however, and only in conjunction with demands of the Zend + API; otherwise, you risk memory leaks. + </para> + </warning> + Zend also features a thread-safe resource manager to + provide better native support for multithreaded Web servers. This + requires you to allocate local structures for all of your global + variables to allow concurrent threads to be run. Because the + thread-safe mode of Zend was not finished back when this was written, + it is not yet extensively covered here. + </para> + </section> + <section id="zend.layout.dir-and-file"> + <title>Directory and File Functions</title> + <para> + The following directory and file functions should be used in Zend + modules. They behave exactly like their C counterparts, but + provide virtual working directory support on the thread level. + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Zend Function</entry> + <entry colname="col2">Regular C Function</entry> + </row> + <row> + <entry colname="col1"><function>V_GETCWD</function></entry> + <entry colname="col2"><function>getcwd</function></entry> + </row> + <row> + <entry colname="col1"><function>V_FOPEN</function></entry> + <entry colname="col2"><function>fopen</function></entry> + </row> + <row> + <entry colname="col1"><function>V_OPEN</function></entry> + <entry colname="col2"><function>open</function></entry> + </row> + <row> + <entry colname="col1"><function>V_CHDIR</function></entry> + <entry colname="col2"><function>chdir</function></entry> + </row> + <row> + <entry colname="col1"><function>V_GETWD</function></entry> + <entry colname="col2"><function>getwd</function></entry> + </row> + <row> + <entry + colname="col1"><function>V_CHDIR_FILE</function></entry> + <entry colname="col2"> + Takes a file path as an argument and changes the current + working directory to that file's directory. + </entry> + </row> + <row> + <entry colname="col1"><function>V_STAT</function></entry> + <entry colname="col2"><function>stat</function></entry> + </row> + <row> + <entry colname="col1"><function>V_LSTAT</function></entry> + <entry colname="col2"><function>lstat</function></entry> + </row> + </tbody> + </tgroup> + </informaltable></para> + </section> + <section id="zend.layout.string-handling"> + <title>String Handling</title> + <para> + Strings are handled a bit differently by the Zend engine + than other values such as integers, Booleans, etc., which don't require + additional memory allocation for storing their values. If you want to + return a string from a function, introduce a new string variable to the symbol + table, or do something similar, you have to make sure that the memory the + string will be occupying has previously been allocated, using the + aforementioned <function>e*</function> functions for allocation. (This might + not make much sense to you yet; just keep it somewhere in your head for now - we'll get + back to it shortly.) + </para> + </section> + <section id="zend.layout.complex-types"> + <title>Complex Types</title> + <para> + Complex types such as arrays and objects require + different treatment. Zend features a single API for these types - they're + stored using hash tables. + </para> + <note> + <para> + To reduce complexity in the following source examples, we're only + working with simple types such as integers at first. A discussion about + creating more advanced types follows later in this chapter. + </para> + </note> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_Overview.xml diff -u ZendAPI/Extending_Zend_Overview.xml:1.4 ZendAPI/Extending_Zend_Overview.xml:1.5 --- ZendAPI/Extending_Zend_Overview.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Overview.xml Mon Feb 11 05:10:33 2002 @@ -1,84 +1,101 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  +  - <chapter id="zend.overview"> - <title>Overview</title> + <chapter id="zend.overview"> + <title>Overview</title> + <para> + "Extending PHP" is easier said than done. PHP has evolved to a + full-fledged tool consisting of a few megabytes of source code, + and to hack a system like this quite a few things have to be + learned and considered. When structuring this chapter, we finally + decided on the "learn by doing" approach. This is not the most + scientific and professional approach, but the method that's the + most fun and gives the best end results. In the following + sections, you'll learn quickly how to get the most basic + extensions to work almost instantly. After that, you'll learn + about Zend's advanced API functionality. The alternative would + have been to try to impart the functionality, design, tips, + tricks, etc. as a whole, all at once, thus giving a complete look + at the big picture before doing anything practical. Although this + is the "better" method, as no dirty hacks have to be made, it can + be very frustrating as well as energy- and time-consuming, which + is why we've decided on the direct approach. + </para> + <para> + Note that even though this chapter tries to impart as much + knowledge as possible about the inner workings of PHP, it's + impossible to really give a complete guide to extending PHP that + works 100% of the time in all cases. PHP is such a huge and + complex package that its inner workings can only be understood if + you make yourself familiar with it by practicing, so we encourage + you to work with the source. + </para> + + <section id="zend.overview.whatisit"> + <title>What Is Zend? and What Is PHP?</title> <para> - "Extending PHP" is easier said than done. PHP has evolved to a - full-fledged tool consisting of a few megabytes of source code, - and to hack a system like this quite a few things have to be - learned and considered. When structuring this chapter, we finally - decided on the "learn by doing" approach. This is not the most - scientific and professional approach, but the method that's the - most fun and gives the best end results. In the following - sections, you'll learn quickly how to get the most basic - extensions to work almost instantly. After that, you'll learn - about Zend's advanced API functionality. The alternative would - have been to try to impart the functionality, design, tips, - tricks, etc. as a whole, all at once, thus giving a complete look - at the big picture before doing anything practical. Although this - is the "better" method, as no dirty hacks have to be made, it can - be very frustrating as well as energy- and time-consuming, which - is why we've decided on the direct approach. + The name <emphasis>Zend</emphasis> refers to the language engine, + PHP's core. The term <emphasis>PHP</emphasis> refers to the + complete system as it appears from the outside. This might sound + a bit confusing at first, but it's not that complicated (see + Figure 9.1). To implement a Web script interpreter, you need + three parts: + <orderedlist> + <listitem> + <para> + The <emphasis>interpreter</emphasis> part analyzes the input + code, translates it, and executes it. + </para> + </listitem> + <listitem> + <para> + The <emphasis>functionality</emphasis> part implements the + functionality of the language (its functions, etc.). + </para> + </listitem> + <listitem> + <para> + The <emphasis>interface</emphasis> part talks to the Web + server, etc. + </para> + </listitem> + </orderedlist> + Zend takes part 1 completely and a bit of part 2; PHP takes parts + 2 and 3. Together they form the complete PHP package. Zend itself + really forms only the language core, implementing PHP at its very + basics with some predefined functions. PHP contains all the + modules that actually create the language's outstanding + capabilities. + <figure> + <title>Figure 9.1. The internal structure of PHP.</title> + <graphic fileref="figures/Extending_Zend_1_PHPs_internal_structure.png"/> + </figure> </para> <para> - Note that even though this chapter tries to impart as much - knowledge as possible about the inner workings of PHP, it's - impossible to really give a complete guide to extending PHP that - works 100% of the time in all cases. PHP is such a huge and - complex package that its inner workings can only be understood if - you make yourself familiar with it by practicing, so we encourage - you to work with the source. + The following sections discuss where PHP can be extended and how + it's done. </para> - - <section id="zend.overview.whatisit"> - <title>What Is Zend? and What Is PHP?</title> - <para> - The name <emphasis>Zend</emphasis> refers to the language engine, - PHP's core. The term <emphasis>PHP</emphasis> refers to the - complete system as it appears from the outside. This might sound - a bit confusing at first, but it's not that complicated (see - Figure 9.1). To implement a Web script interpreter, you need - three parts: - <orderedlist> - <listitem> - <para> - The <emphasis>interpreter</emphasis> part analyzes the input - code, translates it, and executes it. - </para> - </listitem> - <listitem> - <para> - The <emphasis>functionality</emphasis> part implements the - functionality of the language (its functions, etc.). - </para> - </listitem> - <listitem> - <para> - The <emphasis>interface</emphasis> part talks to the Web - server, etc. - </para> - </listitem> - </orderedlist> - Zend takes part 1 completely and a bit of part 2; PHP takes parts - 2 and 3. Together they form the complete PHP package. Zend itself - really forms only the language core, implementing PHP at its very - basics with some predefined functions. PHP contains all the - modules that actually create the language's outstanding - capabilities. - <figure> - <title>Figure 9.1. The internal structure of PHP.</title> - <graphic fileref="figures/Extending_Zend_1_PHPs_internal_structure.png"/> - </figure> - </para> - <para> - The following sections discuss where PHP can be extended and how - it's done. - </para> - </section> - </chapter> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_Possibilities.xml diff -u ZendAPI/Extending_Zend_Possibilities.xml:1.5 ZendAPI/Extending_Zend_Possibilities.xml:1.6 --- ZendAPI/Extending_Zend_Possibilities.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Possibilities.xml Mon Feb 11 05:10:33 2002 @@ -1,105 +1,163 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  +  - <chapter id="zend.possibilities"> - <title>Extension Possibilities</title> - <para>As shown in Figure 9.1 above, PHP can be - extended primarily at three points: external modules, built-in modules, and the Zend engine. The following sections discuss these options.</para> - <section id="zend.possibilities.external"> - <title>External Modules</title> - <para>External modules can be loaded at script runtime using the - function <function>dl</function>. This function loads a shared object from - disk and makes its functionality available to the script to which it's being bound. - After the script is terminated, the external module is discarded from memory. - This method has both advantages and disadvantages, as described in the following table: - <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> - <tbody> - <row> - <entry colname="col1">Advantages</entry> - <entry colname="col2">Disadvantages</entry> - </row> - <row> - <entry colname="col1">External modules don't require - recompiling of PHP.</entry> - <entry colname="col2">The shared objects need to be loaded - every time a script is being executed (every hit), which is very - slow.</entry> - </row> - <row> - <entry colname="col1">The size of PHP remains small by - "outsourcing" certain functionality.</entry> - <entry colname="col2">External additional files clutter up - the disk.</entry> - </row> - <row> - <entry colname="col1"></entry> - <entry colname="col2">Every script that wants to use an - external module's functionality has to specifically include a call to - <function>dl</function>, or the <literal>extension</literal> tag in - <filename>php.ini</filename> needs to be modified (which is not always a - suitable solution).</entry> - </row> - </tbody> - </tgroup> - </informaltable>To sum up, external modules are great for third-party products, small additions to PHP that are rarely used, or just - for testing purposes. To develop additional functionality quickly, external - modules provide the best results. For frequent usage, larger implementations, and - complex code, the disadvantages outweigh the advantages.</para> - <para>Third parties might consider using the <literal>extension</literal> tag in - <filename>php.ini</filename> to create additional external modules to PHP. These external modules are completely detached from the main package, which is a very handy feature in commercial environments. Commercial - distributors can simply ship disks or archives containing only their additional modules, - without the need to create fixed and solid PHP binaries that don't allow other - modules to be bound to them.</para> - </section> - <section id="zend.possibilities.builtin"> - <title>Built-in Modules</title> - <para>Built-in modules are compiled directly into - PHP and carried around with every PHP process; their functionality is - instantly available to every script that's being run. Like external - modules, built-in modules have advantages and disadvantages, as described in the following table: - <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> - <tbody> - <row> - <entry colname="col1">Advantages</entry> - <entry colname="col2">Disadvantages</entry> - </row> - <row> - <entry colname="col1">No need to load the module - specifically; the functionality is instantly available.</entry> - <entry colname="col2">Changes to built-in modules require - recompiling of PHP.</entry> - </row> - <row> - <entry colname="col1">No external files clutter up the - disk; everything resides in the PHP binary.</entry> - <entry colname="col2">The PHP binary grows and consumes more - memory.</entry> - </row> - </tbody> - </tgroup> - </informaltable>Built-in modules are best when you have a solid - library of functions that remains relatively unchanged, requires better than - poor-to-average performance, or is used frequently by many scripts on your site. The need to recompile PHP is quickly compensated by the - benefit in speed and ease of use. However, built-in modules are not ideal when - rapid development of small additions is required.</para> - </section> - <section id="zend.possibilities.engine"> - <title>The Zend Engine</title> - <para>Of course, extensions can also be implemented directly in the Zend - engine. This strategy is good if you need a change in the language behavior or require - special functions to be built directly into the language core. In general, however, modifications to the - Zend engine should be avoided. Changes here result in - incompatibilities with the rest of the world, and hardly anyone will ever adapt - to specially patched Zend engines. Modifications can't be detached from the - main PHP sources and are overridden with the next update using the - "official" source repositories. Therefore, this method is generally considered bad practice and, due - to its rarity, is not covered in this book.</para> - </section> - </chapter> - + Index: ZendAPI/Extending_Zend_Printing.xml diff -u ZendAPI/Extending_Zend_Printing.xml:1.5 ZendAPI/Extending_Zend_Printing.xml:1.6 --- ZendAPI/Extending_Zend_Printing.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Printing.xml Mon Feb 11 05:10:33 2002 @@ -1,131 +1,195 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.printing"> -<title>Printing Information</title> -<para>Often it's necessary to print messages to the output stream from your -module, just as <function>print</function> would be used within a script. -PHP offers functions for most generic tasks, such as printing warning messages, -generating output for <function>phpinfo</function>, and so on. The following sections provide more details. Examples of these functions can be found on the CD-ROM.</para> -<section id="zend.printing.zend-printf"> -<title><function>zend_printf</function></title> -<para><function>zend_printf</function> works like the -standard <function>printf</function>, except that it prints to Zend's -output stream.</para> -</section> -<section id="zend.printing.zend-error"> -<title><function>zend_error</function></title> -<para><function>zend_error</function> can be used to generate error messages. -This function accepts two arguments; the first is the error type (see -<filename>zend_errors.h</filename>), and the second is the error message. -<programlisting>zend_error(E_WARNING, "This function has been called with empty arguments");</programlisting>Table 9.16 shows a list of possible values (see Figure 9.8). These -values are also referred to in <filename>php.ini</filename>. Depending on -which error type you choose, your messages will be logged. -<figure> -<title>Table 9.16. Zend's Predefined Error Messages.</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.36*"/> -<tbody> -<row> -<entry colname="col1">Error</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>E_ERROR</literal></entry> -<entry colname="col2">Signals an error and terminates execution of the script -immediately.</entry> -</row> -<row> -<entry colname="col1"><literal>E_WARNING</literal></entry> -<entry colname="col2">Signals a generic warning. Execution continues.</entry> -</row> -<row> -<entry colname="col1"><literal>E_PARSE</literal></entry> -<entry colname="col2">Signals a parser error. Execution continues.</entry> -</row> -<row> -<entry colname="col1"><literal>E_NOTICE</literal></entry> -<entry colname="col2">Signals a notice. Execution continues. Note that by -default the display of this type of error messages is turned off in -<filename>php.ini</filename>.</entry> -</row> -<row> -<entry colname="col1"><literal>E_CORE_ERROR</literal></entry> -<entry colname="col2">Internal error by the core; shouldn't be used by -user-written modules.</entry> -</row> -<row> -<entry colname="col1"><literal>E_COMPILE_ERROR</literal></entry> -<entry colname="col2">Internal error by the compiler; shouldn't be used by -user-written modules.</entry> -</row> -<row> -<entry colname="col1"><literal>E_COMPILE_WARNING</literal></entry> -<entry colname="col2">Internal warning by the compiler; shouldn't be used by -user-written modules.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<figure> -<title>Figure 9.8. Display of warning messages in the browser.</title><graphic fileref="figures/Extending_Zend_7_warning_messages.png"/> -</figure></para> -</section> -<section id="zend.printing.phpinfo"> -<title>Including Output in <function>phpinfo</function></title> -<para>After creating a real module, you'll want to show information -about the module in <function>phpinfo</function> (in addition to the -module name, which appears in the module list by default). PHP allows -you to create your own section in the <function>phpinfo</function> output with the <literal>ZEND_MINFO()</literal> function. This function -should be placed in the module descriptor block (discussed earlier) and is -always called whenever a script calls <function>phpinfo</function>.</para> -<para>PHP automatically prints a section -in <function>phpinfo</function> for you if you specify the <literal>ZEND_MINFO</literal> -function, including the module name in the heading. Everything else must be -formatted and printed by you.</para> -<para>Typically, you can print an HTML table header -using <function>php_info_print_table_start</function> and then use the standard -functions <function>php_info_print_table_header</function> -and <function>php_info_print_table_row</function>. As arguments, both take the number of -columns (as integers) and the column contents (as strings). Listing 9.14 shows a source example; Figure 9.9 shows the output. To print the table footer, use <function>php_info_print_table_end</function>.</para> -<figure> -<title>Listing 9.14. Source code and screenshot for output -in <function>phpinfo</function>.</title> -<programlisting>php_info_print_table_start(); +  + <chapter id="zend.printing"> + <title>Printing Information</title> + <para> + Often it's necessary to print messages to the output stream from + your module, just as <function>print</function> would be used + within a script. PHP offers functions for most generic tasks, such + as printing warning messages, generating output for + <function>phpinfo</function>, and so on. The following sections + provide more details. Examples of these functions can be found on + the CD-ROM. + </para> + <section id="zend.printing.zend-printf"> + <title><function>zend_printf</function></title> + <para> + <function>zend_printf</function> works like the + standard <function>printf</function>, except that it prints to Zend's + output stream. + </para> + </section> + <section id="zend.printing.zend-error"> + <title><function>zend_error</function></title> + <para> + <function>zend_error</function> can be used to generate error messages. + This function accepts two arguments; the first is the error type (see + <filename>zend_errors.h</filename>), and the second is the error message. + <programlisting>zend_error(E_WARNING, "This function has been called with empty arguments");</programlisting>Table 9.16 shows a list of possible values (see Figure 9.8). These + values are also referred to in <filename>php.ini</filename>. Depending on + which error type you choose, your messages will be logged. + <figure> + <title>Table 9.16. Zend's Predefined Error Messages.</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.36*"/> + <tbody> + <row> + <entry colname="col1">Error</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>E_ERROR</literal></entry> + <entry colname="col2"> + Signals an error and terminates execution of the script + immediately + .</entry> + </row> + <row> + <entry colname="col1"><literal>E_WARNING</literal></entry> + <entry colname="col2"> + Signals a generic warning. Execution continues. + </entry> + </row> + <row> + <entry colname="col1"><literal>E_PARSE</literal></entry> + <entry colname="col2"> + Signals a parser error. Execution continues. + </entry> + </row> + <row> + <entry colname="col1"><literal>E_NOTICE</literal></entry> + <entry colname="col2"> + Signals a notice. Execution continues. Note that by + default the display of this type of error messages is turned off in + <filename>php.ini</filename>. + </entry> + </row> + <row> + <entry colname="col1"><literal>E_CORE_ERROR</literal></entry> + <entry colname="col2"> + Internal error by the core; shouldn't be used by + user-written modules. + </entry> + </row> + <row> + <entry colname="col1"><literal>E_COMPILE_ERROR</literal></entry> + <entry colname="col2"> + Internal error by the compiler; shouldn't be used by + user-written modules. + </entry> + </row> + <row> + <entry colname="col1"><literal>E_COMPILE_WARNING</literal></entry> + <entry colname="col2"> + Internal warning by the compiler; shouldn't be used by + user-written modules. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <figure> + <title>Figure 9.8. Display of warning messages in the browser.</title> + <graphic fileref="figures/Extending_Zend_7_warning_messages.png"/> + </figure></para> + </section> + <section id="zend.printing.phpinfo"> + <title>Including Output in <function>phpinfo</function></title> + <para> + After creating a real module, you'll want to show information + about the module in <function>phpinfo</function> (in addition to the + module name, which appears in the module list by default). PHP allows + you to create your own section in the <function>phpinfo</function> output with the <literal>ZEND_MINFO()</literal> function. This function + should be placed in the module descriptor block (discussed earlier) and is + always called whenever a script calls <function>phpinfo</function>. + </para> + <para> + PHP automatically prints a section + in <function>phpinfo</function> for you if you specify the <literal>ZEND_MINFO</literal> + function, including the module name in the heading. Everything else must be + formatted and printed by you. + </para> + <para> + Typically, you can print an HTML table header + using <function>php_info_print_table_start</function> and then use the standard + functions <function>php_info_print_table_header</function> + and <function>php_info_print_table_row</function>. As arguments, both take the number of + columns (as integers) and the column contents (as strings). Listing 9.14 shows a source example; Figure 9.9 shows the output. To print the table footer, use <function>php_info_print_table_end</function>. + </para> + <figure> + <title> + Listing 9.14. Source code and screenshot for output in <function>phpinfo</function>. + </title> + <programlisting> +php_info_print_table_start(); php_info_print_table_header(2, "First column", "Second column"); php_info_print_table_row(2, "Entry in first row", "Another entry"); php_info_print_table_row(2, "Just to fill", "another row here"); -php_info_print_table_end();</programlisting><graphic fileref="figures/Extending_Zend_8_phpinfo_output.png"/> -</figure> -</section> -<section id="zend.printing.execution"> -<title>Execution Information</title> -<para>You can also print execution information, such as -the current file being executed. The name of the function currently being executed can be retrieved using -the function <function>get_active_function_name</function>. This function -returns a pointer to the function name and doesn't accept any arguments. To retrieve the name of the file currently being executed, use <function>zend_get_executed_filename</function>. This function -accesses the executor globals, which are passed to it using the -<literal>ELS_C</literal> macro. The executor globals are automatically -available to every function that's called directly by Zend (they're part of -the <literal>INTERNAL_FUNCTION_PARAMETERS</literal> described earlier in this -chapter). If you want to access the executor globals in another function -that doesn't have them available automatically, call the macro -<literal>ELS_FETCH()</literal> once in that function; this will introduce them -to your local scope.</para> -<para>Finally, the line number currently being executed can be -retrieved using the function <function>zend_get_executed_lineno</function>. -This function also requires the executor globals as arguments. For examples of these functions, see Listing 9.15 and Figure 9.10. Of -course, all the examples are also available on the CD-ROM.</para> -<figure> -<title>Listing 9.15. Printing execution information.</title> -<programlisting>zend_printf("The name of the current function is %s<br>", get_active_function_name()); +php_info_print_table_end(); + </programlisting> + <graphic fileref="figures/Extending_Zend_8_phpinfo_output.png"/> + </figure> + </section> + <section id="zend.printing.execution"> + <title>Execution Information</title> + <para> + You can also print execution information, such as the current file + being executed. The name of the function currently being executed + can be retrieved using the function + <function>get_active_function_name</function>. This function + returns a pointer to the function name and doesn't accept any + arguments. To retrieve the name of the file currently being + executed, use <function>zend_get_executed_filename</function>. + This function accesses the executor globals, which are passed to + it using the <literal>ELS_C</literal> macro. The executor globals + are automatically available to every function that's called + directly by Zend (they're part of the + <literal>INTERNAL_FUNCTION_PARAMETERS</literal> described earlier + in this chapter). If you want to access the executor globals in + another function that doesn't have them available automatically, + call the macro <literal>ELS_FETCH()</literal> once in that + function; this will introduce them to your local scope. + </para> + <para> + Finally, the line number currently being executed can be retrieved + using the function <function>zend_get_executed_lineno</function>. + This function also requires the executor globals as arguments. For + examples of these functions, see Listing 9.15 and Figure 9.10. Of + course, all the examples are also available on the CD-ROM. + </para> + <figure> + <title>Listing 9.15. Printing execution information.</title> + <programlisting> +zend_printf("The name of the current function is %s<br>", get_active_function_name()); zend_printf("The file currently executed is %s<br>", zend_get_executed_filename(ELS_C)); -zend_printf("The current line being executed is %i<br>", zend_get_executed_lineno(ELS_C));</programlisting><graphic fileref="figures/Extending_Zend_9_execution_info.png"/> -</figure> -</section> -</chapter> +zend_printf("The current line being executed is %i<br>", zend_get_executed_lineno(ELS_C)); + </programlisting> + <graphic fileref="figures/Extending_Zend_9_execution_info.png"/> + </figure> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_Returning.xml diff -u ZendAPI/Extending_Zend_Returning.xml:1.5 ZendAPI/Extending_Zend_Returning.xml:1.6 --- ZendAPI/Extending_Zend_Returning.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Returning.xml Mon Feb 11 05:10:33 2002 @@ -1,145 +1,212 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.returning"> -<title>Returning Values</title> -<para>Returning values from your functions to PHP was described briefly in an earlier section; this section gives the details. Return values are passed via the <envar>return_value</envar> variable, -which is passed to your functions as argument. The <envar>return_value</envar> argument -consists of a <envar>zval</envar> container (see the earlier discussion of the call -interface) that you can freely modify. The container -itself is already allocated, so you don't have to run -<literal>MAKE_STD_ZVAL</literal> on it. Instead, you can access its -members directly.</para> -<para>To make returning values from functions easier and to prevent hassles with -accessing the internal structures of the <envar>zval</envar> container, a set of predefined macros is available (as usual). These macros automatically set the -correspondent type and value, as described in Tables 9.14 and 9.15.</para> -<figure> -<title>Table 9.14. Predefined Macros for Returning Values from a Function</title> -<programlisting>Note: The macros in Table 9.14 automatically return from your function.</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_RESOURCE(resource)</literal></entry> -<entry colname="col2">Returns a resource.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_BOOL(bool)</literal></entry> -<entry colname="col2">Returns a Boolean.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_NULL()</literal></entry> -<entry colname="col2">Returns nothing (a NULL value).</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_LONG(long)</literal></entry> -<entry colname="col2">Returns a long.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_DOUBLE(double)</literal></entry> -<entry colname="col2">Returns a double.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_STRING(string, -duplicate)</literal></entry> -<entry colname="col2">Returns a string. The <envar>duplicate</envar> flag -indicates whether the string should be duplicated using -<function>estrdup</function>.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_STRINGL(string, length, -duplicate)</literal></entry> -<entry colname="col2">Returns a string of the specified length; otherwise, -behaves like <literal>RETURN_STRING</literal>. This macro is faster and binary-safe, however.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_EMPTY_STRING()</literal></entry> -<entry colname="col2">Returns an empty string.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_FALSE</literal></entry> -<entry colname="col2">Returns Boolean false.</entry> -</row> -<row> -<entry colname="col1"><literal>RETURN_TRUE</literal></entry> -<entry colname="col2">Returns Boolean true.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<figure> -<title>Table 9.15. Predefined Macros for Setting the Return Value of a Function</title> -<programlisting>Note: The macros in Table 9.15 only <emphasis>set</emphasis> the return value; they don't return from your function.</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_RESOURCE(resource)</literal></entry> -<entry colname="col2">Sets the return value to the specified resource.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_BOOL(bool)</literal></entry> -<entry colname="col2">Sets the return value to the specified Boolean -value.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_NULL</literal></entry> -<entry colname="col2">Sets the return value to NULL.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_LONG(long)</literal></entry> -<entry colname="col2">Sets the return value to the specified long.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_DOUBLE(double)</literal></entry> -<entry colname="col2">Sets the return value to the specified double.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_STRING(string, -duplicate)</literal></entry> -<entry colname="col2">Sets the return value to the specified string and -duplicates it to Zend internal memory if desired (see also -<literal>RETURN_STRING</literal>).</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_STRINGL(string, length, -duplicate)</literal></entry> -<entry colname="col2">Sets the return value to the specified string and forces the length to become <envar>length</envar> (see -also <literal>RETVAL_STRING</literal>). This macro is faster and binary-safe, and -should be used whenever the string length is known.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_EMPTY_STRING</literal></entry> -<entry colname="col2">Sets the return value to an empty string.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_FALSE</literal></entry> -<entry colname="col2">Sets the return value to Boolean false.</entry> -</row> -<row> -<entry colname="col1"><literal>RETVAL_TRUE</literal></entry> -<entry colname="col2">Sets the return value to Boolean true.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<para>Complex types such as arrays and objects can be returned by -using <function>array_init</function> and <function>object_init</function>, as -well as the corresponding hash functions on <envar>return_value</envar>. Since -these types cannot be constructed of trivial information, there are no -predefined macros for them.</para> -</chapter> +  + <chapter id="zend.returning"> + <title>Returning Values</title> + <para> + Returning values from your functions to PHP was described briefly + in an earlier section; this section gives the details. Return + values are passed via the <envar>return_value</envar> variable, + which is passed to your functions as argument. The + <envar>return_value</envar> argument consists of a + <envar>zval</envar> container (see the earlier discussion of the + call interface) that you can freely modify. The container itself is + already allocated, so you don't have to run + <literal>MAKE_STD_ZVAL</literal> on it. Instead, you can access its + members directly. + </para> + <para> + To make returning values from functions easier and to prevent + hassles with accessing the internal structures of the + <envar>zval</envar> container, a set of predefined macros is + available (as usual). These macros automatically set the + correspondent type and value, as described in Tables 9.14 and 9.15. + </para> + <figure> + <title>Table 9.14. Predefined Macros for Returning Values from a + Function</title> + <programlisting>Note: The macros in Table 9.14 automatically return + from your function.</programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_RESOURCE(resource)</literal></entry> + <entry colname="col2">Returns a resource.</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_BOOL(bool)</literal></entry> + <entry colname="col2">Returns a Boolean.</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_NULL()</literal></entry> + <entry colname="col2">Returns nothing (a NULL value).</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_LONG(long)</literal></entry> + <entry colname="col2">Returns a long.</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_DOUBLE(double)</literal></entry> + <entry colname="col2">Returns a double.</entry> + </row> + <row> + <entry colname="col1"> + <literal>RETURN_STRING(string, duplicate)</literal> + </entry> + <entry colname="col2"> + Returns a string. The <envar>duplicate</envar> flag indicates + whether the string should be duplicated using + <function>estrdup</function>. + </entry> + </row> + <row> + <entry colname="col1"> + <literal>RETURN_STRINGL(string, length, duplicate)</literal> + </entry> + <entry colname="col2"> + Returns a string of the specified length; otherwise, behaves + like <literal>RETURN_STRING</literal>. This macro is faster + and binary-safe, however. + </entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_EMPTY_STRING()</literal></entry> + <entry colname="col2">Returns an empty string.</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_FALSE</literal></entry> + <entry colname="col2">Returns Boolean false.</entry> + </row> + <row> + <entry colname="col1"><literal>RETURN_TRUE</literal></entry> + <entry colname="col2">Returns Boolean true.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <figure> + <title>Table 9.15. Predefined Macros for Setting the Return Value + of a Function</title> + <programlisting> + Note: The macros in Table 9.15 only <emphasis>set</emphasis> the + return value; they don't return from your function. + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_RESOURCE(resource)</literal></entry> + <entry colname="col2">Sets the return value to the specified + resource.</entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_BOOL(bool)</literal></entry> + <entry colname="col2">Sets the return value to the specified + Boolean value.</entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_NULL</literal></entry> + <entry colname="col2">Sets the return value to NULL.</entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_LONG(long)</literal></entry> + <entry colname="col2"> + Sets the return value to the specified long. + </entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_DOUBLE(double)</literal></entry> + <entry colname="col2"> + Sets the return value to the specified double. + </entry> + </row> + <row> + <entry colname="col1"> + <literal>RETVAL_STRING(string, duplicate)</literal> + </entry> + <entry colname="col2"> + Sets the return value to the specified string and duplicates + it to Zend internal memory if desired (see also + <literal>RETURN_STRING</literal>). + </entry> + </row> + <row> + <entry colname="col1"> + <literal>RETVAL_STRINGL(string, length, duplicate)</literal> + </entry> + <entry colname="col2"> + Sets the return value to the specified string and forces the + length to become <envar>length</envar> (see also + <literal>RETVAL_STRING</literal>). This macro is faster and + binary-safe, and should be used whenever the string length is + known. + </entry> + </row> + <row> + <entry colname="col1"> + <literal>RETVAL_EMPTY_STRING</literal> + </entry> + <entry colname="col2"> + Sets the return value to an empty string. + </entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_FALSE</literal></entry> + <entry colname="col2"> + Sets the return value to Boolean false. + </entry> + </row> + <row> + <entry colname="col1"><literal>RETVAL_TRUE</literal></entry> + <entry colname="col2"> + Sets the return value to Boolean true. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <para> + Complex types such as arrays and objects can be returned by using + <function>array_init</function> and + <function>object_init</function>, as well as the corresponding hash + functions on <envar>return_value</envar>. Since these types cannot + be constructed of trivial information, there are no predefined + macros for them. + </para> + </chapter>  + Index: ZendAPI/Extending_Zend_StartupAndShutdown.xml diff -u ZendAPI/Extending_Zend_StartupAndShutdown.xml:1.4 ZendAPI/Extending_Zend_StartupAndShutdown.xml:1.5 --- ZendAPI/Extending_Zend_StartupAndShutdown.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_StartupAndShutdown.xml Mon Feb 11 05:10:33 2002 @@ -1,26 +1,56 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.startup-and-shutdown"> -<title>Startup and Shutdown Functions</title> -<para>Startup and shutdown functions can be used for one-time initialization -and deinitialization of your modules. As discussed earlier in this -chapter (see the description of the Zend module descriptor block), there are -global, module, and request startup and shutdown events.</para> -<para>The global startup functions are called once when PHP starts up; -similarly, the global shutdown functions are called once when PHP shuts -down. Please note that they're really only called <emphasis>once</emphasis>, -not when a new Apache process is being created!</para> -<para>The module startup and shutdown functions are called whenever a module is -loaded and needs initialization; the request startup and shutdown functions are -called every time a request is processed (meaning that a file is being -executed).</para> -<para>For dynamic extensions, module and request startup/shutdown events -happen at the same time.</para> -<para>Declaration and implementation of these functions can be done with -macros; see the earlier section "Declaration of the Zend Module Block" for details.</para> -</chapter> +  + <chapter id="zend.startup-and-shutdown"> + <title>Startup and Shutdown Functions</title> + <para> + Startup and shutdown functions can be used for one-time + initialization and deinitialization of your modules. As discussed + earlier in this chapter (see the description of the Zend module + descriptor block), there are global, module, and request startup + and shutdown events. + </para> + <para> + The global startup functions are called once when PHP starts up; + similarly, the global shutdown functions are called once when PHP + shuts down. Please note that they're really only called + <emphasis>once</emphasis>, not when a new Apache process is being + created! + </para> + <para> + The module startup and shutdown functions are called whenever a + module is loaded and needs initialization; the request startup and + shutdown functions are called every time a request is processed + (meaning that a file is being executed). + </para> + <para> + For dynamic extensions, module and request startup/shutdown events + happen at the same time. + </para> + <para> + Declaration and implementation of these functions can be done with + macros; see the earlier section "Declaration of the Zend Module + Block" for details. + </para> + </chapter>  + Index: ZendAPI/Extending_Zend_Structure.xml diff -u ZendAPI/Extending_Zend_Structure.xml:1.6 ZendAPI/Extending_Zend_Structure.xml:1.7 --- ZendAPI/Extending_Zend_Structure.xml:1.6 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Structure.xml Mon Feb 11 05:10:33 2002 @@ -1,263 +1,364 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.structure"> -<title>Source Discussion</title> -<para>Now that you've got a safe build environment and you're able to include -the modules into PHP files, it's time to discuss how everything works.</para> -<section id="zend.structure.module"> -<title>Module Structure</title> -<para>All PHP modules follow a common structure: -<itemizedlist> -<listitem> -<para>Header file inclusions (to include all required macros, API definitions, - etc.)</para> -</listitem> -<listitem> -<para>C declaration of exported functions (required to declare the Zend - function block)</para> -</listitem> -<listitem> -<para>Declaration of the Zend function block</para> -</listitem> -<listitem> -<para>Declaration of the Zend module block</para> -</listitem> -<listitem> -<para>Implementation of <function>get_module</function></para> -</listitem> -<listitem> -<para>Implementation of all exported functions</para> -</listitem> -</itemizedlist></para> -</section> -<section id="zend.structure.headers"> -<title>Header File Inclusions</title> -<para>The only header file you really have to include for your modules is -<filename>php.h</filename>, located in the PHP directory. This file makes all -macros and API definitions required to build new modules available to your -code. -</para><para><emphasis>Tip:</emphasis> It's good practice to create a separate header file for your module -that contains module-specific definitions. This header file should contain -all the forward definitions -for exported functions and include <filename>php.h</filename>.</para> -</section> -<section id="zend.structure.exporting-functions"> -<title>Declaring Exported Functions</title> -<para>To declare functions that are to be exported (i.e., made available to PHP -as new native functions), Zend provides a set of macros. A sample declaration -looks like this: -<programlisting>ZEND_FUNCTION(my_function);</programlisting></para> -<para><literal>ZEND_FUNCTION</literal> declares a new C function that complies -with Zend's internal API. This means that the function is of -type <literal>void</literal> and -accepts <literal>INTERNAL_FUNCTION_PARAMETERS</literal> (another macro) as -parameters. Additionally, it prefixes the function name with -<literal>zif</literal>. The immediately expanded version of the above -definitions would look like this: -<programlisting>void zif_my_function(INTERNAL_FUNCTION_PARAMETERS);</programlisting>Expanding -<literal>INTERNAL_FUNCTION_PARAMETERS</literal> results in -the following:<programlisting>void zif_my_function(int ht, zval *return_value, zval *this_ptr, int return_value_used, zend_executor_globals *executor_globals);</programlisting> - </para><para>Since the interpreter and executor core have been separated from the main -PHP package, a second API defining macros and function sets has evolved: the -Zend API. As the Zend API now handles quite a few of the responsibilities -that previously belonged to PHP, a lot of PHP functions have been reduced to -macros aliasing to calls into the Zend API. The recommended practice is to -use the Zend API wherever possible, as the old API is only preserved -for compatibility reasons. For example, the types <envar>zval</envar> and <envar>pval</envar> are identical. <envar>zval</envar> is Zend's definition; <envar>pval</envar> is PHP's -definition (actually, <envar>pval</envar> is an alias -for <envar>zval</envar> now). As the -macro <literal>INTERNAL_FUNCTION_PARAMETERS</literal> is a Zend macro, the above -declaration contains <envar>zval</envar>. When writing code, you should always -use <envar>zval</envar> to conform to the new Zend API.</para><para>The parameter list of this declaration is very important; you should keep these parameters in mind (see Table 9.1 for descriptions). -<figure> -<title>Table 9.1. Zend's Parameters to Functions Called from PHP</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.79*"/> -<tbody> - <row> - <entry colname="col1">Parameter</entry> - <entry colname="col2">Description</entry> - </row> - <row> - <entry colname="col1"><envar>ht</envar></entry> - <entry colname="col2">The number of arguments passed to the Zend function. - You should not touch this directly, but instead use ZEND_NUM_ARGS() to obtain the - value.</entry> - </row> - <row> - <entry colname="col1"><envar>return_value</envar></entry> - <entry colname="col2">This variable is used to pass any return values of - your function back to PHP. Access to this variable is best done using the - predefined macros. For a description of these see below.</entry> - </row> - <row> - <entry colname="col1"><envar>this_ptr</envar></entry> - <entry colname="col2">Using this variable, you can gain access to the object - in which your function is contained, if it's used within an object. Use - the function <function>getThis</function> to obtain this pointer.</entry> - </row> - <row> - <entry colname="col1"><envar>return_value_used</envar></entry> - <entry colname="col2">This flag indicates whether an eventual return value - from this function will actually be used by the calling script. - <literal>0</literal> indicates that the return value is not used; - <literal>1</literal> indicates that the caller expects a return value. - Evaluation of this flag can be done to verify correct usage of the function as - well as speed optimizations in case returning a value requires expensive - operations (for an example, see how <filename>array.c</filename> makes use of - this).</entry> - </row> - <row> - <entry colname="col1"><envar>executor_globals</envar></entry> - <entry colname="col2">This variable points to global settings of the Zend - engine. You'll find this useful when creating new variables, for example -(more about this later). The executor globals can also be introduced to your - function by using the macro <literal>ELS_FETCH()</literal>.</entry> - </row> -</tbody> -</tgroup> -</informaltable> -</figure></para> -</section> -<section id="zend.structure.function-block"> -<title>Declaration of the Zend Function Block</title> -<para>Now that you have declared the functions to be exported, you also -have to introduce them to Zend. Introducing the list of functions is done by -using an array of <envar>zend_function_entry</envar>. This array consecutively -contains all functions that are to be made available externally, with the function's name -as it should appear in PHP and its name as defined in the C source. -Internally, <envar>zend_function_entry</envar> is defined as shown in Listing 9.5. -</para><para><figure> -<title>Listing 9.5. Internal declaration of <envar>zend_function_entry</envar>.</title> -<programlisting>typedef struct _zend_function_entry { +  + <chapter id="zend.structure"> + <title>Source Discussion</title> + <para> + Now that you've got a safe build environment and you're able to include + the modules into PHP files, it's time to discuss how everything works. + </para> + <section id="zend.structure.module"> + <title>Module Structure</title> + <para> + All PHP modules follow a common structure: + <itemizedlist> + <listitem> + <para> + Header file inclusions (to include all required macros, API + definitions, etc.) + </para> + </listitem> + <listitem> + <para> + C declaration of exported functions (required to declare the Zend + function block) + </para> + </listitem> + <listitem> + <para>Declaration of the Zend function block</para> + </listitem> + <listitem> + <para>Declaration of the Zend module block</para> + </listitem> + <listitem> + <para>Implementation of <function>get_module</function></para> + </listitem> + <listitem> + <para>Implementation of all exported functions</para> + </listitem> + </itemizedlist></para> + </section> + <section id="zend.structure.headers"> + <title>Header File Inclusions</title> + <para> + The only header file you really have to include for your modules is + <filename>php.h</filename>, located in the PHP directory. This file makes all + macros and API definitions required to build new modules available to your + code. + </para> + <para> + <emphasis>Tip:</emphasis> It's good practice to create a separate + header file for your module that contains module-specific + definitions. This header file should contain all the forward + definitions for exported functions and include + <filename>php.h</filename>. If you created your module using + <literal>ext_skel</literal> you already have such a header file + prepared. + </para> + </section> + <section id="zend.structure.exporting-functions"> + <title>Declaring Exported Functions</title> + <para> + To declare functions that are to be exported (i.e., made available to PHP + as new native functions), Zend provides a set of macros. A sample declaration + looks like this: + <programlisting> +ZEND_FUNCTION ( my_function ); + </programlisting> + </para> + <para> + <literal>ZEND_FUNCTION</literal> declares a new C function that complies + with Zend's internal API. This means that the function is of + type <literal>void</literal> and + accepts <literal>INTERNAL_FUNCTION_PARAMETERS</literal> (another macro) as + parameters. Additionally, it prefixes the function name with + <literal>zif</literal>. The immediately expanded version of the above + definitions would look like this: + <programlisting> +void zif_my_function ( INTERNAL_FUNCTION_PARAMETERS ); + </programlisting> + Expanding <literal>INTERNAL_FUNCTION_PARAMETERS</literal> + results in the following: + <programlisting> +void zif_my_function( int ht + , zval * return_value + , zval * this_ptr + , int return_value_used + , zend_executor_globals * executor_globals + ); + </programlisting> + </para> + <para> + Since the interpreter and executor core have been separated from + the main PHP package, a second API defining macros and function + sets has evolved: the Zend API. As the Zend API now handles quite + a few of the responsibilities that previously belonged to PHP, a + lot of PHP functions have been reduced to macros aliasing to calls + into the Zend API. The recommended practice is to use the Zend API + wherever possible, as the old API is only preserved for + compatibility reasons. For example, the types <envar>zval</envar> + and <envar>pval</envar> are identical. <envar>zval</envar> is + Zend's definition; <envar>pval</envar> is PHP's definition + (actually, <envar>pval</envar> is an alias for <envar>zval</envar> + now). As the macro <literal>INTERNAL_FUNCTION_PARAMETERS</literal> + is a Zend macro, the above declaration contains + <envar>zval</envar>. When writing code, you should always use + <envar>zval</envar> to conform to the new Zend API. + </para> + <para> + The parameter list of this declaration is very important; you should keep these parameters in mind (see Table 9.1 for descriptions). + <figure> + <title>Table 9.1. Zend's Parameters to Functions Called from PHP</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.79*"/> + <tbody> + <row> + <entry colname="col1">Parameter</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><envar>ht</envar></entry> + <entry colname="col2"> + The number of arguments passed to the Zend function. + You should not touch this directly, but instead use ZEND_NUM_ARGS() to obtain the + value. + </entry> + </row> + <row> + <entry colname="col1"> + <envar>return_value</envar></entry> + <entry colname="col2"> + This variable is used to pass any return values of + your function back to PHP. Access to this variable is best done using the + predefined macros. For a description of these see below. + </entry> + </row> + <row> + <entry colname="col1"><envar>this_ptr</envar></entry> + <entry colname="col2"> + Using this variable, you can gain access to the object + in which your function is contained, if it's used within an object. Use + the function <function>getThis</function> to obtain this pointer. + </entry> + </row> + <row> + <entry colname="col1"><envar>return_value_used</envar></entry> + <entry colname="col2"> + This flag indicates whether an eventual return value + from this function will actually be used by the calling script. + <literal>0</literal> indicates that the return value is not used; + <literal>1</literal> indicates that the caller expects a return value. + Evaluation of this flag can be done to verify correct usage of the function as + well as speed optimizations in case returning a value requires expensive + operations (for an example, see how <filename>array.c</filename> makes use of + this). + </entry> + </row> + <row> + <entry colname="col1"><envar>executor_globals</envar></entry> + <entry colname="col2"> + This variable points to global settings of the Zend + engine. You'll find this useful when creating new variables, for example + (more about this later). The executor globals can also be introduced to your + function by using the macro <literal>ELS_FETCH()</literal>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure></para> + </section> + <section id="zend.structure.function-block"> + <title>Declaration of the Zend Function Block</title> + <para> + Now that you have declared the functions to be exported, you also + have to introduce them to Zend. Introducing the list of functions is done by + using an array of <envar>zend_function_entry</envar>. This array consecutively + contains all functions that are to be made available externally, with the function's name + as it should appear in PHP and its name as defined in the C source. + Internally, <envar>zend_function_entry</envar> is defined as shown in Listing 9.5. + </para> + <para> + <figure> + <title>Listing 9.5. Internal declaration of <envar>zend_function_entry</envar>.</title> + <programlisting> +typedef struct _zend_function_entry { char *fname; void (*handler)(INTERNAL_FUNCTION_PARAMETERS); unsigned char *func_arg_types; } zend_function_entry; -</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.82*"/> -<tbody> -<row> -<entry colname="col1">Entry</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><envar>fname</envar></entry> -<entry colname="col2">Denotes the function name as seen in PHP (for - example, <literal>fopen</literal>, <literal>mysql_connect</literal>, or, in our - example, <literal>first_module</literal>).</entry> -</row> -<row> -<entry colname="col1"><envar>handler</envar></entry> -<entry colname="col2">Pointer to the C function responsible for handling calls - to this function. For example, see the standard macro - <literal>INTERNAL_FUNCTION_PARAMETERS</literal> discussed earlier.</entry> -</row> -<row> -<entry colname="col1"><envar>func_arg_types</envar></entry> -<entry colname="col2">Allows you to mark certain parameters so that they're forced to be passed by reference. You usually should set this to - NULL.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure>In the example above, the declaration looks like this: -<programlisting>zend_function_entry firstmod_functions[] = + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.82*"/> + <tbody> + <row> + <entry colname="col1">Entry</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><envar>fname</envar></entry> + <entry colname="col2"> + Denotes the function name as seen in PHP (for + example, <literal>fopen</literal>, <literal>mysql_connect</literal>, or, in our + example, <literal>first_module</literal>). + </entry> + </row> + <row> + <entry colname="col1"><envar>handler</envar></entry> + <entry colname="col2"> + Pointer to the C function responsible for handling calls + to this function. For example, see the standard macro + <literal>INTERNAL_FUNCTION_PARAMETERS</literal> discussed earlier. + </entry> + </row> + <row> + <entry colname="col1"><envar>func_arg_types</envar></entry> + <entry colname="col2"> + Allows you to mark certain parameters so that they're forced + to be passed by reference. You usually should set this to + NULL. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure>In the example above, the declaration looks like this: + <programlisting> +zend_function_entry firstmod_functions[] = { ZEND_FE(first_module, NULL) {NULL, NULL, NULL} -};</programlisting>You can see that the last entry in the list always has to -be <literal>{NULL, NULL, NULL}</literal>. This marker has to be set for Zend to know when the end of the list of exported functions is -reached. -</para><para><emphasis>Note:</emphasis> You <emphasis>cannot</emphasis> use the predefined macros for the end -marker, as these would try to refer to a function named "NULL"!</para><para>The macro <literal>ZEND_FE</literal> simply expands to a structure entry -in <envar>zend_function_entry</envar>. Note that these macros introduce a -special naming scheme to your functions - your C functions will be -prefixed with <literal>zif_</literal>, meaning -that <literal>ZEND_FE(first_module)</literal> will refer to a C -function <function>zif_first_module</function>. If you want to mix -macro usage with hand-coded entries (not a good practice), keep -this in mind. -</para><para>Tip: Compilation errors that refer to functions -named <function>zif_*</function> relate to functions defined -with <literal>ZEND_FE</literal>.</para> -<para>Table 9.2 shows a list of all the macros that you can use to define -functions.</para> -<figure> -<title>Table 9.2. Macros for Defining Functions</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="1.08*"/> -<tbody> -<row> -<entry colname="col1">Macro Name</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>ZEND_FE(name, arg_types)</literal></entry> -<entry colname="col2">Defines a function entry of the name <envar>name</envar> in -<envar>zend_function_entry</envar>. Requires a corresponding C -function. <envar>arg_types</envar> needs to be set to <literal>NULL</literal>. -This function uses automatic C function name generation by prefixing the PHP -function name with <literal>zif_</literal>. -For example, <literal>ZEND_FE("first_module", NULL)</literal> introduces a -function <function>first_module</function> to PHP and links it to the C -function <function>zif_first_module</function>. Use in conjunction -with <literal>ZEND_FUNCTION</literal>.</entry> -</row> -<row> -<entry colname="col1"><literal>ZEND_NAMED_FE(php_name, name, -arg_types)</literal></entry> -<entry colname="col2">Defines a function that will be available to PHP by the -name <envar>php_name</envar> and links it to the corresponding C -function <envar>name</envar>. <envar>arg_types</envar> needs to be set -to <literal>NULL</literal>. Use this function if you don't want the automatic -name prefixing introduced by <literal>ZEND_FE</literal>. Use in conjunction -with <literal>ZEND_NAMED_FUNCTION</literal>.</entry> -</row> -<row> -<entry colname="col1"><literal>ZEND_FALIAS(name, alias, -arg_types)</literal></entry> -<entry colname="col2">Defines an alias named -<envar>alias</envar> for <envar>name</envar>. <envar>arg_types</envar> needs to -be set to <literal>NULL</literal>. Doesn't require a corresponding C function; -refers to the alias target instead.</entry> -</row> -<row> -<entry colname="col1"><literal>PHP_FE(name, arg_types)</literal></entry> -<entry colname="col2">Old PHP API equivalent -of <literal>ZEND_FE</literal>.</entry> -</row> -<row> -<entry colname="col1"><literal>PHP_NAMED_FE(runtime_name, name, arg_types)</literal></entry> -<entry colname="col2">Old PHP API equivalent -of <literal>ZEND_NAMED_FE</literal>.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<para><emphasis>Note:</emphasis> You can't use <literal>ZEND_FE</literal> in conjunction -with <literal>PHP_FUNCTION</literal>, or <literal>PHP_FE</literal> in -conjunction with <literal>ZEND_FUNCTION</literal>. However, it's perfectly -legal to mix <literal>ZEND_FE</literal> and <literal>ZEND_FUNCTION</literal> with -<literal>PHP_FE</literal> and <literal>PHP_FUNCTION</literal> when staying with -the same macro set for each function to be declared. But mixing is <emphasis>not</emphasis> recommended; instead, you're advised to use the <literal>ZEND_*</literal> macros only.</para> -</section> +}; + </programlisting> + You can see that the last entry in the list always has to be + <literal>{NULL, NULL, NULL}</literal>. + This marker has to be set for Zend to know when the end of the + list of exported functions is reached. + </para> + <note> + <para> + You <emphasis>cannot</emphasis> use the predefined macros for the + end marker, as these would try to refer to a function named "NULL"! + </para> + </note> + <para> + The macro <literal>ZEND_FE</literal> (short for 'Zend Function + Entry') simply expands to a structure entry in + <envar>zend_function_entry</envar>. Note that these macros + introduce a special naming scheme to your functions - your C + functions will be prefixed with <literal>zif_</literal>, meaning + that <literal>ZEND_FE(first_module)</literal> will refer to a C + function <function>zif_first_module</function>. If you want to mix + macro usage with hand-coded entries (not a good practice), keep + this in mind. + </para> + <para> + Tip: Compilation errors that refer to functions + named <function>zif_*</function> relate to functions defined + with <literal>ZEND_FE</literal>. + </para> + <para> + Table 9.2 shows a list of all the macros that you can use to + define functions. + </para> + <figure> + <title>Table 9.2. Macros for Defining Functions</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.08*"/> + <tbody> + <row> + <entry colname="col1">Macro Name</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_FE(name, arg_types)</literal></entry> + <entry colname="col2"> + Defines a function entry of the name <envar>name</envar> in + <envar>zend_function_entry</envar>. Requires a corresponding C + function. <envar>arg_types</envar> needs to be set to <literal>NULL</literal>. + This function uses automatic C function name generation by prefixing the PHP + function name with <literal>zif_</literal>. + For example, <literal>ZEND_FE("first_module", NULL)</literal> introduces a + function <function>first_module</function> to PHP and links it to the C + function <function>zif_first_module</function>. Use in conjunction + with <literal>ZEND_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"> + <literal>ZEND_NAMED_FE(php_name, name, arg_types)</literal> + </entry> + <entry colname="col2"> + Defines a function that will be available to PHP by the + name <envar>php_name</envar> and links it to the corresponding C + function <envar>name</envar>. <envar>arg_types</envar> needs to be set + to <literal>NULL</literal>. Use this function if you don't want the automatic + name prefixing introduced by <literal>ZEND_FE</literal>. Use in conjunction + with <literal>ZEND_NAMED_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"> + <literal>ZEND_FALIAS(name, alias, arg_types)</literal> + </entry> + <entry colname="col2"> + Defines an alias named <envar>alias</envar> for + <envar>name</envar>. <envar>arg_types</envar> needs to be set + to <literal>NULL</literal>. Doesn't require a corresponding C + function; refers to the alias target instead. + </entry> + </row> + <row> + <entry colname="col1"><literal>PHP_FE(name, arg_types)</literal></entry> + <entry colname="col2"> + Old PHP API equivalent of <literal>ZEND_FE</literal>. + </entry> + </row> + <row> + <entry colname="col1"> + <literal>PHP_NAMED_FE(runtime_name, name, arg_types)</literal> + </entry> + <entry colname="col2"> + Old PHP API equivalent of <literal>ZEND_NAMED_FE</literal>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <para> + <emphasis>Note:</emphasis> You can't use + <literal>ZEND_FE</literal> in conjunction with + <literal>PHP_FUNCTION</literal>, or <literal>PHP_FE</literal> in + conjunction with <literal>ZEND_FUNCTION</literal>. However, it's + perfectly legal to mix <literal>ZEND_FE</literal> and + <literal>ZEND_FUNCTION</literal> with <literal>PHP_FE</literal> + and <literal>PHP_FUNCTION</literal> when staying with the same + macro set for each function to be declared. But mixing is + <emphasis>not</emphasis> recommended; instead, you're advised to + use the <literal>ZEND_*</literal> macros only. + </para> + </section> -<section id="zend.structure.module-block"> - <title>Declaration of the Zend Module Block</title> - <para> - This block is stored in the structure - <envar>zend_module_entry</envar> and contains all necessary - information to describe the contents of this module to Zend. You can - see the internal definition of this module in Listing 9.6. - </para> - <figure> - <title>Internal declaration of <envar>zend_module_entry</envar>.</title> - <programlisting>typedef struct _zend_module_entry zend_module_entry; - -struct _zend_module_entry { + <section id="zend.structure.module-block"> + <title>Declaration of the Zend Module Block</title> + <para> + This block is stored in the structure + <envar>zend_module_entry</envar> and contains all necessary + information to describe the contents of this module to Zend. You can + see the internal definition of this module in Listing 9.6. + </para> + <figure> + <title>Internal declaration of <envar>zend_module_entry</envar>.</title> + <programlisting> +typedef struct _zend_module_entry zend_module_entry; + + struct _zend_module_entry { unsigned short size; unsigned int zend_api; unsigned char zend_debug; @@ -275,165 +376,167 @@ [ Rest of the structure is not interesting here ] -};</programlisting> - <informaltable> - <tgroup cols="2"> - <colspec colnum="1" colname="col1" colwidth="1.00*"/> - <colspec colnum="2" colname="col2" colwidth="1.69*"/> - <thead> - <row> - <entry colname="col1">Entry</entry> - <entry colname="col2">Description</entry> - </row> - </thead> +}; +</programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.69*"/> + <thead> + <row> + <entry colname="col1">Entry</entry> + <entry colname="col2">Description</entry> + </row> + </thead> <tbody> - <row> - <entry colname="col1"> - <envar>size</envar>, <envar>zend_api</envar>, - <envar>zend_debug</envar> and <envar>zts</envar> - </entry> - <entry colname="col2"> - Usually filled with the - <literal>"STANDARD_MODULE_HEADER"</literal>, which fills these - four members with the size of the whole zend_module_entry, the - <literal>ZEND_MODULE_API_NO</literal>, whether it is a debug - build or normal build (<literal>ZEND_DEBUG</literal>) and if - ZTS is enabled (<literal>USING_ZTS</literal>). - </entry> - </row> - <row> - <entry colname="col1"><envar>name</envar></entry> - <entry colname="col2"> - Contains the module name (for example, <literal>"File - functions"</literal>, <literal>"Socket functions"</literal>, - <literal>"Crypt"</literal>, etc.). This name will show up in - <function>phpinfo</function>, in the section "Additional - Modules." - </entry> - </row> - <row> - <entry colname="col1"><envar>functions</envar></entry> - <entry colname="col2"> - Points to the Zend function block, discussed in the preceding - section. - </entry> - </row> - <row> - <entry colname="col1"><envar>module_startup_func</envar></entry> - <entry colname="col2"> - This function is called once upon module initialization and can - be used to do one-time initialization steps (such as initial - memory allocation, etc.). To indicate a failure during - initialization, return <literal>FAILURE</literal>; otherwise, - <literal>SUCCESS</literal>. To mark this field as unused, use - <literal>NULL</literal>. To declare a function, use the macro - <literal>ZEND_MINIT</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>module_shutdown_func</envar></entry> - <entry colname="col2"> - This function is called once upon module shutdown and can be - used to do one-time deinitialization steps (such as memory - deallocation). This is the counterpart to - <function>module_startup_func</function>. To indicate a failure - during deinitialization, return <literal>FAILURE</literal>; - otherwise, <literal>SUCCESS</literal>. To mark this field as - unused, use <literal>NULL</literal>. To declare a function, use - the macro <literal>ZEND_MSHUTDOWN</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>request_startup_func</envar></entry> - <entry colname="col2"> - This function is called once upon every page request and can be - used to do one-time initialization steps that are required to - process a request. To indicate a failure here, return - <literal>FAILURE</literal>; otherwise, - <literal>SUCCESS</literal>. <emphasis>Note:</emphasis> As - dynamic loadable modules are loaded only on page requests, the - request startup function is called right after the module - startup function (both initialization events happen at the same - time). To mark this field as unused, use - <literal>NULL</literal>. To declare a function, use the macro - <literal>ZEND_RINIT</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>request_shutdown_func</envar></entry> - <entry colname="col2"> - This function is called once after every page request and works - as counterpart to <function>request_startup_func</function>. To - indicate a failure here, return <literal>FAILURE</literal>; - otherwise, <literal>SUCCESS</literal>. - <emphasis>Note:</emphasis> As dynamic loadable modules are - loaded only on page requests, the request shutdown function is - immediately followed by a call to the module shutdown handler - (both deinitialization events happen at the same time). To mark - this field as unused, use <literal>NULL</literal>. To declare a - function, use the macro <literal>ZEND_RSHUTDOWN</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>info_func</envar></entry> - <entry colname="col2"> - When <function>phpinfo</function> is called in a script, Zend - cycles through all loaded modules and calls this function. - Every module then has the chance to print its own "footprint" - into the output page. Generally this is used to dump - environmental or statistical information. To mark this field as - unused, use <literal>NULL</literal>. To declare a function, use - the macro <literal>ZEND_MINFO</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>version</envar></entry> - <entry colname="col2"> - The version of the module. You can use - <literal>NO_VERSION_YET</literal> if you don't want to give the - module a version number yet, but we really recommend that you - add a version string here. Such a version string can look like - this (in chronological order): <literal>"2.5-dev"</literal>, - <literal>"2.5RC1"</literal>, <literal>"2.5"</literal> or - <literal>"2.5pl3"</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>global_startup_func</envar></entry> - <entry colname="col2"> - The global startup functions are rarely used. You should - usually skip through the rest of this structure by placing the - macro <literal>STANDARD_MODULE_PROPERTIES</literal>. To mark - this field as unused, use <literal>NULL</literal>. To declare a - function, use the macro <literal>ZEND_GINIT</literal>. - </entry> - </row> - <row> - <entry colname="col1"><envar>global_shutdown_func</envar></entry> - <entry colname="col2"> - To mark this field as unused, use <literal>NULL</literal>. To - declare a function, use the macro - <literal>ZEND_GSHUTDOWN</literal>. - </entry> - </row> - <row> - <entry colname="col1">Remaining structure elements</entry> - <entry colname="col2"> - These are used internally and can be prefilled by using the - macro <literal>STANDARD_MODULE_PROPERTIES_EX</literal>. You - should not assign any values to them. Use - <literal>STANDARD_MODULE_PROPERTIES_EX</literal> only if you - use global startup and shutdown functions; otherwise, use - <literal>STANDARD_MODULE_PROPERTIES</literal> directly. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </figure> - <para> - In our example, this structure is implemented as follows: - <programlisting>zend_module_entry firstmod_module_entry = + <row> + <entry colname="col1"> + <envar>size</envar>, <envar>zend_api</envar>, + <envar>zend_debug</envar> and <envar>zts</envar> + </entry> + <entry colname="col2"> + Usually filled with the + <literal>"STANDARD_MODULE_HEADER"</literal>, which fills these + four members with the size of the whole zend_module_entry, the + <literal>ZEND_MODULE_API_NO</literal>, whether it is a debug + build or normal build (<literal>ZEND_DEBUG</literal>) and if + ZTS is enabled (<literal>USING_ZTS</literal>). + </entry> + </row> + <row> + <entry colname="col1"><envar>name</envar></entry> + <entry colname="col2"> + Contains the module name (for example, <literal>"File + functions"</literal>, <literal>"Socket functions"</literal>, + <literal>"Crypt"</literal>, etc.). This name will show up in + <function>phpinfo</function>, in the section "Additional + Modules." + </entry> + </row> + <row> + <entry colname="col1"><envar>functions</envar></entry> + <entry colname="col2"> + Points to the Zend function block, discussed in the preceding + section. + </entry> + </row> + <row> + <entry colname="col1"><envar>module_startup_func</envar></entry> + <entry colname="col2"> + This function is called once upon module initialization and can + be used to do one-time initialization steps (such as initial + memory allocation, etc.). To indicate a failure during + initialization, return <literal>FAILURE</literal>; otherwise, + <literal>SUCCESS</literal>. To mark this field as unused, use + <literal>NULL</literal>. To declare a function, use the macro + <literal>ZEND_MINIT</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>module_shutdown_func</envar></entry> + <entry colname="col2"> + This function is called once upon module shutdown and can be + used to do one-time deinitialization steps (such as memory + deallocation). This is the counterpart to + <function>module_startup_func</function>. To indicate a failure + during deinitialization, return <literal>FAILURE</literal>; + otherwise, <literal>SUCCESS</literal>. To mark this field as + unused, use <literal>NULL</literal>. To declare a function, use + the macro <literal>ZEND_MSHUTDOWN</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>request_startup_func</envar></entry> + <entry colname="col2"> + This function is called once upon every page request and can be + used to do one-time initialization steps that are required to + process a request. To indicate a failure here, return + <literal>FAILURE</literal>; otherwise, + <literal>SUCCESS</literal>. <emphasis>Note:</emphasis> As + dynamic loadable modules are loaded only on page requests, the + request startup function is called right after the module + startup function (both initialization events happen at the same + time). To mark this field as unused, use + <literal>NULL</literal>. To declare a function, use the macro + <literal>ZEND_RINIT</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>request_shutdown_func</envar></entry> + <entry colname="col2"> + This function is called once after every page request and works + as counterpart to <function>request_startup_func</function>. To + indicate a failure here, return <literal>FAILURE</literal>; + otherwise, <literal>SUCCESS</literal>. + <emphasis>Note:</emphasis> As dynamic loadable modules are + loaded only on page requests, the request shutdown function is + immediately followed by a call to the module shutdown handler + (both deinitialization events happen at the same time). To mark + this field as unused, use <literal>NULL</literal>. To declare a + function, use the macro <literal>ZEND_RSHUTDOWN</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>info_func</envar></entry> + <entry colname="col2"> + When <function>phpinfo</function> is called in a script, Zend + cycles through all loaded modules and calls this function. + Every module then has the chance to print its own "footprint" + into the output page. Generally this is used to dump + environmental or statistical information. To mark this field as + unused, use <literal>NULL</literal>. To declare a function, use + the macro <literal>ZEND_MINFO</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>version</envar></entry> + <entry colname="col2"> + The version of the module. You can use + <literal>NO_VERSION_YET</literal> if you don't want to give the + module a version number yet, but we really recommend that you + add a version string here. Such a version string can look like + this (in chronological order): <literal>"2.5-dev"</literal>, + <literal>"2.5RC1"</literal>, <literal>"2.5"</literal> or + <literal>"2.5pl3"</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>global_startup_func</envar></entry> + <entry colname="col2"> + The global startup functions are rarely used. You should + usually skip through the rest of this structure by placing the + macro <literal>STANDARD_MODULE_PROPERTIES</literal>. To mark + this field as unused, use <literal>NULL</literal>. To declare a + function, use the macro <literal>ZEND_GINIT</literal>. + </entry> + </row> + <row> + <entry colname="col1"><envar>global_shutdown_func</envar></entry> + <entry colname="col2"> + To mark this field as unused, use <literal>NULL</literal>. To + declare a function, use the macro + <literal>ZEND_GSHUTDOWN</literal>. + </entry> + </row> + <row> + <entry colname="col1">Remaining structure elements</entry> + <entry colname="col2"> + These are used internally and can be prefilled by using the + macro <literal>STANDARD_MODULE_PROPERTIES_EX</literal>. You + should not assign any values to them. Use + <literal>STANDARD_MODULE_PROPERTIES_EX</literal> only if you + use global startup and shutdown functions; otherwise, use + <literal>STANDARD_MODULE_PROPERTIES</literal> directly. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <para> + In our example, this structure is implemented as follows: + <programlisting> +zend_module_entry firstmod_module_entry = { STANDARD_MODULE_HEADER, "First Module", @@ -441,136 +544,151 @@ NULL, NULL, NULL, NULL, NULL, NO_VERSION_YET, STANDARD_MODULE_PROPERTIES, -};</programlisting> - This is basically the easiest and most minimal set of values you - could ever use. The module name is set to <literal>First - Module</literal>, then the function list is referenced, after which - all startup and shutdown functions are marked as being unused. - </para> - <para> - For reference purposes, you can find a list of the macros involved - in declared startup and shutdown functions in Table 9.3. These are - not used in our basic example yet, but will be demonstrated later - on. You should make use of these macros to declare your startup and - shutdown functions, as these require special arguments to be passed - (<literal>INIT_FUNC_ARGS</literal> and - <literal>SHUTDOWN_FUNC_ARGS</literal>), which are automatically - included into the function declaration when using the predefined - macros. If you declare your functions manually and the PHP - developers decide that a change in the argument list is necessary, - you'll have to change your module sources to remain compatible. - </para> - <figure> - <title>Macros to Declare Startup and Shutdown Functions</title> - <informaltable> - <tgroup cols="2"> - <colspec colnum="1" colname="col1" colwidth="1.00*"/> - <colspec colnum="2" colname="col2" colwidth="1.41*"/> - <tbody> - <row> - <entry colname="col1">Macro</entry> - <entry colname="col2">Description</entry> - </row> - <row> - <entry colname="col1"><literal>ZEND_MINIT(module)</literal></entry> - <entry colname="col2"> - Declares a function for module startup. The generated name will - be <literal>zend_minit_<module></literal> (for example, - <literal>zend_minit_first_module</literal>). Use in - conjunction with <literal>ZEND_MINIT_FUNCTION</literal>. - </entry> - </row> - <row> +}; + </programlisting> + This is basically the easiest and most minimal set of values you + could ever use. The module name is set to <literal>First + Module</literal>, then the function list is referenced, after which + all startup and shutdown functions are marked as being unused. + </para> + <para> + For reference purposes, you can find a list of the macros involved + in declared startup and shutdown functions in Table 9.3. These are + not used in our basic example yet, but will be demonstrated later + on. You should make use of these macros to declare your startup and + shutdown functions, as these require special arguments to be passed + (<literal>INIT_FUNC_ARGS</literal> and + <literal>SHUTDOWN_FUNC_ARGS</literal>), which are automatically + included into the function declaration when using the predefined + macros. If you declare your functions manually and the PHP + developers decide that a change in the argument list is necessary, + you'll have to change your module sources to remain compatible. + </para> + <figure> + <title>Macros to Declare Startup and Shutdown Functions</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="1.41*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_MINIT(module)</literal></entry> + <entry colname="col2"> + Declares a function for module startup. The generated name will + be <literal>zend_minit_<module></literal> (for example, + <literal>zend_minit_first_module</literal>). Use in + conjunction with <literal>ZEND_MINIT_FUNCTION</literal>. + </entry> + </row> + <row> <entry colname="col1"><literal>ZEND_MSHUTDOWN(module)</literal></entry> - <entry colname="col2"> - Declares a function for module shutdown. The generated name - will be <literal>zend_mshutdown_<module></literal> (for - example, <literal>zend_mshutdown_first_module</literal>). Use - in conjunction with <literal>ZEND_MSHUTDOWN_FUNCTION</literal>. - </entry> - </row> - <row> - <entry colname="col1"><literal>ZEND_RINIT(module)</literal></entry> - <entry colname="col2"> - Declares a function for request startup. The generated name - will be <literal>zend_rinit_<module></literal> (for - example, <literal>zend_rinit_first_module</literal>). Use in - conjunction with <literal>ZEND_RINIT_FUNCTION</literal>. - </entry> - </row> - <row> - <entry colname="col1"><literal>ZEND_RSHUTDOWN(module)</literal></entry> - <entry colname="col2"> - Declares a function for request shutdown. The generated name - will be <literal>zend_rshutdown_<module></literal> (for - example, <literal>zend_rshutdown_first_module</literal>). Use - in conjunction with <literal>ZEND_RSHUTDOWN_FUNCTION</literal>. - </entry> - </row> - <row> - <entry colname="col1"><literal>ZEND_GINIT(module)</literal></entry> - <entry colname="col2"> - Declares a function for global startup. The generated name will - be <literal>zend_ginit_<module></literal> (for example, - <literal>zend_ginit_first_module</literal>). Use in - conjunction with <literal>ZEND_GINIT_FUNCTION</literal>. - </entry> - </row> - <row> - <entry colname="col1"><literal>ZEND_GSHUTDOWN(module)</literal></entry> - <entry colname="col2"> - Declares a function for global shutdown. The generated name - will be <literal>zend_gshutdown_<module></literal> (for - example, <literal>zend_gshutdown_first_module</literal>). Use - in conjunction with <literal>ZEND_GSHUTDOWN_FUNCTION</literal>. - </entry> - </row> - <row> - <entry colname="col1"><literal>ZEND_MINFO(module)</literal></entry> - <entry colname="col2"> - Declares a function for printing module information, used when - <function>phpinfo</function> is called. The generated name will - be <literal>zend_info_<module></literal> (for example, - <literal>zend_info_first_module</literal>). Use in conjunction - with <literal>ZEND_MINFO_FUNCTION</literal>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </figure> -</section> - -<section id="zend.structure.get-module"> -<title>Creation of <function>get_module</function></title> -<para>This function is special to all dynamic loadable modules. Take a look at -the creation via the <literal>ZEND_GET_MODULE</literal> macro first: -<programlisting>#if COMPILE_DL_FIRSTMOD -ZEND_GET_MODULE(firstmod) -#endif</programlisting>The function implementation is surrounded by a conditional -compilation statement. This is needed since the function -<function>get_module</function> is only required if your module is built -as a dynamic extension. By specifying a definition of -<literal>COMPILE_DL_FIRSTMOD</literal> in the compiler command (see above for a -discussion of the compilation instructions required to build a dynamic -extension), you can instruct your module whether you intend to build it as -a dynamic extension or as a built-in module. If you want a built-in module, -the implementation of <function>get_module</function> is simply left -out.</para> -<para><function>get_module</function> is called by Zend at load time -of the module. You can think of it as being invoked by the -<function>dl</function> call in your script. Its purpose is to pass the -module information block back to Zend in order to inform the engine about the -module contents.</para> -<para>If you don't implement a <function>get_module</function> function in -your dynamic loadable module, Zend will compliment you with an error message -when trying to access it.</para> -</section> -<section id="zend.structure.implementation"> -<title>Implementation of All Exported Functions</title> -<para>Implementing the exported functions is the final step. The -example function in <literal>first_module</literal> looks like this: -<programlisting>ZEND_FUNCTION(first_module) + <entry colname="col2"> + Declares a function for module shutdown. The generated name + will be <literal>zend_mshutdown_<module></literal> (for + example, <literal>zend_mshutdown_first_module</literal>). Use + in conjunction with <literal>ZEND_MSHUTDOWN_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_RINIT(module)</literal></entry> + <entry colname="col2"> + Declares a function for request startup. The generated name + will be <literal>zend_rinit_<module></literal> (for + example, <literal>zend_rinit_first_module</literal>). Use in + conjunction with <literal>ZEND_RINIT_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_RSHUTDOWN(module)</literal></entry> + <entry colname="col2"> + Declares a function for request shutdown. The generated name + will be <literal>zend_rshutdown_<module></literal> (for + example, <literal>zend_rshutdown_first_module</literal>). Use + in conjunction with <literal>ZEND_RSHUTDOWN_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_GINIT(module)</literal></entry> + <entry colname="col2"> + Declares a function for global startup. The generated name will + be <literal>zend_ginit_<module></literal> (for example, + <literal>zend_ginit_first_module</literal>). Use in + conjunction with <literal>ZEND_GINIT_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_GSHUTDOWN(module)</literal></entry> + <entry colname="col2"> + Declares a function for global shutdown. The generated name + will be <literal>zend_gshutdown_<module></literal> (for + example, <literal>zend_gshutdown_first_module</literal>). Use + in conjunction with <literal>ZEND_GSHUTDOWN_FUNCTION</literal>. + </entry> + </row> + <row> + <entry colname="col1"><literal>ZEND_MINFO(module)</literal></entry> + <entry colname="col2"> + Declares a function for printing module information, used when + <function>phpinfo</function> is called. The generated name will + be <literal>zend_info_<module></literal> (for example, + <literal>zend_info_first_module</literal>). Use in conjunction + with <literal>ZEND_MINFO_FUNCTION</literal>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + </section> + + <section id="zend.structure.get-module"> + <title>Creation of <function>get_module</function></title> + <para> + This function is special to all dynamic loadable modules. Take a + look at the creation via the <literal>ZEND_GET_MODULE</literal> + macro first: + </para> + <programlisting> +#if COMPILE_DL_FIRSTMOD + ZEND_GET_MODULE(firstmod) +#endif + </programlisting> + <para> + The function implementation is surrounded by a conditional + compilation statement. This is needed since the function + <function>get_module</function> is only required if your module is + built as a dynamic extension. By specifying a definition of + <literal>COMPILE_DL_FIRSTMOD</literal> in the compiler command + (see above for a discussion of the compilation instructions + required to build a dynamic extension), you can instruct your + module whether you intend to build it as a dynamic extension or as + a built-in module. If you want a built-in module, the + implementation of <function>get_module</function> is simply left + out. + </para> + <para> + <function>get_module</function> is called by Zend at load time + of the module. You can think of it as being invoked by the + <function>dl</function> call in your script. Its purpose is to pass the + module information block back to Zend in order to inform the engine about the + module contents. + </para> + <para> + If you don't implement a <function>get_module</function> function in + your dynamic loadable module, Zend will compliment you with an error message + when trying to access it. + </para> + </section> + <section id="zend.structure.implementation"> + <title>Implementation of All Exported Functions</title> + <para>Implementing the exported functions is the final step. The + example function in <literal>first_module</literal> looks like this: + <programlisting> +ZEND_FUNCTION(first_module) { long parameter; @@ -579,26 +697,53 @@ } RETURN_LONG(parameter); -}</programlisting>The function declaration is done -using <literal>ZEND_FUNCTION</literal>, which corresponds -to <literal>ZEND_FE</literal> in the function entry table (discussed -earlier).</para> -<para>After the declaration, code for checking and retrieving the function's -arguments, argument conversion, and return value generation follows (more on -this later).</para> -</section> -<section id="zend.structure.summary"> -<title>Summary</title> -<para>That's it, basically - there's nothing more to implementing PHP modules. -Built-in modules are structured similarly to dynamic modules, so, equipped -with the information presented in the previous sections, you'll be able to -fight the odds when encountering PHP module source files.</para> -<para>Now, in the following sections, read on about how to make use of PHP's -internals to build powerful extensions.</para> -</section> -</chapter> +} + </programlisting> + The function declaration is done + using <literal>ZEND_FUNCTION</literal>, which corresponds + to <literal>ZEND_FE</literal> in the function entry table (discussed + earlier). + </para> + <para> + After the declaration, code for checking and retrieving the function's + arguments, argument conversion, and return value generation follows (more on + this later). + </para> + </section> + + <section id="zend.structure.summary"> + <title>Summary</title> + <para> + That's it, basically - there's nothing more to implementing PHP modules. + Built-in modules are structured similarly to dynamic modules, so, equipped + with the information presented in the previous sections, you'll be able to + fight the odds when encountering PHP module source files. + </para> + <para> + Now, in the following sections, read on about how to make use of PHP's + internals to build powerful extensions. + </para> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_Troubleshooting.xml diff -u ZendAPI/Extending_Zend_Troubleshooting.xml:1.4 ZendAPI/Extending_Zend_Troubleshooting.xml:1.5 --- ZendAPI/Extending_Zend_Troubleshooting.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Troubleshooting.xml Mon Feb 11 05:10:33 2002 @@ -1,28 +1,52 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.troubleshooting"> -<title>Troubleshooting</title> -<para>Actually, not much troubleshooting can be done when compiling static or -dynamic modules. The only problem that could arise is that the compiler will -complain about missing definitions or something similar. In this case, make sure that all -header files are available and that you specified their path correctly in the -compilation command. To be sure that everything is located correctly, -extract a clean PHP source tree and use the automatic build in the -<filename>ext</filename> directory with the fresh files from the CD-ROM; this -will guarantee a safe compilation environment. If this fails, try manual -compilation.</para> -<para>PHP might also complain about missing functions in your -module. (This shouldn't happen with the sample sources if you didn't modify them.) If the names of external -functions you're trying to access from your module are misspelled, they'll remain as -"unlinked symbols" in the symbol table. During dynamic loading and linkage by -PHP, they won't resolve because of the typing errors - there are no -corresponding symbols in the main binary. Look for incorrect declarations in -your module file or incorrectly written external references. Note that this -problem is specific to dynamic loadable modules; it doesn't occur with static -modules. Errors in static modules show up at compile time.</para> -</chapter> +  + <chapter id="zend.troubleshooting"> + <title>Troubleshooting</title> + <para> + Actually, not much troubleshooting can be done when compiling + static or dynamic modules. The only problem that could arise is + that the compiler will complain about missing definitions or + something similar. In this case, make sure that all header files + are available and that you specified their path correctly in the + compilation command. To be sure that everything is located + correctly, extract a clean PHP source tree and use the automatic + build in the <filename>ext</filename> directory with the fresh + files from the CD-ROM; this will guarantee a safe compilation + environment. If this fails, try manual compilation. + </para> + <para> + PHP might also complain about missing functions in your module. + (This shouldn't happen with the sample sources if you didn't modify + them.) If the names of external functions you're trying to access + from your module are misspelled, they'll remain as "unlinked + symbols" in the symbol table. During dynamic loading and linkage by + PHP, they won't resolve because of the typing errors - there are no + corresponding symbols in the main binary. Look for incorrect + declarations in your module file or incorrectly written external + references. Note that this problem is specific to dynamic loadable + modules; it doesn't occur with static modules. Errors in static + modules show up at compile time. + </para> + </chapter>  + Index: ZendAPI/Extending_Zend_Using.xml diff -u ZendAPI/Extending_Zend_Using.xml:1.5 ZendAPI/Extending_Zend_Using.xml:1.6 --- ZendAPI/Extending_Zend_Using.xml:1.5 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Using.xml Mon Feb 11 05:10:33 2002 @@ -1,51 +1,85 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.using"> -<title>Using Extensions</title> -<para>Depending on the build process you selected, you should either end up -with a new PHP binary to be linked into your Web server (or run as CGI), or with an .so (shared object) file. If you compiled the -example file <filename>first_module.c</filename> as a shared object, your result file -should be <filename>first_module.so</filename>. To use it, you first have to copy -it to a place from which it's accessible to PHP. For a simple test procedure, -you can copy it to your <filename>htdocs</filename> directory and try it with -the source in Listing 9.4. If you compiled it into the PHP binary, -omit the call to <function>dl</function>, as the module's -functionality is instantly available to your scripts. -<warning> -<para>For security reasons, you <emphasis>should not</emphasis> put your -dynamic modules into publicly accessible directories. Even though it <emphasis>can</emphasis> be -done and it simplifies testing, you should put them into a separate directory -in production environments.</para> -</warning></para> -<figure> -<title>Listing 9.4. A test file for first_module.so.</title> -<programlisting><?php - -//dl("first_module.so"); +  + <chapter id="zend.using"> + <title>Using Extensions</title> + <para> + Depending on the build process you selected, you should either end up + with a new PHP binary to be linked into your Web server (or run as CGI), or with an .so (shared object) file. If you compiled the + example file <filename>first_module.c</filename> as a shared object, your result file + should be <filename>first_module.so</filename>. To use it, you first have to copy + it to a place from which it's accessible to PHP. For a simple test procedure, + you can copy it to your <filename>htdocs</filename> directory and try it with + the source in Listing 9.4. If you compiled it into the PHP binary, + omit the call to <function>dl</function>, as the module's + functionality is instantly available to your scripts. + <warning> + <para> + For security reasons, you <emphasis>should not</emphasis> put your + dynamic modules into publicly accessible directories. Even though it <emphasis>can</emphasis> be + done and it simplifies testing, you should put them into a separate directory + in production environments. + </para> + </warning> + </para> + <figure> + <title>Listing 9.4. A test file for first_module.so.</title> + <programlisting role='php'> +<![CDATA[ +<?php + +// remove next comment if necessary +// dl("first_module.so"); $param = 2; $return = first_module($param); -print("We sent \"$param\" and got \"$return\""); +print("We sent '$param' and got '$return'"); -?></programlisting> -</figure> -<para>Calling this PHP file in your Web browser should give you the -output shown in Figure 9.3. -<figure> -<title>Figure 9.3. Output of first_module.php.</title><graphic fileref="figures/Extending_Zend_2_firstmod_output.png"/> -</figure></para> -<para>If required, the dynamic loadable module is loaded by calling -the <function>dl</function> function. This function looks for the specified -shared object, loads it, and makes its functions available to PHP. The module -exports the function <function>first_module</function>, which accepts a single -parameter, converts it to an integer, and returns the result of the -conversion.</para> -<para>If you've gotten this far, congratulations! You just built your first -extension to PHP.</para> -</chapter> +?> +]]> + </programlisting> + </figure> + <para> + Calling this PHP file in your Web browser should give you the + output shown in Figure 9.3. + <figure> + <title>Figure 9.3. Output of first_module.php.</title> + <graphic fileref="figures/Extending_Zend_2_firstmod_output.png"/> + </figure> + </para> + <para> + If required, the dynamic loadable module is loaded by calling the + <function>dl</function> function. This function looks for the + specified shared object, loads it, and makes its functions + available to PHP. The module exports the function + <function>first_module</function>, which accepts a single + parameter, converts it to an integer, and returns the result of the + conversion. + </para> + <para> + If you've gotten this far, congratulations! You just built your + first extension to PHP. + </para> + </chapter>  + Index: ZendAPI/Extending_Zend_Variables.xml diff -u ZendAPI/Extending_Zend_Variables.xml:1.6 ZendAPI/Extending_Zend_Variables.xml:1.7 --- ZendAPI/Extending_Zend_Variables.xml:1.6 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_Variables.xml Mon Feb 11 05:10:33 2002 @@ -1,53 +1,75 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.variables"> -<title>Creating Variables</title> -<para>When exchanging data from your own -extensions with PHP scripts, one of the most important issues is the creation of variables. This section shows you how to deal with the variable types that PHP -supports.</para> -<section id="zend.variables.overview"> -<title>Overview</title> -<para>To create new variables that can be seen "from the outside" by the -executing script, you need to allocate a new <envar>zval</envar> container, -fill this container with meaningful values, and then introduce it to Zend's -internal symbol table. This basic process is common to all variable creations: -<programlisting>zval *new_variable; +  + <chapter id="zend.variables"> + <title>Creating Variables</title> + <para> + When exchanging data from your own extensions with PHP scripts, one + of the most important issues is the creation of variables. This + section shows you how to deal with the variable types that PHP + supports. + </para> + <section id="zend.variables.overview"> + <title>Overview</title> + <para> + To create new variables that can be seen "from the outside" by the + executing script, you need to allocate a new <envar>zval</envar> + container, fill this container with meaningful values, and then + introduce it to Zend's internal symbol table. This basic process + is common to all variable creations: + </para> + <programlisting> +zval *new_variable; /* allocate and initialize new container */ -MAKE_STD_ZVAL(new_variable); +MAKE_STD_ZVAL(new_variable); -/* set type and variable contents here, see the following sections */ +/* set type and variable contents here, see the following sections */ /* introduce this variable by the name "new_variable_name" into the symbol table */ -ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); +ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); -/* the variable is now accessible to the script by using $new_variable_name */</programlisting>The macro <literal>MAKE_STD_ZVAL</literal> allocates a new <envar>zval</envar> container using -<literal>ALLOC_ZVAL</literal> and initializes it using -<literal>INIT_ZVAL</literal>. As implemented -in Zend at the time of this writing, <emphasis>initializing</emphasis> means setting the reference count to -<literal>1</literal> and clearing the <envar>is_ref</envar> flag, but this process could be -extended later - this is why it's a good idea to keep using -<literal>MAKE_STD_ZVAL</literal> instead of only using -<literal>ALLOC_ZVAL</literal>. If you want to optimize for speed -(and you don't have to explicitly initialize the -<envar>zval</envar> container here), you can use <literal>ALLOC_ZVAL</literal>, -but this isn't recommended because it doesn't ensure data integrity.</para> -<para><literal>ZEND_SET_SYMBOL</literal> takes care of introducing the -new variable to Zend's symbol table. This macro checks whether the value already exists in the symbol table and converts the new symbol to a -reference if so (with automatic deallocation of the old -<envar>zval</envar> container). This is the preferred method if speed is not a -crucial issue and you'd like to keep memory usage low.</para> -<para>Note that <literal>ZEND_SET_SYMBOL</literal> makes use of the Zend -executor globals via the macro <literal>EG</literal>. By -specifying <literal>EG(active_symbol_table)</literal>, you get access to the -currently active symbol table, dealing with the active, local scope. The local -scope may differ depending on whether the function was invoked from -within a function.</para> -<para>If you need to optimize for speed and don't care about optimal memory -usage, you can omit the check for an existing variable with the same value and instead -force insertion into the symbol table by using -<function>zend_hash_update</function>: -<programlisting>zval *new_variable; +/* the variable is now accessible to the script by using $new_variable_name */ + </programlisting> + <para> + The macro <literal>MAKE_STD_ZVAL</literal> allocates a new + <envar>zval</envar> container using <literal>ALLOC_ZVAL</literal> + and initializes it using <literal>INIT_ZVAL</literal>. As + implemented in Zend at the time of this writing, + <emphasis>initializing</emphasis> means setting the reference + count to <literal>1</literal> and clearing the + <envar>is_ref</envar> flag, but this process could be extended + later - this is why it's a good idea to keep using + <literal>MAKE_STD_ZVAL</literal> instead of only using + <literal>ALLOC_ZVAL</literal>. If you want to optimize for speed + (and you don't have to explicitly initialize the + <envar>zval</envar> container here), you can use + <literal>ALLOC_ZVAL</literal>, but this isn't recommended because + it doesn't ensure data integrity. + </para> + <para> + <literal>ZEND_SET_SYMBOL</literal> takes care of introducing the + new variable to Zend's symbol table. This macro checks whether the + value already exists in the symbol table and converts the new + symbol to a reference if so (with automatic deallocation of the + old <envar>zval</envar> container). This is the preferred method + if speed is not a crucial issue and you'd like to keep memory + usage low. + </para> + <para> + Note that <literal>ZEND_SET_SYMBOL</literal> makes use of the Zend + executor globals via the macro <literal>EG</literal>. By + specifying <literal>EG(active_symbol_table)</literal>, you get access to the + currently active symbol table, dealing with the active, local scope. The local + scope may differ depending on whether the function was invoked from + within a function. + </para> + <para> + If you need to optimize for speed and don't care about optimal memory + usage, you can omit the check for an existing variable with the same value and instead + force insertion into the symbol table by using + <function>zend_hash_update</function>: + <programlisting> +zval *new_variable; /* allocate and initialize new container */ MAKE_STD_ZVAL(new_variable); @@ -62,14 +84,18 @@ &new_variable, sizeof(zval *), NULL -);</programlisting>This is actually the standard method used in most -modules.</para> -<para>The variables generated with the snippet above will always be of local -scope, so they reside in the context in which the function has been called. To -create new variables in the global scope, use the same method -but refer to another symbol table: -<programlisting>zval *new_variable; - +); + </programlisting> + This is actually the standard method used in most modules. + </para> + <para> + The variables generated with the snippet above will always be of local + scope, so they reside in the context in which the function has been called. To + create new variables in the global scope, use the same method + but refer to another symbol table: + <programlisting> +zval *new_variable; + // allocate and initialize new container MAKE_STD_ZVAL(new_variable); @@ -78,16 +104,25 @@ // // introduce this variable by the name "new_variable_name" into the global symbol table -ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name", new_variable);</programlisting>The macro <literal>ZEND_SET_SYMBOL</literal> is now being -called with a reference to the main, global symbol table by referring -<literal>EG(symbol_table)</literal>.</para><para><emphasis>Note:</emphasis> The <envar>active_symbol_table</envar> variable is a -pointer, but <envar>symbol_table</envar> is not. This is why you have -to use <literal>EG(active_symbol_table)</literal> and <literal>&EG(symbol_table)</literal> -as parameters to <literal>ZEND_SET_SYMBOL</literal> - it requires a -pointer.</para> -<para>Similarly, to get a more efficient version, you can hardcode the -symbol table update: -<programlisting>zval *new_variable; +ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name", new_variable); + </programlisting> + The macro <literal>ZEND_SET_SYMBOL</literal> is now being + called with a reference to the main, global symbol table by referring + <literal>EG(symbol_table)</literal>. + </para> + <para> + <emphasis>Note:</emphasis> The <envar>active_symbol_table</envar> + variable is a pointer, but <envar>symbol_table</envar> is not. + This is why you have to use + <literal>EG(active_symbol_table)</literal> and + <literal>&EG(symbol_table)</literal> as parameters to + <literal>ZEND_SET_SYMBOL</literal> - it requires a pointer. + </para> + <para> + Similarly, to get a more efficient version, you can hardcode the + symbol table update: + <programlisting> +zval *new_variable; // allocate and initialize new container MAKE_STD_ZVAL(new_variable); @@ -104,16 +139,22 @@ &new_variable, sizeof(zval *), NULL -);</programlisting>Listing 9.10 shows a sample source that -creates two variables - <envar>local_variable</envar> with a local scope -and <envar>global_variable</envar> with a global scope (see Figure 9.7). The full example can be -found on the CD-ROM.</para><para>Note: You can see that the global variable is actually not accessible from -within the function. This is because it's not imported into the local scope -using <literal>global $global_variable;</literal> in the PHP source. -</para> -<figure> -<title>Listing 9.10. Creating variables with different scopes.</title> -<programlisting>ZEND_FUNCTION(variable_creation) +); + </programlisting> + Listing 9.10 shows a sample source that + creates two variables - <envar>local_variable</envar> with a local scope + and <envar>global_variable</envar> with a global scope (see Figure 9.7). + The full example can be found on the CD-ROM. + </para> + <para> + Note: You can see that the global variable is actually not accessible from + within the function. This is because it's not imported into the local scope + using <literal>global $global_variable;</literal> in the PHP source. + </para> + <figure> + <title>Listing 9.10. Creating variables with different scopes.</title> + <programlisting> +ZEND_FUNCTION(variable_creation) { zval *new_var1, *new_var2; @@ -128,294 +169,376 @@ RETURN_NULL(); -}</programlisting><graphic fileref="figures/Extending_Zend_6_variable_creation.png"/> -</figure> -</section> -<section id="zend.variables.long"> -<title>Longs (Integers)</title> -<para>Now let's get to the assignment of data to variables, starting with -longs. Longs are PHP's integers and are very simple to store. Looking at -the <envar>zval.value</envar> container structure discussed earlier in this -chapter, you can see that the long data type is directly contained in the union, -namely in the <envar>lval</envar> field. The -corresponding <envar>type</envar> value for longs is <literal>IS_LONG</literal> (see Listing 9.11). -<figure> -<title>Listing 9.11. Creation of a long.</title> -<programlisting>zval *new_long; +} + </programlisting> + <graphic fileref="figures/Extending_Zend_6_variable_creation.png"/> + </figure> + </section> + <section id="zend.variables.long"> + <title>Longs (Integers)</title> + <para>Now let's get to the assignment of data to variables, starting with + longs. Longs are PHP's integers and are very simple to store. Looking at + the <envar>zval.value</envar> container structure discussed earlier in this + chapter, you can see that the long data type is directly contained in the union, + namely in the <envar>lval</envar> field. The corresponding + <envar>type</envar> value for longs is <literal>IS_LONG</literal> + (see Listing 9.11). + <figure> + <title>Listing 9.11. Creation of a long.</title> + <programlisting> +zval *new_long; MAKE_STD_ZVAL(new_long); new_long->type = IS_LONG; -new_long->value.lval = 10;</programlisting> -</figure>Alternatively, you can use the macro <literal>ZVAL_LONG</literal>:<programlisting>zval *new_long; +new_long->value.lval = 10; + </programlisting> + </figure> + Alternatively, you can use the macro <literal>ZVAL_LONG</literal>: + <programlisting> +zval *new_long; MAKE_STD_ZVAL(new_long); -ZVAL_LONG(new_long, 10);</programlisting></para> -</section> -<section id="zend.variables.float"> -<title>Doubles (Floats)</title> -<para>Doubles are PHP's floats and are as easy to assign as longs, because their value -is also contained directly in the union. The member in the -<envar>zval.value</envar> container is <envar>dval</envar>; the corresponding -type is <literal>IS_DOUBLE</literal>. -<programlisting>zval *new_double; +ZVAL_LONG(new_long, 10); + </programlisting> + </para> + </section> + <section id="zend.variables.float"> + <title>Doubles (Floats)</title> + <para> + Doubles are PHP's floats and are as easy to assign as longs, because their value + is also contained directly in the union. The member in the + <envar>zval.value</envar> container is <envar>dval</envar>; + the corresponding type is <literal>IS_DOUBLE</literal>. + <programlisting> +zval *new_double; MAKE_STD_ZVAL(new_double); new_double->type = IS_DOUBLE; -new_double->value.dval = 3.45;</programlisting>Alternatively, you can use the -macro <literal>ZVAL_DOUBLE</literal>:<programlisting>zval *new_double; +new_double->value.dval = 3.45; + </programlisting> + Alternatively, you can use the macro <literal>ZVAL_DOUBLE</literal>: + <programlisting> +zval *new_double; MAKE_STD_ZVAL(new_double); -ZVAL_DOUBLE(new_double, 3.45);</programlisting></para> -</section> -<section id="zend.variables.string"> -<title>Strings</title> -<para>Strings need slightly more effort. As mentioned earlier, all strings -that will be associated with Zend's internal data structures need to be -allocated using Zend's own memory-management functions. Referencing of static -strings or strings allocated with standard routines is not allowed. To assign -strings, you have to access the structure <envar>str</envar> in -the <envar>zval.value</envar> container. The corresponding type -is <literal>IS_STRING</literal>:<programlisting>zval *new_string; +ZVAL_DOUBLE(new_double, 3.45); + </programlisting> + </para> + </section> + <section id="zend.variables.string"> + <title>Strings</title> + <para> + Strings need slightly more effort. As mentioned earlier, all strings + that will be associated with Zend's internal data structures need to be + allocated using Zend's own memory-management functions. Referencing of static + strings or strings allocated with standard routines is not allowed. To assign + strings, you have to access the structure <envar>str</envar> in + the <envar>zval.value</envar> container. The corresponding type + is <literal>IS_STRING</literal>: +<programlisting> +zval *new_string; char *string_contents = "This is a new string variable"; MAKE_STD_ZVAL(new_string); new_string->type = IS_STRING; new_string->value.str.len = strlen(string_contents); -new_string->value.str.val = estrdup(string_contents);</programlisting>Note the usage of Zend's <function>estrdup</function> here. -Of course, you can also use the predefined macro -<literal>ZVAL_STRING</literal>:<programlisting>zval *new_string; +new_string->value.str.val = estrdup(string_contents); + </programlisting> + Note the usage of Zend's <function>estrdup</function> here. + Of course, you can also use the predefined macro + <literal>ZVAL_STRING</literal>: + <programlisting> +zval *new_string; char *string_contents = "This is a new string variable"; MAKE_STD_ZVAL(new_string); -ZVAL_STRING(new_string, string_contents, 1);</programlisting><literal>ZVAL_STRING</literal> accepts a third parameter that -indicates whether the supplied string contents should be duplicated (using -<function>estrdup</function>). Setting this parameter -to <literal>1</literal> causes the string to be -duplicated; <literal>0</literal> simply uses the supplied pointer for the -variable contents. This is most useful if you want to create a new variable -referring to a string that's already allocated in Zend internal memory.</para> -<para>If you want to truncate the string at a certain -position or you already know its length, you can use <literal>ZVAL_STRINGL(zval, string, length, -duplicate)</literal>, which accepts an explicit string length to be -set for the new string. This macro is faster than -<literal>ZVAL_STRING</literal> and also binary-safe.</para> -<para>To create empty strings, set the string length to <literal>0</literal> and -use <literal>empty_string</literal> as contents: -<programlisting>new_string->type = IS_STRING; +ZVAL_STRING(new_string, string_contents, 1); + </programlisting> + <literal>ZVAL_STRING</literal> accepts a third parameter that + indicates whether the supplied string contents should be duplicated (using + <function>estrdup</function>). Setting this parameter + to <literal>1</literal> causes the string to be + duplicated; <literal>0</literal> simply uses the supplied pointer for the + variable contents. This is most useful if you want to create a new variable + referring to a string that's already allocated in Zend internal memory. + </para> + <para> + If you want to truncate the string at a certain position or you + already know its length, you can use <literal>ZVAL_STRINGL(zval, + string, length, duplicate)</literal>, which accepts an explicit + string length to be set for the new string. This macro is faster + than <literal>ZVAL_STRING</literal> and also binary-safe. + </para> + <para> + To create empty strings, set the string length to <literal>0</literal> and + use <literal>empty_string</literal> as contents: + <programlisting> +new_string->type = IS_STRING; new_string->value.str.len = 0; -new_string->value.str.val = empty_string;</programlisting>Of course, there's a macro for this as -well (<literal>ZVAL_EMPTY_STRING</literal>):<programlisting>MAKE_STD_ZVAL(new_string); -ZVAL_EMPTY_STRING(new_string);</programlisting></para> -</section> -<section id="zend.variables.boolean"> -<title>Booleans</title> -<para>Booleans are created just like longs, but have the -type <literal>IS_BOOL</literal>. Allowed values in -<envar>lval</envar> are <literal>0</literal> and <literal>1</literal>:<programlisting>zval *new_bool; +new_string->value.str.val = empty_string; + </programlisting> + Of course, there's a macro for this as + well (<literal>ZVAL_EMPTY_STRING</literal>): + <programlisting> +MAKE_STD_ZVAL(new_string); +ZVAL_EMPTY_STRING(new_string); + </programlisting> + </para> + </section> + <section id="zend.variables.boolean"> + <title>Booleans</title> + <para> + Booleans are created just like longs, but have the + type <literal>IS_BOOL</literal>. Allowed values in + <envar>lval</envar> are <literal>0</literal> and <literal>1</literal>: + <programlisting> +zval *new_bool; MAKE_STD_ZVAL(new_bool); new_bool->type = IS_BOOL; -new_bool->value.lval = 1;</programlisting>The corresponding macros for this type -are <literal>ZVAL_BOOL</literal> (allowing specification of the value) as well -as <literal>ZVAL_TRUE</literal> and <literal>ZVAL_FALSE</literal> (which -explicitly set the value to <literal>TRUE</literal> and <literal>FALSE</literal>, -respectively).</para> -</section> -<section id="zend.variables.array"> -<title>Arrays</title> -<para>Arrays are stored using Zend's internal hash tables, which can be -accessed using the <function>zend_hash_*</function> API. For every array that -you want to create, you need a new hash table handle, which will be -stored in the <envar>ht</envar> member of -the <envar>zval.value</envar> container.</para> -<para>There's a whole API solely for the creation of arrays, which is extremely -handy. To start a new array, you call -<function>array_init</function>. -<programlisting>zval *new_array; +new_bool->value.lval = 1; + </programlisting> + The corresponding macros for this type + are <literal>ZVAL_BOOL</literal> (allowing specification of the value) as well + as <literal>ZVAL_TRUE</literal> and <literal>ZVAL_FALSE</literal> (which + explicitly set the value to <literal>TRUE</literal> and <literal>FALSE</literal>, + respectively). + </para> + </section> + <section id="zend.variables.array"> + <title>Arrays</title> + <para> + Arrays are stored using Zend's internal hash tables, which can be + accessed using the <function>zend_hash_*</function> API. For every + array that you want to create, you need a new hash table handle, + which will be stored in the <envar>ht</envar> member of the + <envar>zval.value</envar> container. + </para> + <para> + There's a whole API solely for the creation of arrays, which is extremely + handy. To start a new array, you call + <function>array_init</function>. + <programlisting> +zval *new_array; MAKE_STD_ZVAL(new_array); if(array_init(new_array) != SUCCESS) { // do error handling here -}</programlisting>If <function>array_init</function> fails to create a -new array, it returns <literal>FAILURE</literal>.</para> -<para>To add new elements to the array, you can use numerous functions, -depending on what you want to do. Tables 9.8, 9.9, and 9.10 describe these functions. All functions return <literal>FAILURE</literal> on failure -and <literal>SUCCESS</literal> on success.</para> -<figure> -<title>Table 9.8. Zend's API for Associative Arrays</title> -<programlisting>Note: The functions in Table 9.8 all operate on the array "array" with the key "key". The key string doesn't have to reside in Zend internal memory; it will be duplicated by the API.</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Function</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_long(zval *array, char *key, long -n);</function></entry> -<entry colname="col2">Adds an element of type <literal>long</literal>.</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_unset(zval *array, char -*key);</function></entry> -<entry colname="col2">Adds an unset element.</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_bool(zval *array, char *key, int -b);</function></entry> -<entry colname="col2">Adds a Boolean element.</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_resource(zval *array, char *key, int -r);</function></entry> -<entry colname="col2">Adds a resource to the array.</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_double(zval *array, char *key, double -d);</function></entry> -<entry colname="col2">Adds a floating-point value.</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_string(zval *array, char *key, char -*str, int duplicate);</function></entry> -<entry colname="col2">Adds a string to the array. The -flag <envar>duplicate</envar> specifies whether the string contents have to be -copied to Zend internal memory.</entry> -</row> -<row> -<entry colname="col1"><function>add_assoc_stringl(zval *array, char *key, char -*str, uint length, int duplicate);</function></entry> -<entry colname="col2">Adds a string with the desired -length <envar>length</envar> to the array. Otherwise, behaves -like <function>add_assoc_string</function>.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<figure> -<title>Table 9.9. Zend's API for Indexed Arrays, Part 1</title> -<programlisting>Note: The functions in Table 9.9 all operate on the array "array" with the index "idx". -The index is always an integer.</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Function</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><function>add_index_long(zval *array, uint idx, long -n);</function></entry> -<entry colname="col2">Adds an element of type <literal>long</literal>.</entry> -</row> -<row> -<entry colname="col1"><function>add_index_unset(zval *array, uint -idx);</function></entry> -<entry colname="col2">Adds an unset element.</entry> -</row> -<row> -<entry colname="col1"><function>add_index_bool(zval *array, uint idx, int -b);</function></entry> -<entry colname="col2">Adds a Boolean element.</entry> -</row> -<row> -<entry colname="col1"><function>add_index_resource(zval *array, uint idx, int -r);</function></entry> -<entry colname="col2">Adds a resource to the array.</entry> -</row> -<row> -<entry colname="col1"><function>add_index_double(zval *array, uint idx, double -d);</function></entry> -<entry colname="col2">Adds a floating-point value.</entry> -</row> -<row> -<entry colname="col1"><function>add_index_string(zval *array, uint idx, char -*str, int duplicate);</function></entry> -<entry colname="col2">Adds a string to the array. The -flag <envar>duplicate</envar> specifies whether the string contents have to be -copied to Zend internal memory.</entry> -</row> -<row> -<entry colname="col1"><function>add_index_stringl(zval *array, uint idx, char -*str, uint length, int duplicate);</function></entry> -<entry colname="col2">Adds a string with the desired -length <envar>length</envar> to the array. This function is faster and binary-safe. Otherwise, behaves like <function>add_index_string()</function>.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<figure> -<title>Table 9.10. Zend's API for Indexed Arrays, Part 2</title> -<programlisting>Note: The functions in Table 9.10 all operate on the array "array". -These functions automatically generate a new index based on the highest index found in the array.</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Function</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_long(zval *array, long -n);</function></entry> -<entry colname="col2">Adds an element of type <literal>long</literal>.</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_unset(zval -*array);</function></entry> -<entry colname="col2">Adds an unset element.</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_bool(zval *array, int -b);</function></entry> -<entry colname="col2">Adds a Boolean element.</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_resource(zval *array, int -r);</function></entry> -<entry colname="col2">Adds a resource to the array.</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_double(zval *array, double -d);</function></entry> -<entry colname="col2">Adds a floating-point value.</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_string(zval *array, char *str, -int duplicate);</function></entry> -<entry colname="col2">Adds a string to the array. The -flag <envar>duplicate</envar> specifies whether the string contents have to be -copied to Zend internal memory.</entry> -</row> -<row> -<entry colname="col1"><function>add_next_index_stringl(zval *array, char *str, -uint length, int duplicate);</function></entry> -<entry colname="col2">Adds a string with the desired -length <envar>length</envar> to the array. This function is faster and binary-safe. Otherwise, behaves like <function>add_index_string()</function>.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -<para>All these functions provide a handy abstraction to Zend's internal hash -API. Of course, you can also use the hash functions directly - for example, if -you already have a <envar>zval</envar> container allocated that you want to insert into an array. This is done using <function>zend_hash_update()</function> for -associative arrays (see Listing 9.12) and <function>zend_hash_index_update</function> for -indexed arrays (see Listing 9.13): -<figure> -<title>Listing 9.12. Adding an element to an associative array.</title> -<programlisting>zval *new_array, *new_element; +} +</programlisting> + If <function>array_init</function> fails to create a + new array, it returns <literal>FAILURE</literal>. + </para> + <para> + To add new elements to the array, you can use numerous functions, + depending on what you want to do. Tables 9.8, 9.9, and 9.10 + describe these functions. All functions return + <literal>FAILURE</literal> on failure and + <literal>SUCCESS</literal> on success. + </para> + <figure> + <title>Table 9.8. Zend's API for Associative Arrays</title> + <programlisting> +Note: The functions in Table 9.8 all operate on the array "array" with the key "key". +The key string doesn't have to reside in Zend internal memory; it will be duplicated by the API. + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Function</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"> + <function>add_assoc_long(zval *array, char *key, long n);</function> + </entry> + <entry colname="col2">Adds an element of type <literal>long</literal>.</entry> + </row> + <row> + <entry colname="col1"> + <function>add_assoc_unset(zval *array, char *key);</function></entry> + <entry colname="col2">Adds an unset element.</entry> + </row> + <row> + <entry colname="col1"> + <function>add_assoc_bool(zval *array, char *key, int b);</function> + </entry> + <entry colname="col2">Adds a Boolean element.</entry> + </row> + <row> + <entry colname="col1"> + <function>add_assoc_resource(zval *array, char *key, int r);</function> + </entry> + <entry colname="col2">Adds a resource to the array.</entry> + </row> + <row> + <entry colname="col1"> + <function>add_assoc_double(zval *array, char *key, double d);</function> + </entry> + <entry colname="col2">Adds a floating-point value.</entry> + </row> + <row> + <entry colname="col1"> + <function>add_assoc_string(zval *array, char *key, char *str, int duplicate);</function> + </entry> + <entry colname="col2"> + Adds a string to the array. The + flag <envar>duplicate</envar> specifies whether the string contents have to be + copied to Zend internal memory. + </entry> + </row> + <row> + <entry colname="col1"> + <function> + add_assoc_stringl(zval *array, char *key, char *str, uint length, int duplicate); + </function> + </entry> + <entry colname="col2"> + Adds a string with the desired length <envar>length</envar> + to the array. Otherwise, behaves like + <function>add_assoc_string</function>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <figure> + <title>Table 9.9. Zend's API for Indexed Arrays, Part 1</title> + <programlisting> +Note: The functions in Table 9.9 all operate on the array "array" with the index "idx". +The index is always an integer. + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Function</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><function>add_index_long(zval *array, uint idx, long + n);</function></entry> + <entry colname="col2">Adds an element of type <literal>long</literal>.</entry> + </row> + <row> + <entry colname="col1"><function>add_index_unset(zval *array, uint + idx);</function></entry> + <entry colname="col2">Adds an unset element.</entry> + </row> + <row> + <entry colname="col1"><function>add_index_bool(zval *array, uint idx, int + b);</function></entry> + <entry colname="col2">Adds a Boolean element.</entry> + </row> + <row> + <entry colname="col1"><function>add_index_resource(zval *array, uint idx, int + r);</function></entry> + <entry colname="col2">Adds a resource to the array.</entry> + </row> + <row> + <entry colname="col1"><function>add_index_double(zval *array, uint idx, double + d);</function></entry> + <entry colname="col2">Adds a floating-point value.</entry> + </row> + <row> + <entry colname="col1"><function>add_index_string(zval *array, uint idx, char + *str, int duplicate);</function></entry> + <entry colname="col2">Adds a string to the array. The + flag <envar>duplicate</envar> specifies whether the string contents have to be + copied to Zend internal memory.</entry> + </row> + <row> + <entry colname="col1"><function>add_index_stringl(zval *array, uint idx, char + *str, uint length, int duplicate);</function></entry> + <entry colname="col2">Adds a string with the desired + length <envar>length</envar> to the array. This function is faster and binary-safe. Otherwise, behaves like <function>add_index_string()</function>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <figure> + <title>Table 9.10. Zend's API for Indexed Arrays, Part 2</title> + <programlisting> +Note: The functions in Table 9.10 all operate on the array "array". +These functions automatically generate a new index based on the highest index found in the array. + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Function</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_long(zval *array, long + n);</function></entry> + <entry colname="col2">Adds an element of type <literal>long</literal>.</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_unset(zval + *array);</function></entry> + <entry colname="col2">Adds an unset element.</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_bool(zval *array, int + b);</function></entry> + <entry colname="col2">Adds a Boolean element.</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_resource(zval *array, int + r);</function></entry> + <entry colname="col2">Adds a resource to the array.</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_double(zval *array, double + d);</function></entry> + <entry colname="col2">Adds a floating-point value.</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_string(zval *array, char *str, + int duplicate);</function></entry> + <entry colname="col2">Adds a string to the array. The + flag <envar>duplicate</envar> specifies whether the string contents have to be + copied to Zend internal memory.</entry> + </row> + <row> + <entry colname="col1"><function>add_next_index_stringl(zval *array, char *str, + uint length, int duplicate);</function></entry> + <entry colname="col2">Adds a string with the desired + length <envar>length</envar> to the array. This function is faster and binary-safe. Otherwise, behaves like <function>add_index_string()</function>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + <para> + All these functions provide a handy abstraction to Zend's internal hash + API. Of course, you can also use the hash functions directly - for example, if + you already have a <envar>zval</envar> container allocated that you want to + insert into an array. This is done using <function>zend_hash_update()</function> + for associative arrays (see Listing 9.12) and + <function>zend_hash_index_update</function> for indexed arrays (see Listing 9.13): + <figure> + <title>Listing 9.12. Adding an element to an associative array.</title> + <programlisting> +zval *new_array, *new_element; char *key = "element_key"; - + MAKE_STD_ZVAL(new_array); MAKE_STD_ZVAL(new_element); @@ -429,11 +552,13 @@ if(zend_hash_update(new_array->value.ht, key, strlen(key) + 1, (void *)&new_element, sizeof(zval *), NULL) == FAILURE) { // do error handling here -}</programlisting> -</figure> -<figure> -<title>Listing 9.13. Adding an element to an indexed array.</title> -<programlisting>zval *new_array, *new_element; +} + </programlisting> + </figure> + <figure> + <title>Listing 9.13. Adding an element to an indexed array.</title> + <programlisting> +zval *new_array, *new_element; int key = 2; MAKE_STD_ZVAL(new_array); @@ -449,103 +574,127 @@ if(zend_hash_index_update(new_array->value.ht, key, (void *)&new_element, sizeof(zval *), NULL) == FAILURE) { // do error handling here -}</programlisting> -</figure></para> -<para>To emulate the functionality of <function>add_next_index_*</function>, -you can use this:</para><programlisting>zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL)</programlisting> -<para><emphasis>Note:</emphasis> To return arrays from a function, use <function>array_init</function> and -all following actions on the predefined variable <envar>return_value</envar> -(given as argument to your exported function; see the earlier discussion of the call interface). You do not have to use -<literal>MAKE_STD_ZVAL</literal> on this.</para> -<para><emphasis>Tip:</emphasis> To avoid having to -write <literal>new_array->value.ht</literal> every time, you can -use <literal>HASH_OF(new_array)</literal>, which is also recommended for -compatibility and style reasons.</para> -</section> -<section id="zend.variables.object"> -<title>Objects</title> -<para>Since objects can be converted to arrays (and vice versa), you might have -already guessed that they have a lot of similarities to arrays in PHP. Objects are maintained with the same hash functions, but there's a different API for creating them.</para> -<para>To initialize an object, you use the -function <function>object_init</function>: -<programlisting>zval *new_object; +} + </programlisting> + </figure> + </para> + <para> + To emulate the functionality of + <function>add_next_index_*</function>, you can use this: + </para> + <programlisting> +zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL) + </programlisting> + <para> + <emphasis>Note:</emphasis> To return arrays from a function, use <function>array_init</function> and + all following actions on the predefined variable <envar>return_value</envar> + (given as argument to your exported function; see the earlier discussion of the call interface). You do not have to use + <literal>MAKE_STD_ZVAL</literal> on this. + </para> + <para> + <emphasis>Tip:</emphasis> To avoid having to + write <literal>new_array->value.ht</literal> every time, you can + use <literal>HASH_OF(new_array)</literal>, which is also recommended for + compatibility and style reasons. + </para> + </section> + <section id="zend.variables.object"> + <title>Objects</title> + <para> + Since objects can be converted to arrays (and vice versa), you + might have already guessed that they have a lot of similarities to + arrays in PHP. Objects are maintained with the same hash + functions, but there's a different API for creating them. + </para> + <para> + To initialize an object, you use the + function <function>object_init</function>: + <programlisting> +zval *new_object; MAKE_STD_ZVAL(new_object); if(object_init(new_object) != SUCCESS) { // do error handling here -}</programlisting>You can use the functions described in Table 9.11 to add -members to your object.</para> -<figure> -<title>Table 9.11. Zend's API for Object Creation</title> -<programlisting>Note: All functions in Table 9.11 work on the object "object" with the key "key". The key forms the member name, -so the resulting member can be accessed via $object->key.</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.24*"/><colspec colnum="2" colname="col2" colwidth="1.00*"/> -<tbody> -<row> -<entry colname="col1">Function</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><function>add_property_long(zval *object, char *key, long -l);</function></entry> -<entry colname="col2">Adds a long to the object.</entry> -</row> -<row> -<entry colname="col1"><function>add_property_unset(zval *object, char -*key);</function></entry> -<entry colname="col2">Adds an unset property to the object.</entry> -</row> -<row> -<entry colname="col1"><function>add_property_bool(zval *object, char *key, int -b);</function></entry> -<entry colname="col2">Adds a Boolean to the object.</entry> -</row> -<row> -<entry colname="col1"><function>add_property_resource(zval *object, char *key, -long r);</function></entry> -<entry colname="col2">Adds a resource to the object.</entry> -</row> -<row> -<entry colname="col1"><function>add_property_double(zval *object, char *key, -double d);</function></entry> -<entry colname="col2">Adds a double to the object.</entry> -</row> -<row> -<entry colname="col1"><function>add_property_string(zval *object, char *key, -char *str, int duplicate);</function></entry> -<entry colname="col2">Adds a string to the object.</entry> -</row> -<row> -<entry colname="col1"><function>add_property_stringl(zval *object, char *key, -char *str, uint length, int duplicate);</function></entry> -<entry colname="col2">Adds a string of the specified length to the object. This -function is faster than <function>add_property_string</function> and also -binary-safe.</entry> -</row> - - <row> - <entry colname="col1"> - <function>add_property_zval(zval *obect, char *key, zval *container):</function> - </entry> - <entry colname="col2"> - Adds a <literal>zval</literal> container to the object. This is useful if you - have to add properties which aren't simple types like integers or strings but - arrays or other objects. - </entry> - </row> - -</tbody> -</tgroup> -</informaltable> -</figure> -</section> - -<section id="zend.variables.resource"> - <title>Resources</title> - <para> +} + </programlisting> + You can use the functions described in Table 9.11 to add + members to your object. + </para> + <figure> + <title>Table 9.11. Zend's API for Object Creation</title> + <programlisting> + Note: All functions in Table 9.11 work on the object "object" with the key "key". The key forms the member name, + so the resulting member can be accessed via $object->key. + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.24*"/> + <colspec colnum="2" colname="col2" colwidth="1.00*"/> + <tbody> + <row> + <entry colname="col1">Function</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><function>add_property_long(zval *object, char *key, long + l);</function></entry> + <entry colname="col2">Adds a long to the object.</entry> + </row> + <row> + <entry colname="col1"><function>add_property_unset(zval *object, char + *key);</function></entry> + <entry colname="col2">Adds an unset property to the object.</entry> + </row> + <row> + <entry colname="col1"><function>add_property_bool(zval *object, char *key, int + b);</function></entry> + <entry colname="col2">Adds a Boolean to the object.</entry> + </row> + <row> + <entry colname="col1"><function>add_property_resource(zval *object, char *key, + long r);</function></entry> + <entry colname="col2">Adds a resource to the object.</entry> + </row> + <row> + <entry colname="col1"><function>add_property_double(zval *object, char *key, + double d);</function></entry> + <entry colname="col2">Adds a double to the object.</entry> + </row> + <row> + <entry colname="col1"><function>add_property_string(zval *object, char *key, + char *str, int duplicate);</function></entry> + <entry colname="col2">Adds a string to the object.</entry> + </row> + <row> + <entry colname="col1"><function>add_property_stringl(zval *object, char *key, + char *str, uint length, int duplicate);</function></entry> + <entry colname="col2">Adds a string of the specified length to the object. This + function is faster than <function>add_property_string</function> and also + binary-safe.</entry> + </row> + + <row> + <entry colname="col1"> + <function>add_property_zval(zval *obect, char *key, zval *container):</function> + </entry> + <entry colname="col2"> + Adds a <literal>zval</literal> container to the object. This is useful if you + have to add properties which aren't simple types like integers or strings but + arrays or other objects. + </entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </figure> + </section> + + <section id="zend.variables.resource"> + <title>Resources</title> + <para> Resources are a special kind of data type in PHP. The term <emphasis>resources</emphasis> doesn't really refer to any special kind of data, but to an abstraction method for maintaining any kind @@ -563,15 +712,15 @@ can be found in the MySQL module, but other modules such as the Oracle module also make use of resources. <note> - <para> - In fact, a resource can be a pointer to anything you need to - handle in your functions (e.g. pointer to a structure) and the - user only has to pass a single resource variable to your - function. - </para> + <para> + In fact, a resource can be a pointer to anything you need to + handle in your functions (e.g. pointer to a structure) and the + user only has to pass a single resource variable to your + function. + </para> </note> - </para> - <para> + </para> + <para> To create a new resource you need to register a resource destruction handler for it. Since you can store any kind of data as a resource, Zend needs to know how to free this resource if its not longer @@ -584,85 +733,93 @@ of time stored in a global static variable within your extension. There is no need to worry about thread safety here because you only register your resource handler once during module initialization. - </para> - <para> + </para> + <para> The Zend function to register your resource handler is defined as: - <programlisting>ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number); + <programlisting> +ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number); </programlisting> - </para> - <para> + </para> + <para> There are two different kinds of resource destruction handlers you can pass to this function: a handler for normal resources and a handler for persistent resources. Persistent resources are for example used for database connection. When registering a resource, either of these handlers must be given. For the other handler just pass <literal>NULL</literal>. - </para> - <para> + </para> + <para> <function>zend_register_list_destructors_ex</function> accepts the following parameters: <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="5.00*"/> - <tbody> - <row> - <entry colname="col1"><literal>ld</literal></entry> - <entry colname="col2">Normal resource destruction - handler callback</entry> - </row> - <row> - <entry colname="col1"><literal>pld</literal></entry> - <entry colname="col2">Pesistent resource destruction - handler callback</entry> - </row> - <row> - <entry colname="col1"><literal>type_name</literal></entry> - <entry colname="col2">A string specifying the name of - your resource. It's always a good thing to - specify an unique name within PHP for the resource type - so when the user for example calls - <literal>var_dump($resource);</literal> - he also gets the name of the resource.</entry> - </row> - <row> - <entry colname="col1"><literal>module_number</literal></entry> - <entry colname="col2">The <literal>module_number</literal> - is automatically available in your - <literal>PHP_MINIT_FUNCTION</literal> - function and therefore you just pass it over.</entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="5.00*"/> + <tbody> + <row> + <entry colname="col1"><literal>ld</literal></entry> + <entry colname="col2">Normal resource destruction + handler callback</entry> + </row> + <row> + <entry colname="col1"><literal>pld</literal></entry> + <entry colname="col2">Pesistent resource destruction + handler callback</entry> + </row> + <row> + <entry colname="col1"><literal>type_name</literal></entry> + <entry colname="col2">A string specifying the name of + your resource. It's always a good thing to + specify an unique name within PHP for the resource type + so when the user for example calls + <literal>var_dump($resource);</literal> + he also gets the name of the resource.</entry> + </row> + <row> + <entry colname="col1"><literal>module_number</literal></entry> + <entry colname="col2">The <literal>module_number</literal> + is automatically available in your + <literal>PHP_MINIT_FUNCTION</literal> + function and therefore you just pass it over.</entry> + </row> + </tbody> + </tgroup> </informaltable> The return value is an unique integer ID for your <emphasis role="strong">resource type</emphasis>. - </para> - <para> + </para> + <para> The resource destruction handler (either normal or persistent resources) has the following prototype: <programlisting>void resource_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC);</programlisting> The passed <literal>rsrc</literal> is a pointer to the following structure: - <programlisting>typedef struct _zend_rsrc_list_entry { - + <programlisting> +typedef struct _zend_rsrc_list_entry { + void *ptr; int type; int refcount; -} zend_rsrc_list_entry;</programlisting> +} zend_rsrc_list_entry; + </programlisting> The member <literal>void *ptr</literal> is the actual pointer to your resource. - </para> - <para> + </para> + <para> Now we know how to start things, we define our own resource we want register within Zend. It is only a simple structure with two integer members: - <programlisting>typedef struct { - + <programlisting> +typedef struct { + int resource_link; int resource_type; -} my_resource;</programlisting> +} my_resource; + </programlisting> Our resource destruction handler is probably going to look something like this: - <programlisting>void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) { + <programlisting> +void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) { // You most likely cast the void pointer to your structure type @@ -673,27 +830,31 @@ // Also, don't forget to actually free the memory for your resource too! do_whatever_needs_to_be_done_with_the_resource(my_rsrc); -}</programlisting> - <note><para>One important thing to mention: If your resource +} + </programlisting> + <note> + <para>One important thing to mention: If your resource is a rather complex structure which also contains pointers to memory you allocated during runtime you have to free them <emphasis role="strong">before</emphasis> freeing - the resource itself!</para></note> - </para> - <para> + the resource itself! + </para> + </note> + </para> + <para> Now that we have defined <orderedlist> - <listitem><para>what our resource is and</para></listitem> - <listitem><para>our resource destruction handler</para></listitem> + <listitem><para>what our resource is and</para></listitem> + <listitem><para>our resource destruction handler</para></listitem> </orderedlist> we can go on and do the rest of the steps: <orderedlist> - <listitem><para>create a global variable within the extension holding - the resource ID so it can be accessed from every function - which needs it</para></listitem> - <listitem><para>define the resource name</para></listitem> - <listitem><para>write the resource destruction handler</para></listitem> - <listitem><para>and finally register the handler</para></listitem> + <listitem><para>create a global variable within the extension holding + the resource ID so it can be accessed from every function + which needs it</para></listitem> + <listitem><para>define the resource name</para></listitem> + <listitem><para>write the resource destruction handler</para></listitem> + <listitem><para>and finally register the handler</para></listitem> </orderedlist> <programlisting> // Somewhere in your extension, define the variable for your registered resources. @@ -723,62 +884,71 @@ // You can register additional resources, initialize // your global vars, constants, whatever. - }</programlisting> - </para> - <para> + } + </programlisting> + </para> + <para> To actually register a new resource you use can either use the <function>zend_register_resource</function> function or the <function>ZEND_REGISTER_RESOURE</function> macro, both defined in zend_list.h . Although the arguments for both map 1:1 it's a good idea to always use macros to be upwards compatible: - <programlisting> int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type);</programlisting> + <programlisting> +int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type); + </programlisting> <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="5.00*"/> - <tbody> - <row> - <entry colname="col1"><literal>rsrc_result</literal></entry> - <entry colname="col2">This is an already initialized - <literal>zval *</literal> container.</entry> - </row> - <row> - <entry colname="col1"><literal>rsrc_pointer</literal></entry> - <entry colname="col2">Your resource pointer you want to - store.</entry> - </row> - <row> - <entry colname="col1"><literal>rsrc_type</literal></entry> - <entry colname="col2">The type which you received when - you registered the resource destruction handler. If you - followed the naming scheme this would be - <literal>le_myresource</literal>.</entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="5.00*"/> + <tbody> + <row> + <entry colname="col1"><literal>rsrc_result</literal></entry> + <entry colname="col2">This is an already initialized + <literal>zval *</literal> container.</entry> + </row> + <row> + <entry colname="col1"><literal>rsrc_pointer</literal></entry> + <entry colname="col2">Your resource pointer you want to + store.</entry> + </row> + <row> + <entry colname="col1"><literal>rsrc_type</literal></entry> + <entry colname="col2">The type which you received when + you registered the resource destruction handler. If you + followed the naming scheme this would be + <literal>le_myresource</literal>.</entry> + </row> + </tbody> + </tgroup> </informaltable> The return value is an unique integer identifier for that resource. - </para> - <para> + </para> + <para> What is really going on when you register a new resource is it gets inserted in an internal list in Zend and the result is just stored in the given <literal>zval *</literal> container: - <programlisting> rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type); - + <programlisting> + rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type); + if (rsrc_result) { rsrc_result->value.lval = rsrc_id; rsrc_result->type = IS_RESOURCE; } - return rsrc_id;</programlisting> - The returned <literal>rsrc_id</literal> uniquly identifies the newly - registered resource. You can use the macro - <literal>RETURN_RESOURE</literal> to return it to the user: - <programlisting> RETURN_RESOURCE(rsrc_id)</programlisting> - <note><para>It is common practice that if you want to return the resource - immidiately to the user you specify the <literal>return_value</literal> - as the <literal>zval *</literal> container.</para></note> - </para> - <para> + return rsrc_id; + </programlisting> + The returned <literal>rsrc_id</literal> uniquly identifies the newly + registered resource. You can use the macro + <literal>RETURN_RESOURE</literal> to return it to the user: + <programlisting> RETURN_RESOURCE(rsrc_id)</programlisting> + <note><para>It is common practice that if you want to return the resource + immidiately to the user you specify the <literal>return_value</literal> + as the <literal>zval *</literal> container. + </para> + </note> + </para> + <para> Zend now keeps track of all references to this resource. As soon as all references to the resource are lost, the destructor that you previously registered for this resource is called. The nice thing @@ -787,56 +957,60 @@ allocations that your calling script will refer to as resources. As soon as the script decides it doesn't need them anymore, Zend will find out and tell you. - </para> - <para> + </para> + <para> Now that the user got his resource, at some point he is passing it back to one of your functions. The <envar>value.lval</envar> inside the <literal>zval *</literal> container contains the key to your resource and thus can be used to fetch the resource with the following macro: <literal>ZEND_FETCH_RESOURCE</literal>: - <programlisting> ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type)</programlisting> + <programlisting> +ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type) +</programlisting> <informaltable> - <tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="5.00*"/> - <tbody> - <row> - <entry colname="col1"><literal>rsrc</literal></entry> - <entry colname="col2">This is your pointer which will - point to your previously registered resource.</entry> - </row> - <row> - <entry colname="col1"><literal>rsrc_type</literal></entry> - <entry colname="col2">This is the typecast argument for - your pointer, e.g. <literal>myresource *</literal>.</entry> - </row> - <row> - <entry colname="col1"><literal>rsrc_id</literal></entry> - <entry colname="col2">This is the address of the - <literal>zval *</literal>container the user passed to - your function, e.g. <literal>&z_resource</literal> if - <literal>zval *z_resource</literal> is given.</entry> - </row> - <row> - <entry colname="col1"><literal>default_rsrc_id</literal></entry> - <entry colname="col2">This integer specifies the default - resource <literal>ID</literal> if no resource could be fetched - or -1.</entry> - </row> - <row> - <entry colname="col1"><literal>resource_type_name</literal></entry> - <entry colname="col2">This is the name of the requested resource. - It's a string and is used when the resource can't be - found or is invalid to form a meaningful error - message.</entry> - </row> - <row> - <entry colname="col1"><literal>resource_type</literal></entry> - <entry colname="col2">The <literal>resource_type</literal> - you got back when registering the resource destruction handler. - In our example this was <envar>le_myresource</envar>.</entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.00*"/> + <colspec colnum="2" colname="col2" colwidth="5.00*"/> + <tbody> + <row> + <entry colname="col1"><literal>rsrc</literal></entry> + <entry colname="col2">This is your pointer which will + point to your previously registered resource.</entry> + </row> + <row> + <entry colname="col1"><literal>rsrc_type</literal></entry> + <entry colname="col2">This is the typecast argument for + your pointer, e.g. <literal>myresource *</literal>.</entry> + </row> + <row> + <entry colname="col1"><literal>rsrc_id</literal></entry> + <entry colname="col2">This is the address of the + <literal>zval *</literal>container the user passed to + your function, e.g. <literal>&z_resource</literal> if + <literal>zval *z_resource</literal> is given.</entry> + </row> + <row> + <entry colname="col1"><literal>default_rsrc_id</literal></entry> + <entry colname="col2">This integer specifies the default + resource <literal>ID</literal> if no resource could be fetched + or -1.</entry> + </row> + <row> + <entry colname="col1"><literal>resource_type_name</literal></entry> + <entry colname="col2">This is the name of the requested resource. + It's a string and is used when the resource can't be + found or is invalid to form a meaningful error + message.</entry> + </row> + <row> + <entry colname="col1"><literal>resource_type</literal></entry> + <entry colname="col2">The <literal>resource_type</literal> + you got back when registering the resource destruction handler. + In our example this was <envar>le_myresource</envar>.</entry> + </row> + </tbody> + </tgroup> </informaltable> This macro has no return value. It is for the developers convenience and takes care @@ -845,8 +1019,8 @@ It throws a warning message and returns the current PHP function with <literal>NULL</literal> if there was a problem retrieving the resource. - </para> - <para> + </para> + <para> To force removal of a resource from the list, use the function <function>zend_list_delete</function>. You can also force the reference count to increase if you know that you're creating another @@ -856,124 +1030,164 @@ previously allocated resource entries, use <function>zend_list_find</function>. The complete API can be found in <filename>zend_list.h</filename>. - </para> -</section> + </para> + </section> -<section id="zend.variables.global"> -<title>Macros for Automatic Global Variable Creation</title> -<para>In addition to the macros discussed earlier, a few macros allow easy creation of simple global variables. These are nice to know in -case you want to introduce global flags, for example. This is somewhat bad -practice, but Table 9.12 describes macros that do exactly this -task. They don't need any <envar>zval</envar> allocation; you simply have -to supply a variable name and value.</para> -<figure> -<title>Table 9.12. Macros for Global Variable Creation</title> -<programlisting>Note: All macros in Table 9.12 create a global variable of the name "name" with the value "value".</programlisting> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"><literal>SET_VAR_STRING(name, value)</literal></entry> -<entry colname="col2">Creates a new string.</entry> -</row> -<row> -<entry colname="col1"><literal>SET_VAR_STRINGL(name, value, -length)</literal></entry> -<entry colname="col2">Creates a new string of the specified length. This macro -is faster than <literal>SET_VAR_STRING</literal> and also binary-safe.</entry> -</row> -<row> -<entry colname="col1"><literal>SET_VAR_LONG(name, value)</literal></entry> -<entry colname="col2">Creates a new long.</entry> -</row> -<row> -<entry colname="col1"><literal>SET_VAR_DOUBLE(name, value)</literal></entry> -<entry colname="col2">Creates a new double.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -</section> -<section id="zend.variables.constant"> -<title>Creating Constants</title> -<para>Zend supports the creation of true constants (as opposed to regular -variables). Constants are accessed without the typical dollar sign (<literal>$</literal>) prefix and are available in all scopes. Examples -include <literal>TRUE</literal> and <literal>FALSE</literal>, to name just -two.</para> -<para>To create your own constants, you can use the macros in Table 9.13. All the macros create a constant with the specified name and value.</para><para>You can also specify flags for each constant: -<itemizedlist> -<listitem> -<para><literal>CONST_CS</literal> - This constant's name is to be treated -as case sensitive.</para> -</listitem> -<listitem> -<para><literal>CONST_PERSISTENT</literal> - This constant is persistent and -won't be "forgotten" when the current process carrying this constant shuts -down.</para> -</listitem> -</itemizedlist>To use the flags, combine them using a -binary OR: -<programlisting>// register a new constant of type "long" -REGISTER_LONG_CONSTANT("NEW_MEANINGFUL_CONSTANT", 324, CONST_CS | CONST_PERSISTENT);</programlisting>There are two types of -macros - <literal>REGISTER_*_CONSTANT</literal> and<literal>REGISTER_MAIN_*_CONSTANT</literal>. -The first type creates constants bound to the current module. These -constants are dumped from the symbol table as soon as the module that -registered the constant is unloaded from memory. The second type creates constants that remain in the symbol table independently of the -module.</para> -<figure> -<title>Table 9.13. Macros for Creating Constants</title> -<informaltable> -<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.53*"/><colspec colnum="2" colname="col2" colwidth="1.00*"/> -<tbody> -<row> -<entry colname="col1">Macro</entry> -<entry colname="col2">Description</entry> -</row> -<row> -<entry colname="col1"> -<para><literal>REGISTER_LONG_CONSTANT(name, value, flags)</literal></para> -<para><literal>REGISTER_MAIN_LONG_CONSTANT(name, value, -flags)</literal></para></entry> -<entry colname="col2">Registers a new constant of type long.</entry> -</row> -<row> -<entry colname="col1"> -<para><literal>REGISTER_DOUBLE_CONSTANT(name, value, flags)</literal></para> -<para><literal>REGISTER_MAIN_DOUBLE_CONSTANT(name, value, -flags)</literal></para></entry> -<entry colname="col2">Registers a new constant of type double.</entry> -</row> -<row> -<entry colname="col1"> -<para><literal>REGISTER_STRING_CONSTANT(name, value, flags)</literal></para> -<para><literal>REGISTER_MAIN_STRING_CONSTANT(name, value, -flags)</literal></para></entry> -<entry colname="col2"> Registers a new constant of type string. The specified -string must reside in Zend's internal memory.</entry> -</row> -<row> -<entry colname="col1"> -<para><literal>REGISTER_STRINGL_CONSTANT(name, value, length, -flags)</literal></para> -<para><literal>REGISTER_MAIN_STRINGL_CONSTANT(name, value, length, -flags)</literal></para></entry> -<entry colname="col2">Registers a new constant of type string. The string length -is explicitly set to <envar>length</envar>. The specified string must reside -in Zend's internal memory.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</figure> -</section> -</chapter> + <section id="zend.variables.global"> + <title>Macros for Automatic Global Variable Creation</title> + <para> + In addition to the macros discussed earlier, a few macros allow + easy creation of simple global variables. These are nice to know + in case you want to introduce global flags, for example. This is + somewhat bad practice, but Table 9.12 describes macros that do + exactly this task. They don't need any <envar>zval</envar> + allocation; you simply have to supply a variable name and value. + </para> + <figure> + <title>Table 9.12. Macros for Global Variable Creation</title> + <programlisting> + Note: All macros in Table 9.12 create a global variable of the name "name" with the value "value". + </programlisting> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="*"/> + <colspec colnum="2" colname="col2" colwidth="*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"><literal>SET_VAR_STRING(name, value)</literal></entry> + <entry colname="col2">Creates a new string.</entry> + </row> + <row> + <entry colname="col1"><literal>SET_VAR_STRINGL(name, value, + length)</literal></entry> + <entry colname="col2">Creates a new string of the specified length. This macro + is faster than <literal>SET_VAR_STRING</literal> and also binary-safe.</entry> + </row> + <row> + <entry colname="col1"><literal>SET_VAR_LONG(name, value)</literal></entry> + <entry colname="col2">Creates a new long.</entry> + </row> + <row> + <entry colname="col1"><literal>SET_VAR_DOUBLE(name, value)</literal></entry> + <entry colname="col2">Creates a new double.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + </section> + <section id="zend.variables.constant"> + <title>Creating Constants</title> + <para> + Zend supports the creation of true constants (as opposed to + regular variables). Constants are accessed without the typical + dollar sign (<literal>$</literal>) prefix and are available in all + scopes. Examples include <literal>TRUE</literal> and + <literal>FALSE</literal>, to name just two. + </para> + <para> + To create your own constants, you can use the macros in Table 9.13. All the macros create a constant with the specified name and value. + </para> + <para> + You can also specify flags for each constant: + <itemizedlist> + <listitem> + <para> + <literal>CONST_CS</literal> - This constant's name is to be + treated as case sensitive. + </para> + </listitem> + <listitem> + <para> + <literal>CONST_PERSISTENT</literal> - This constant is + persistent and won't be "forgotten" when the current process + carrying this constant shuts down. + </para> + </listitem> + </itemizedlist> To use the flags, combine them using a inary OR: + <programlisting> // register a new constant of type "long" + REGISTER_LONG_CONSTANT("NEW_MEANINGFUL_CONSTANT", 324, CONST_CS | + CONST_PERSISTENT); </programlisting> There are two types of + macros - <literal>REGISTER_*_CONSTANT</literal> + and<literal>REGISTER_MAIN_*_CONSTANT</literal>. The first type + creates constants bound to the current module. These constants are + dumped from the symbol table as soon as the module that registered + the constant is unloaded from memory. The second type creates + constants that remain in the symbol table independently of the + module. + </para> + <figure> + <title>Table 9.13. Macros for Creating Constants</title> + <informaltable> + <tgroup cols="2"> + <colspec colnum="1" colname="col1" colwidth="1.53*"/> + <colspec colnum="2" colname="col2" colwidth="1.00*"/> + <tbody> + <row> + <entry colname="col1">Macro</entry> + <entry colname="col2">Description</entry> + </row> + <row> + <entry colname="col1"> + <literal>REGISTER_LONG_CONSTANT(name, value, flags)</literal> + <literal>REGISTER_MAIN_LONG_CONSTANT(name, value, flags)</literal> + </entry> + <entry colname="col2">Registers a new constant of type long.</entry> + </row> + <row> + <entry colname="col1"> + <literal>REGISTER_DOUBLE_CONSTANT(name, value, flags)</literal> + <literal>REGISTER_MAIN_DOUBLE_CONSTANT(name, value, flags)</literal> + </entry> + <entry colname="col2">Registers a new constant of type double.</entry> + </row> + <row> + <entry colname="col1"> + <literal>REGISTER_STRING_CONSTANT(name, value, flags)</literal> + <literal>REGISTER_MAIN_STRING_CONSTANT(name, value, flags)</literal> + </entry> + <entry colname="col2"> Registers a new constant of type string. The specified + string must reside in Zend's internal memory.</entry> + </row> + <row> + <entry colname="col1"> + <literal>REGISTER_STRINGL_CONSTANT(name, value, length, flags)</literal> + <literal>REGISTER_MAIN_STRINGL_CONSTANT(name, value, length, + flags)</literal> + </entry> + <entry colname="col2">Registers a new constant of type string. The string length + is explicitly set to <envar>length</envar>. The specified string must reside + in Zend's internal memory.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </figure> + </section> + </chapter>  + Index: ZendAPI/Extending_Zend_WhereToGo.xml diff -u ZendAPI/Extending_Zend_WhereToGo.xml:1.4 ZendAPI/Extending_Zend_WhereToGo.xml:1.5 --- ZendAPI/Extending_Zend_WhereToGo.xml:1.4 Fri Feb 8 12:02:46 2002 +++ ZendAPI/Extending_Zend_WhereToGo.xml Mon Feb 11 05:10:33 2002 @@ -1,24 +1,45 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -  -<chapter id="zend.where-to-go"> -<title>Where to Go from Here</title> -<para>You've learned a lot about PHP. You now know how to create -dynamic loadable modules and statically linked extensions. You've -learned how PHP and Zend deal with internal storage of variables and how you -can create and access these variables. You know quite a set of tool functions -that do a lot of routine tasks such as printing informational texts, -automatically introducing variables to the symbol table, and so on.</para> -<para>Even though this chapter often had a mostly "referential" character, we -hope that it gave you insight on how to start writing your own extensions. -For the sake of space, we had to leave out a lot; we suggest that you take the time to -study the header files and some modules (especially the ones in the -<filename>ext/standard</filename> directory and the MySQL module, as these -implement commonly known functionality). This will give you an idea of how -other people have used the API functions - particularly those that didn't make it into -this chapter.</para> -</chapter> +  + <chapter id="zend.where-to-go"> + <title>Where to Go from Here</title> + <para> + You've learned a lot about PHP. You now know how to create + dynamic loadable modules and statically linked extensions. You've + learned how PHP and Zend deal with internal storage of variables and how you + can create and access these variables. You know quite a set of tool functions + that do a lot of routine tasks such as printing informational texts, + automatically introducing variables to the symbol table, and so on. + </para> + <para> + Even though this chapter often had a mostly "referential" character, we + hope that it gave you insight on how to start writing your own extensions. + For the sake of space, we had to leave out a lot; we suggest that you take the time to + study the header files and some modules (especially the ones in the + <filename>ext/standard</filename> directory and the MySQL module, as these + implement commonly known functionality). This will give you an idea of how + other people have used the API functions - particularly those that didn't make it into + this chapter. + </para> + </chapter>  + Index: ZendAPI/manual.xml diff -u ZendAPI/manual.xml:1.8 ZendAPI/manual.xml:1.9 --- ZendAPI/manual.xml:1.8 Sat Jan 26 18:04:18 2002 +++ ZendAPI/manual.xml Mon Feb 11 05:10:33 2002 @@ -6,31 +6,49 @@ %zendapi.defs; ]> -<book id="zendapi" lang="en"> - &zendapi.toc; - <appendix id="zend.documentation-changes"> - <title>Documentation changes</title> - <para> - This appendix should reflect the major changes of the revisions of - this book so developers can reconstruct how the Zend API has - evolved over time. This may be in particular useful for developers - who are confronted with extensions (most probably external ones) - which have not yet been updated to the latest Zend API changes. - </para> - <para> - 2001.10.xx: A new approach on parsing the parameters passed to PHP functions - similar to the one used in Python has been introduced. The new API - greatly simplifies the process of receiving parameteres. The - ability to specify the type of parameter to parse results in less - typing and unified warnings messages (Andrei Zmievski, Markus Fischer). - </para> - <para> - 2001.12.01: The resource chapter has been rewritten for clarity and - verbosity (Markus Fischer). - </para> - <para> - 2002.01.09: Splitted the manual into one part per chapter (Derick - Rethans). - </para> - </appendix> +<book id="zendapi" lang="en"> + &zendapi.toc; + <appendix id="zend.documentation-changes"> + <title>Documentation changes</title> + <para> + This appendix should reflect the major changes of the revisions of + this book so developers can reconstruct how the Zend API has + evolved over time. This may be in particular useful for developers + who are confronted with extensions (most probably external ones) + which have not yet been updated to the latest Zend API changes. + </para> + <para> + 2001.10.xx: A new approach on parsing the parameters passed to PHP functions + similar to the one used in Python has been introduced. The new API + greatly simplifies the process of receiving parameteres. The + ability to specify the type of parameter to parse results in less + typing and unified warnings messages (Andrei Zmievski, Markus Fischer). + </para> + <para> + 2001.12.01: The resource chapter has been rewritten for clarity and + verbosity (Markus Fischer). + </para> + <para> + 2002.01.09: Splitted the manual into one part per chapter (Derick + Rethans). + </para> + </appendix> </book> + +