<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297078 $ -->
 <sect1 xml:id="internals2.structure.modstruct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>The zend_module structure</title>
  <para>
   The main source file of a PHP extension contains several new constructs for
   a C programmer. The most important of these, the one touched first when
   starting a new extension, is the <literal>zend_module</literal> structure.
   This structure contains a wealth of information that tells the Zend Engine
   about the extension's dependencies, version, callbacks, and other critical
   data. The structure has mutated considerably over time; this section will
   focus on the structure as it has appeared since PHP 5.2, and will identify
   the very few parts which have changed in PHP 5.3.
  </para>
  
  <para>
   The <literal>zend_module</literal> declaration from
   <filename>counter.c</filename> looks like this before any code has been
   written. The example file was generated by
   <command>ext_skel --extname=counter</command>, with some obsolete constructs
   removed:
  </para>
  
  <example xml:id="internals2.structure.modstruct.example-decl">
   <title>zend_module declaration in the counter extension</title>
   <programlisting role="c">
<![CDATA[
/* {{{ counter_module_entry
 */
zend_module_entry counter_module_entry = {
    STANDARD_MODULE_HEADER,
    "counter",
    counter_functions,
    PHP_MINIT(counter),
    PHP_MSHUTDOWN(counter),
    PHP_RINIT(counter),        /* Replace with NULL if there's nothing to do at request start */
    PHP_RSHUTDOWN(counter),    /* Replace with NULL if there's nothing to do at request end */
    PHP_MINFO(counter),
    "0.1", /* Replace with version number for your extension */
    STANDARD_MODULE_PROPERTIES
};
/* }}} */
]]>
   </programlisting>
  </example>
  
  <para>
   This may look a bit daunting at first glance, but most of it is very simple
   to understand. Here's the declaration of <literal>zend_module</literal> from
   <filename>zend_modules.h</filename> in PHP 5.3:
  </para>
  
  <example xml:id="internals2.structure.modstruct.struct-defn">
   <title>zend_module definition in PHP 5.3</title>
   <programlisting role="c">
<![CDATA[
struct _zend_module_entry {
    unsigned short size;
    unsigned int zend_api;
    unsigned char zend_debug;
    unsigned char zts;
    const struct _zend_ini_entry *ini_entry;
    const struct _zend_module_dep *deps;
    const char *name;
    const struct _zend_function_entry *functions;
    int (*module_startup_func)(INIT_FUNC_ARGS);
    int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
    int (*request_startup_func)(INIT_FUNC_ARGS);
    int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);
    void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);
    const char *version;
    size_t globals_size;
#ifdef ZTS
    ts_rsrc_id* globals_id_ptr;
#else
    void* globals_ptr;
#endif
    void (*globals_ctor)(void *global TSRMLS_DC);
    void (*globals_dtor)(void *global TSRMLS_DC);
    int (*post_deactivate_func)(void);
    int module_started;
    unsigned char type;
    void *handle;
    int module_number;
};
]]>
   </programlisting>
  </example>
  
  <para>
   Many of these fields will never be touched by an extension writer. There are
   a number of standard macros that set them to their proper values
   automatically. The macro <constant>STANDARD_MODULE_HEADER</constant> fills in
   everything up to the <varname>deps</varname> field. Alternatively, the
   <constant>STANDARD_MODULE_HEADER_EX</constant> will leave the
   <varname>deps</varname> field empty for the developer's use. The developer is
   always responsible for everything from <varname>name</varname> to
   <varname>version</varname>. After that, the
   <constant>STANDARD_MODULE_PROPERTIES</constant> macro will fill in the rest
   of the structure, or the <constant>STANDARD_MODULE_PROPERTIES_EX</constant>
   macro can be used to leave the extension globals and post-deactivation
   function fields unfilled. Most modern extensions will make use of module
   globals.
  </para>
  
  <note>
   <para>
    This table gives the values that each field would have if the developer
    were to fill in the structure entirely by hand, without recourse to any of
    the shortcut macros. <emphasis>This is not recommended.</emphasis> The
    &quot;correct&quot; values for many fields may change. Use the macros
    whenever possible.
   </para>
  </note>

  <table xml:id="internals2.structure.modstruct.struct-values">
   <title>Module structure field values</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Field</entry>
      <entry>Value</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>

     <row>
      <entry>
       <varname>size</varname>
       <footnote xml:id="internals2.structure.modstruct.struct-values.not-for-dev">
        <para>
         This field is not intended for use by module developers.
        </para>
       </footnote>
       <footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMHE">
        <para>
         This field is filled in by <constant>STANDARD_MODULE_HEADER_EX</constant>.
        </para>
       </footnote>
       <footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMH">
        <para>
         This field is filled in by <constant>STANDARD_MODULE_HEADER</constant>.
        </para>
       </footnote>
      </entry>
      <entry><code>sizeof(zend_module_entry)</code></entry>
      <entry>
       The size in bytes of the structure.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>zend_api</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHE"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
      </entry>
      <entry><constant>ZEND_MODULE_API_NO</constant></entry>
      <entry>
       The version of the Zend API this module was compiled against.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>zend_debug</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHE"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
      </entry>
      <entry><constant>ZEND_DEBUG</constant></entry>
      <entry>
       A flag indicating whether the module was compiled with debugging turned
       on.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>zts</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMHE"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
      </entry>
      <entry><constant>USING_ZTS</constant></entry>
      <entry>
       A flag indicating whether the module was compiled with ZTS (TSRM) enabled
       (see <xref linkend="internals2.memory"/>).
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>ini_entry</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
      </entry>
      <entry>&null;</entry>
      <entry>
       This pointer is used internally by Zend to keep a non-local reference to
       any INI entries declared for the module.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>deps</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMH"/>
      </entry>
      <entry>&null;</entry>
      <entry>
       A pointer to a list of dependencies for the module.
      </entry>
     </row>

     <row>
      <entry>
       <varname>name</varname>
      </entry>
      <entry>&quot;mymodule&quot;</entry>
      <entry>
       The name of the module. This is the short name, such as &quot;spl&quot;
       or &quot;standard&quot;.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>functions</varname>
      </entry>
      <entry>mymodule_functions</entry>
      <entry>
       A pointer to the module's function table, which Zend uses to expose
       functions in the module to user space.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>module_startup_func</varname>
      </entry>
      <entry>PHP_MINIT(mymodule)</entry>
      <entry>
       A callback function that Zend will call the first time a module is loaded
       into a particular instance of PHP.
      </entry>
     </row>

     <row>
      <entry>
       <varname>module_shutdown_func</varname>
      </entry>
      <entry>PHP_MSHUTDOWN(mymodule)</entry>
      <entry>
       A callback function that Zend will call the when a module is unloaded
       from a particular instance of PHP, typically during final shutdown.
      </entry>
     </row>

     <row>
      <entry>
       <varname>request_startup_func</varname>
      </entry>
      <entry>PHP_RINIT(mymodule)</entry>
      <entry>
       A callback function that Zend will call at the beginning of each request.
      </entry>
     </row>

     <row>
      <entry>
       <varname>request_shutdown_func</varname>
      </entry>
      <entry>PHP_RSHUTDOWN(mymodule)</entry>
      <entry>
       A callback function that Zend will call at the end of each request.
      </entry>
     </row>

     <row>
      <entry>
       <varname>info_func</varname>
      </entry>
      <entry>PHP_MINFO(mymodule)</entry>
      <entry>
       A callback function that Zend will call when the <function>phpinfo</function>
       function is called.
      </entry>
     </row>

     <row>
      <entry>
       <varname>version</varname>
      </entry>
      <entry><constant>NO_VERSION_YET</constant></entry>
      <entry>
       A string giving the version of the module, as specified by the module
       developer. It is recommended that the version number be either in the
       format expected by version_compare() (e.g. &quot;1.0.5-dev&quot;), or a
       CVS or SVN revision number (e.g. &quot;$Rev: 297078 $&quot;).
      </entry>
     </row>

     <row>
      <entry>
       <varname>globals_size</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMP">
        <para>
         This field is filled in by <constant>STANDARD_MODULE_PROPERTIES</constant>.
        </para>
       </footnote>
       <footnote xml:id="internals2.structure.modstruct.struct-values.given-by-NMG">
        <para>
         This field is filled in by <constant>NO_MODULE_GLOBALS</constant>.
        </para>
       </footnote>
       <footnote xml:id="internals2.structure.modstruct.struct-values.given-by-PMG">
        <para>
         This field is filled in by <constant>PHP_MODULE_GLOBALS</constant>.
        </para>
       </footnote>
      </entry>
      <entry>sizeof(zend_mymodule_globals)</entry>
      <entry>
       The size of the data structure containing the module's globals, if any.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>globals_id_ptr</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
       <footnote xml:id="internals2.structure.modstruct.struct-values.only-with-ZTS">
        <para>
         This field only exists when <constant>USING_ZTS</constant> is &true;.
        </para>
       </footnote>
      </entry>
      <entry>&amp;mymodule_globals_id</entry>
      <entry morerows="1">
       Only one of these two fields will exist, depending upon whether the
       <constant>USING_ZTS</constant> constant is &true;. The former is an index
       into TSRM's allocation table for the module's globals, and the latter is
       a pointer directly to the globals.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>globals_ptr</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
       <footnote xml:id="internals2.structure.modstruct.struct-values.only-without-ZTS">
        <para>
         This field only exists when <constant>USING_ZTS</constant> is &false;.
        </para>
       </footnote>
      </entry>
      <entry>&amp;mymodule_globals</entry>
     </row>
     
     <row>
      <entry>
       <varname>globals_ctor</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
      </entry>
      <entry>PHP_GINIT(mymodule)</entry>
      <entry>
       This funtion is called to initialize a module's globals <emphasis>before</emphasis>
       any <varname>module_startup_func</varname>.
      </entry>
     </row>

     <row>
      <entry>
       <varname>globals_dtor</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-NMG"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-PMG"/>
      </entry>
      <entry>PHP_GSHUTDOWN(mymodule)</entry>
      <entry>
       This funtion is called to deallocate a module's globals <emphasis>after</emphasis>
       any <varname>module_shutdown_func</varname>.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>post_deactivate_func</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
      </entry>
      <entry>ZEND_MODULE_POST_ZEND_DEACTIVATE_N(mymodule)</entry>
      <entry>
       This function is called by Zend after request shutdown. It is rarely used.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>module_started</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnote xml:id="internals2.structure.modstruct.struct-values.given-by-SMPE">
        <para>
         This field is filled in by <constant>STANDARD_MODULE_PROPERTIES_EX</constant>.
        </para>
       </footnote>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
      </entry>
      <entry>0</entry>
      <entry morerows="3">
       These fields are used for Zend's internal tracking information.
      </entry>
     </row>
     
     <row>
      <entry>
       <varname>type</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMPE"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
      </entry>
      <entry>0</entry>
     </row>
     
     <row>
      <entry>
       <varname>handle</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMPE"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
      </entry>
      <entry>&null;</entry>
     </row>
    
     <row>
      <entry>
       <varname>module_number</varname>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.not-for-dev"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMPE"/>
       <footnoteref linkend="internals2.structure.modstruct.struct-values.given-by-SMP"/>
      </entry>
      <entry>0</entry>
     </row>

    </tbody>
   </tgroup>
  </table>

  <sect2 xml:id="internals2.structure.modstruct.filling-it-in">
   <title>Filling in the structure in a practical situation</title>

   <para>
    With all these fields to play with, it can be confusing to know which to use
    for what purpose. Here is the <literal>zend_module</literal> definition from
    the "counter" example extension after updating it to its final form.
   </para>
   
   <example xml:id="internals2.structure.modstruct.filling-it-in.counter-mod-ex">
    <title>Counter extension module definition</title>
    <programlisting role="c">
<![CDATA[
/* {{{ counter_module_entry
 */
zend_module_entry counter_module_entry = {
    STANDARD_MODULE_HEADER,
    "counter",
    counter_functions,
    PHP_MINIT(counter),
    PHP_MSHUTDOWN(counter),
    PHP_RINIT(counter),
    PHP_RSHUTDOWN(counter),
    PHP_MINFO(counter),
    NO_VERSION_YET,
    PHP_MODULE_GLOBALS(counter),
    PHP_GINIT(counter),
    PHP_GSHUTDOWN(counter),
    NULL,
    STANDARD_MODULE_PROPERTIES_EX
};
/* }}} */
]]>
    </programlisting>
   </example>
   
   <itemizedlist>
    <listitem>
     <simpara>
      <constant>STANDARD_MODULE_HEADER</constant> is used since this module
      doesn't define any dependencies.
     </simpara>
    </listitem>
    
    <listitem>
     <simpara>
      &quot;counter&quot; is the extension's name, and is used to define the
      various callback functions the module passes to Zend. "counter" uses
      module, globals, and request functions at startup and shutdown times, and
      provides information to <function>phpinfo</function>, so all seven
      callbacks are defined.
     </simpara>
    </listitem>
    
    <listitem>
     <simpara>
      It is assumed that there is a variable of type
      <type>zend_function_entry *</type> named
      <varname>counter_functions</varname> earlier in the file that contains
      the module definition, listing the functions the module exports to
      userspace.
     </simpara>
    </listitem>
    
    <listitem>
     <simpara>
      <constant>NO_VERSION_YET</constant> is a particularly nice way of telling
      Zend the module doesn't have a version. It might have been more correct to
      place <literal>&quot;1.0&quot;</literal> here instead in a real module.
     </simpara>
    </listitem>
    
    <listitem>
     <simpara>
      "counter" uses per-module globals, so
      <constant>PHP_MODULE_GLOBALS</constant> is used
     </simpara>
    </listitem>
    
    <listitem>
     <simpara>
      This module has no post-deactivate function, so &null; is used.
     </simpara>
    </listitem>
    
    <listitem>
     <simpara>
      Since this module <emphasis>does</emphasis> use globals,
      <constant>STANDARD_MODULE_PROPERTIES_EX</constant> is used to finish the
      structure.
     </simpara>
    </listitem>
   
   </itemizedlist>

  </sect2>

  <sect2 xml:id="internals2.structure.modstruct.php53">
   <title>What's changed between 5.2 and 5.3?</title>
   
   <simpara>
    Nothing. The only differences in the <literal>zend_module</literal>
    structure between PHP 5.2 and PHP 5.3 are a few <modifier>const</modifier>
    keywords.
   </simpara>

  </sect2>

 </sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->