summaryrefslogtreecommitdiff
path: root/include/extension.h
blob: fcc0f7279c13dbc86edd7c6c84d99357170e4aa7 (plain)
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
/**
 *  Extension.h
 *
 *  The extension class is the starting point of your PHP extension. This class
 *  is instantiated the moment the PHP engine starts - for example when the
 *  apache process starts - and will be used for all subsequent requests that
 *  are handled by Apache.
 *
 *  For some environments (for example CLI scripts and CGI calls) only one 
 *  request is handled by an extension instance, but for others (when PHP runs
 *  as module in a webserver) many requests are handled by the same extension
 *  instance.
 * 
 *  @author Emiel Bruijntjes <emiel.bruijntjes@copernica.com>
 *  @copyright 2013, 2014 Copernica BV
 */

/**
 *  Set up namespace
 */
namespace Php {

/**
 *  Forward declaration
 */
class ExtensionImpl;

/**
 *  Signature of a callback
 */
using Callback = std::function<void()>;

/**
 *  Class definition
 */
class Extension : public Namespace
{
public:
    /**
     *  Constructor that defines a number of functions right away
     *  @param  name        Extension name
     *  @param  version     Extension version string
     */
    Extension(const char *name, const char *version = "1.0");
    
    /**
     *  No copy'ing and no moving
     */
    Extension(const Extension &extension) = delete;
    Extension(Extension &&extension) = delete;
    
    /**
     *  Destructor
     */
    virtual ~Extension();
    
    /**
     *  Register a function to be called when the PHP engine is ready
     * 
     *  The callback will be called after all extensions are loaded, and all 
     *  functions and classes are available, but before the first pageview/request
     *  is handled. You can register this callback if you want to be notified
     *  when the engine is ready, for example to initialize certain things.
     * 
     *  @param  callback    Function to be called
     *  @return Extension   Same object to allow chaining
     */
    Extension &onStartup(const Callback &callback);
    
    /**
     *  Register a function to be called when the PHP engine is going to stop
     * 
     *  The callback will be called right before the process is going to stop.
     *  You can register a function if you want to clean up certain things.
     * 
     *  @param  callback    Function to be called
     *  @return Extension   Same object to allow chaining
     */
    Extension &onShutdown(const Callback &callback);
    
    /**
     *  Register a callback that is called at the beginning of each pageview/request
     * 
     *  You can register a callback if you want to initialize certain things
     *  at the beginning of each request. Remember that the extension can handle
     *  multiple requests after each other, and you may want to set back certain
     *  global variables to their initial variables in front of each request
     * 
     *  @param  callback    Function to be called
     *  @return Extension   Same object to allow chaining
     */
    Extension &onRequest(const Callback &callback);
    
    /**
     *  Register a callback that is called to cleanup things after a pageview/request
     * 
     *  The callback will be called after _each_ request, so that you can clean up
     *  certain things and make your extension ready to handle the next request.
     *  This method is called onIdle because the extension is idle in between
     *  requests.
     * 
     *  @param  callback    Function to be called
     *  @return Extension   Same object to allow chaining
     */
    Extension &onIdle(const Callback &callback);
    
    /**
     *  Retrieve the module pointer
     * 
     *  This is the memory address that should be exported by the get_module()
     *  function.
     *
     *  @return void*
     */
    void *module();
    
    /**
     *  Cast to a module entry
     * 
     *  @return void*
     */
    operator void * ()
    {
        return module();
    }

private:
    /**
     *  The implementation object
     * 
     *  @var ExtensionImpl
     */
    ExtensionImpl *_impl;
};

/**
 *  End of namespace
 */
}