From 2f8781979d3c9c917021fd8b7f15ead6ebc22519 Mon Sep 17 00:00:00 2001
From: Gwynne Raskind <gwynne@php.net>
Date: Sun, 9 Mar 2008 20:38:44 +0000
Subject: [PATCH] real-world example, need to backport this example to its own
 section for use throughout the docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@254717 c90b9560-bf6c-de11-be94-00142212c4b1
---
 internals2/structure/modstruct.xml | 95 +++++++++++++++++++++++++++++-
 1 file changed, 93 insertions(+), 2 deletions(-)

diff --git a/internals2/structure/modstruct.xml b/internals2/structure/modstruct.xml
index b5a8f131f3..7c0166cc6d 100644
--- a/internals2/structure/modstruct.xml
+++ b/internals2/structure/modstruct.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
  <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>
@@ -456,7 +456,98 @@ struct _zend_module_entry {
     </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
+    a &quot;real-world&quot; example extension. This extension provides a
+    counter that increases by one every time the function to get its current
+    value is called. The time at which the counter is reset is controlled by an
+    INI switch. This is useless in a practical sense, but serves to illustrate
+    many techniques for extension writing.
+   </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.
+     </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>
+      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>
+
  </sect1>
 
 <!-- Keep this comment at the end of the file