From cd0dd3d9b69fd0345f320c7c69b957df3968ecc0 Mon Sep 17 00:00:00 2001
From: Gwynne Raskind <gwynne@php.net>
Date: Mon, 8 Dec 2008 06:26:25 +0000
Subject: [PATCH] more lifecycle docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@270794 c90b9560-bf6c-de11-be94-00142212c4b1
---
 internals2/structure/lifecycle.xml | 132 ++++++++++++++++++++++++++++-
 1 file changed, 131 insertions(+), 1 deletion(-)

diff --git a/internals2/structure/lifecycle.xml b/internals2/structure/lifecycle.xml
index 8ecdc19c0c..a6df02d605 100644
--- a/internals2/structure/lifecycle.xml
+++ b/internals2/structure/lifecycle.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
  <sect1 xml:id="internals2.structure.lifecycle" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
   <title>Life cycle of an extension</title>
 
@@ -65,6 +65,136 @@
 
   </sect2>
 
+  <sect2 xml:id="internals2.structure.lifecycle.what-when">
+   <title>What to do, and when to do it</title>
+
+   <simpara>
+    There are many tasks that might be performed at any of these four points.
+    This table details where many common initialization and termination tasks
+    belong.
+   </simpara>
+   
+   <table>
+    <title>What to do, and when to do it</title>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>Module initialization/termination</entry>
+       <entry>Request initialization/termination</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>Allocate/deallocate and initialize module global variables</entry>
+       <entry>
+        Allocate/deallocate and initialize request-specific variables
+       </entry>
+      </row>
+      <row>
+       <entry>Register/unregister class entries</entry>
+       <entry></entry>
+      </row>
+      <row>
+       <entry>Register/unregister INI entries</entry>
+       <entry></entry>
+      </row>
+      <row>
+       <entry>Register constants</entry>
+       <entry></entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+  </sect2>
+
+  <sect2 xml:id="internals2.structure.lifecycle.info">
+   <title>The <function>phpinfo</function> callback</title>
+   
+   <simpara>
+    Aside from globals initialization and certain rarely-used callbacks, there
+    is one more part of a module's lifecycle to examine: A call to
+    <function>phpinfo</function>. The output a user sees from this call, whether
+    text or HTML or anything else, is generated by each individual extension
+    that is loaded into the PHP interpreter at the time the call is made.
+   </simpara>
+   
+   <simpara>
+    To provide for format-neutral output, the header
+    &quot;ext/standard/info.h&quot; provides an array of functions to produce
+    standardized display elements. Specifically, several functions which create
+    the familiar tables exist:
+   </simpara>
+   
+   <variablelist>
+    <varlistentry>
+     <term><function>php_info_print_table_start</function></term>
+     <listitem>
+      <simpara>
+       Open a table in <function>phpinfo</function> output. Takes no parameters.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><function>php_info_print_table_header</function></term>
+     <listitem>
+      <simpara>
+       Print a table header in <function>phpinfo</function> output. Takes one
+       parameter, the number of columns, plus the same number of
+       <type>char *</type> parameters which are the texts for each column
+       heading.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><function>php_info_print_table_row</function></term>
+     <listitem>
+      <simpara>
+       Print a table row in <function>phpinfo</function> output. Takes one
+       parameter, the number of columns, plus the same number of
+       <type>char *</type> parameters which are the texts for each column
+       content.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><function>php_info_print_table_end</function></term>
+     <listitem>
+      <simpara>
+       Close a table formerly opened by
+       <function>php_info_print_table_start</function>. Takes no parameters.
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+   
+   <simpara>
+    Using these four functions, it is possible to produce status information for
+    nearly any conbimation of features in an extension. Here is the information
+    callback from the counter extension:
+   </simpara>
+
+   <example xml:id="internals2.structure.lifecycle.info.counter">
+    <title>counter's PHP_MINFO function</title>
+    <programlisting role="c">
+<![CDATA[
+/* {{{ PHP_MINFO(counter) */
+PHP_MINFO_FUNCTION(counter)
+{
+    char        buf[10];
+
+    php_info_print_table_start();
+    php_info_print_table_row(2, "counter support", "enabled");
+    snprintf(buf, sizeof(buf), "%ld", COUNTER_G(basic_counter_value));
+    php_info_print_table_row(2, "Basic counter value", buf);
+    php_info_print_table_end();
+}
+/* }}} */
+]]>
+    </programlisting>
+   </example>
+  </sect2>
+
  </sect1>
 
 <!-- Keep this comment at the end of the file