documentation/extension-lifetime.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

<h1>The lifetime of an extension</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, so
    that your functions and classes can be seen from PHP scripts.
</p>
<p>
    After this get_module() call, your extension is loaded and will be used to handle
    <i>multiple pageviews</i>. This is an important difference between standard
    PHP scripts and native extensions, because standard PHP scripts handle only a single
    pageview. Extension can be used to serve multiple pageviews after 
    each other.
</p>
<p>
    This difference is especially important when you use global variables. 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 see the updated value. If you do not want this, 
    you can register callback functions that get called in front of each
    request and right after each request. In these callback you can then 
    re-initialize the global variables.
</p>
<p>
<pre class="language-c++"><code>#include &lt;phpcpp.h&gt;
#include &lt;iostream&gt;

/**
 *  Global value that keeps track of the number 
 *  of requests that have been handled
 *  @var    int
 */
int requestCount = 0;

/**
 *  Global value that stores the number of times 
 *  the function updateCounters() has been called in total
 *  @var    int
 */
int invokeTotalCount = 0;

/**
 *  Global value 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 function that is called when the PHP engine
        // is fully initialized
        extension.onReady([]() {
            
            // set global variables to their initial values
            requestCount = 0;
            invokeTotalCount = 0;
        });
        
        // install a callback that is called at the beginning of each
        // request
        extension.onRequest([]() {
            
            // re-initialize the counter
            invokeDuringRequestCount = 0;
        });
        
        // install a callback that is called after each request
        extension.onCleanup([]() {
            
            // @todo add your own implementation
            
        });
        
        // install a callback that is called when the Zend engine
        // is closing down
        extension.onFinalize([]() {
            
            // @todo add your own implementation
        });
        
        // return the extension details
        return extension;
    }
}</code></pre>
</p>