renamed extension-lifetime document to extension-callbacks

1 files changed, 133 insertions, 0 deletions

diff --git a/documentation/extension-callbacks.html b/documentation/extension-callbacks.html
new file mode 100644
index 0000000..5c93736
--- /dev/null
+++ b/documentation/extension-callbacks.html
@@ -0,0 +1,133 @@
+<h1>Extension callbacks</h1>
+<p>
+    As we <a href="loading-extension">explained before</a>, the get_module()
+    function is called when your extension is started. It returns a memory address 
+    where the Zend engine can find all relevant information about your extension.
+</p>
+<p>
+    After this get_module() call, your extension is loaded and will be used to handle
+    <i>multiple</i> pageviews. This is an important difference between standard
+    PHP scripts and native extensions, because standard PHP scripts handle only a single
+    pageview. But extensions serve multiple pageviews after each other.
+</p>
+<p>
+    This difference is especially important if you use global C++ variables. 
+    Such global variables are initialized when the extension is loaded - and not at 
+    the beginning of each pageview. Changes that you make to global variables keep 
+    their value, and subsequent requests will therefore see the updated values. 
+</p>
+<p>
+    This, by the way, only happens to <i>native</i> variables. Global PHP variables,
+    stored in the Php::GLOBALS object, are re-initialized at the beginning of 
+    each request. You do not have to worry about changes that you make to 
+    global PHP variables: at the beginning of the next request, the Php::GLOBALS
+    object is fresh and new, and the changes that you made during the
+    previous request are no longer visible.
+</p>
+<p>
+    Back to the global C++ variables. If you want to reset a global variable
+    at the beginning of a new request, you can register a special callback function 
+    that gets called in front of each request.
+</p>
+<p>
+<pre class="language-c++"><code>#include &lt;phpcpp.h&gt;
+
+/**
+ *  Global variable that stores the number of times 
+ *  the function updateCounters() has been called in total
+ *  @var    int
+ */
+int invokeTotalCount = 0;
+
+/**
+ *  Global variable that keeps track how many times the
+ *  function updateCounters() was called during the
+ *  current request
+ *  @var    int
+ */
+int invokeDuringRequestCount = 0;
+
+/**
+ *  Native function that is callable from PHP
+ *
+ *  This function updates a number of global variables that count
+ *  the number of times a function was called
+ */
+void updateCounters()
+{
+    // increment global counters
+    invokeTotalCount++;
+    invokeDuringRequestCount++;
+}
+
+/**
+ *  Switch to C context, because the Zend engine expects get get_module()
+ *  to have a C style function signature
+ */
+extern "C" {
+    /**
+     *  Startup function that is automatically called by the Zend engine
+     *  when PHP starts, and that should return the extension details
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() 
+    {
+        // the extension object
+        static Php::Extension extension("my_extension", "1.0");
+        
+        // install a callback that is called at the beginning 
+        // of each request
+        extension.onRequest([]() {
+            
+            // re-initialize the counter
+            invokeDuringRequestCount = 0;
+        });
+        
+        // add the updateCounter method to the extension
+        extension.add("updateCounters", updateCounters);
+        
+        // return the extension details
+        return extension;
+    }
+}</code></pre>
+</p>
+<p>
+    The Php::Extension class has a method onRequest() that is used in the
+    above example to register a callback function. This callback is called right 
+    before every pageview/request. And as you can see, it is 
+    permitted to use C++ lambda functions.
+</p>
+<p>
+    The onRequest() is not the only method in the Php::Extension object to
+    register a callback. There are in fact
+    four different on*() methods that you can use.
+</p>
+<p>
+    <ul>
+        <li>void onStartup(const std::function&lt;void()&gt; &callback);</li>
+        <li>void onRequest(const std::function&lt;void()&gt; &callback);</li>
+        <li>void onIdle(const std::function&lt;void()&gt; &callback);</li>
+        <li>void onShutdown(const std::function&lt;void()&gt; &callback);</li>
+    </ul>
+</p>
+<p>
+    The startup callback is called when the Zend engine has loaded your extension 
+    and all functions and classes in it were registered. If you want to initialize 
+    additional variables in your extension before the functions are going to get called, 
+    you can use the onStartup() function and register a callback to run this
+    initialization code.
+</p>
+<p>
+    After the Zend engine is initialized, it is ready to process requests. In the
+    example above we used the onRequest() method to register a callback that is
+    called in front of each request. Next to that, you can also install a callback that gets called
+    <i>after</i> each request, when the Zend engine moves to an idle state - waiting
+    for the next request. This can be accomplished with the onIdle()
+    method in the Php::Extension object.
+</p>
+<p>
+    The fourth callback that you can register is a callback that gets called 
+    right before PHP shuts down. If there is anything to clean up, you can install
+    such a callback and run the cleanup code from it.
+</p>
+    
\ No newline at end of file