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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
|
<h1>Working with variables</h1>
<p>
Variables in PHP are non-typed. A variable can thus hold any possible type:
an integer, string, a floating point number, and even an object or an array.
C++ on the other hand is a typed language. In C++ an integer variable always
has a numeric value, and a string variable always hold a string value.
</p>
<p>
When you mix native code and PHP code, you will need to convert the non-typed
PHP variables into native variables, and the other way round: convert native
variables back into non-typed PHP variables. The PHP-CPP library offers the
Php::Value class that makes this a very simple task.
</p>
<h2 id="zvals">Zval's</h2>
<p>
But we start with sharing one of our frustrations.
If you have ever spent time on writing PHP extensions in plain C, or if you've
ever read something about the internals of PHP, you must have heard about zval's.
A zval is a C structure in which PHP variables are stored. Internally, this zval
keeps a refcount, a union with the possible types and a number of other members
too. Every time that you access such a zval, make a copy of it, or write to
it, you must break your head to correctly update the refcount, and/or split the
zval into different zvals, explicitly call copy constructors, allocate or
free memory (using special memory allocation routines), or choose not to
do this and leave the zval alone.
</p>
<p>
This all is crazy difficult and a big source for mistakes and all sorts of bugs.
</p>
<p>
And to make things even worse, there are literally hundreds of different
undocumented (!) macro's and functions in the Zend engine that can manipulate these
zval variables. There are special macro's that work on zval's, macro's for
pointers-to-zval's, macro's for pointer-to-pointer-to-zval's and even macro's
that deal with pointer-to-pointer-to-pointer-to-zval's.
</p>
<p>
Every single PHP module, every PHP extension, and every built-in PHP function
is busy manipulating these zval structures. It is a big surprise that nobody
ever took the time to wrap such a zval in a simple C++ class that does all
this administration for you. C++ is such a nice language with constructors,
destructors, casting operators and operator overloading that can encapsulate all
this complicated zval handling.
</p>
<p>
And that is exactly what we did with PHP-CPP. We have introduced the Php::Value
object with a very simple interface, that takes away all the problems of zval
handling. Internally, the Php::Value object is a wrapper around a zval variable,
but it completely hides the complexity of zval handling.
</p>
<p>
So, everything that you always wanted to ask about the internals of PHP, but
were afraid to ask: just forget about it. Sit back and relax, and take a look
how simple life is with PHP-CPP.
</p>
<h2 id="scalar-variables">Scalar variables</h2>
<p>
The Php::Value object can be used to store scalar variables. Scalar variables
are variables like integers, doubles, strings, booleans and null values.
To create such a scalar variable, just assign it to a Php::Value object.
</p>
<p>
<pre class="language-c++"><code>
Php::Value value1 = 1234;
Php::Value value2 = "this is a string";
Php::Value value3 = std::string("another string");
Php::Value value4 = nullptr;
Php::Value value5 = 123.45;
Php::Value value6 = true;
</code></pre>
</p>
<p>
The Php::Value class has casting operators to cast the object to almost
every thinkable native type. When you have access to a Php::Value object,
but want to store it in a (much faster) native variable, you can simply
assign it.
</p>
<p>
<pre class="language-c++"><code>
void myFunction(const Php::Value &value)
{
int value1 = value;
std::string value2 = value;
double value3 = value;
bool value4 = value;
}
</code></pre>
</p>
<p>
If the Php::Value object holds an object, and you cast it to a string, the
__toString() method of the object gets called, exactly what would happen
if you had casted the variable to a string in a PHP script.
</p>
<p>
Many different operators are overloaded too so that you can use a Php::Value
object directly in arithmetric operations, compare it with other variables,
or send it to an output stream.
</p>
<p>
<pre class="language-c++"><code>
void myFunction(Php::Value &value)
{
value += 10;
Php::out << value << std::endl;
if (value == "some string")
{
}
int result = value - 8;
}
</code></pre>
</p>
<p>
The Php::Value object has implicit constructors for most types. This means
that every function that accepts a Php::Value as parameter can also be
called with a native type, and in functions that should return a Php::Value
you can simply specify a scalar return value - which will automatically be
converted into a Php::Value object by the compiler.
</p>
<p>
<pre class="language-c++"><code>
Php::Value myFunction(const Php::Value &value)
{
if (value == 12)
{
return "abc";
}
else if (value > 100)
{
return myFunction(12);
}
return nullptr;
}
</code></pre>
</p>
<p>
As you can see in the examples, you can do almost anything with Php::Value
objects. Internally it does all the zval manipulation, and sometimes that
can become complicated, but for you, the extension programmer, there is
nothing to worry about.
</p>
<h2 id="strings">Strings</h2>
<p>
Strings can be easily stored in Php::Value objects. It is so easy to
assign a string to a Php::Value, or to cast a Php::Value into a string,
that any explanation hardly is necessary. Normally, the assignment operators
and casting operators are sufficient. When performance is an issue however,
you may consider to get direct access to the internal buffer inside the
Php::Value object.
</p>
<p>
When a Php::Value is casted to a std::string, the entire string contents
are copied from the Php::Value object to the std::string object.
If you do not want to make such a full copy, you can cast the value to a
const char * instead. This gives you direct access to the buffer inside
the Php::Value object. The size of the string can be retrieved with the size()
method. But you must realize that once the Php::Value gets out of scope,
the pointer to the buffer is no longer guaranteed to be valid.
</p>
<p>
<pre class="language-c++"><code>
/**
* Example function
* @param params
*/
void myFunction(Parameters &params)
{
// store the first parameter in a std::string (the entire string
// buffer is copied from the Php::Value object to the std::string)
std::string var1 = params[0];
// it also is possible to cast the object into a const char *. This works
// too, but the buffer is only valid for as long as the Php::Value object
// stays in scope
const char *var2 = params[0];
size_t var2size = params[0].size();
}
</code></pre>
</p>
<p>
It also is possible to directly write to the internal Php::Value buffer.
When you assign a string to a Php::Value object, the entire string buffer
is copied too. It does not matter if the string that you assign is a
std::string or a char*: a copy is always made. For small things, this hardly
is an issue and it would make your code much less readable if you did it
differently. But if you have to copy many bytes, you can better get direct
access to the buffer.
</p>
<p>
<pre class="language-c++"><code>
/**
* Example function to read bytes from a filedescriptor, and
* return it as a Php::Value object
*
* @param fd Filedescriptor
* @return Php::Value
*/
Php::Value readExample1(int fd)
{
// buffer to read the bytes in
char buffer[4096];
// read the buffer
ssize_t bytes = read(fd, buffer, 4096);
if (bytes < 0) bytes = 0;
// convert the buffer to a Php::Value object and return it
return Php::Value(buffer, bytes);
}
/**
* Another example function, that does the same as the previous
* function, but now it reads the bytes directly into a Php::Value
* buffer, and does not use an intermediate buffer.
*
* @param fd Filedescriptor
* @param Php::Value
*/
Php::Value readExample2(int fd)
{
// result variable
Php::Value result;
// resize the buffer to 4096 bytes, the resize() method resizes
// the internal buffer to the appropriate size, and returns a pointer
// to the buffer
char *buffer = result.resize(4096);
// read in the bytes directly into the just allocated buffer
ssize_t bytes = read(fd, buffer, 4096);
if (bytes < 0) bytes = 0;
// resize the buffer to the actual number of bytes in it (this
// is necessary, otherwise the PHP strlen() returns 4096 even
// when less bytes were available
result.resize(bytes);
// return the result
return result;
}
</code></pre>
</p>
<p>
The first example function is easier to read. The read() system call is
used to fill a local buffer with bytes. This local buffer is then converted
to a Php::Value object and returned.
</p>
<p>
The second example function is more efficient, because the read() system
call now immediately reads the bytes into the buffer of the Php::Value
object, and not into a temporary buffer. As a programmer, you must choose
between one of these algorithms depending on your needs: easy code or more
efficient code.
</p>
<h2 id="arrays">Arrays</h2>
<p>
PHP supports two array types: regular arrays (indexed by numbers) and
associative arrays (indexed by strings). The Php::Value object supports
arrays too. By using array access operators (square brackets) to assign
values to a Php::Value object, you automatically turn it into an array.
</p>
<p>
<pre class="language-c++"><code>
// create a regular array
Php::Value array;
array[0] = "apple";
array[1] = "banana";
array[2] = "tomato";
// an initializer list can be used to create a filled array
Php::Value filled({ "a", "b", "c", "d"});
// you can cast an array to a vector, template parameter can be
// any type that a Value object is compatible with (string, int, etc)
std::vector<std::string> fruit = array;
// create an associative array
Php::Value assoc;
assoc["apple"] = "green";
assoc["banana"] = "yellow";
assoc["tomato"] = "green";
// the variables in an array do not all have to be of the same type
Php::Value assoc2;
assoc2["x"] = "info@example.com";
assoc2["y"] = nullptr;
assoc2["z"] = 123;
// nested arrays are possible too
Php::Value assoc2;
assoc2["x"] = "info@example.com";
assoc2["y"] = nullptr;
assoc2["z"][0] = "a";
assoc2["z"][1] = "b";
assoc2["z"][2] = "c";
// assoc arrays can be cast to a map, indexed by string
std::map<std::string,std::string> map = assoc2;
</code></pre>
</p>
<p>
Reading from arrays is just as simple. You can use the array access
operators (square brackets) for this too.
</p>
<p>
<pre class="language-c++"><code>
Php::Value array;
array["x"] = 10;
array["y"] = 20;
Php::out << array["x"] << std::endl;
Php::out << array["y"] << std::endl;
</code></pre>
</p>
<p>
There also is a special Php::Array class. This is an extended Php::Value
class that, when constructed, immediately starts as empty array (unlike
Php::Value objects that by default construct to NULL values).
</p>
<p>
<pre class="language-c++"><code>
// create empty array
Php::Array array1;
// Php::Value is the base class, so you can assign Php::Array objects
Php::Value array2 = array1;
// impossible, a Php::Array must always be an array
array1 = 100;
</code></pre>
</p>
<h2 id="objects">Objects</h2>
<p>
Just like the Php::Array class that is an extended Php::Value that initializes
to an empty array, there also is a Php::Object class that becomes an
object when constructed. By default this is an instance of stdClass - PHP's
most simple class.
</p>
<p>
<pre class="language-c++"><code>
// create empty object of type stdClass
Php::Object object;
// Php::Value is the base class, so you can assign Php::Object objects
Php::Value value = object;
// impossible, a Php::Object must always be an object
object = "test";
// object properties can be accessed with square brackets
object["property1"] = "value1";
object["property2"] = "value2";
// to create an object of a different type, pass in the class name
// to the constructor with optional constructor parameters
object = Php::Object("DateTime", "now");
// methods can be called with the call() method
Php::out << object.call("format", "Y-m-d H:i:s") << std::endl;
// all these methods can be called on a Php::Value object too
Php::Value value = Php::Object("DateTime", "now");
Php::out << value.call("format", "Y-m-d H:i:s") << std::endl;
</code></pre>
</p>
<h2 id="iterating">Iterating</h2>
<p>
The Php::Value class implements the begin() and end() methods just like
many C++ STL containers. As a consequence, you can iterate over a Php::Value
just like you would iterate over a std::map class.
</p>
<p>
<pre class="language-c++"><code>
/**
* Function that accepts an array as parameter
* @param array
*/
void myFunction(const Php::Value &value)
{
// assum the value variable holds an array or object, it then
// is possible to iterator over the values or properties
for (auto &iter : value)
{
// output key and value
Php::out << iter.first << ": " << iter.second << std::endl;
}
}
</code></pre>
</p>
<p>
The iterated value is a std::pair<Php::Value::Php::Value>. You can
access its property 'first' to get the current key, and the property 'second'
to get the current value. This is identical to how you would iterate over
a std::map.
</p>
<p>
You can iterate over all Php::Value objects that hold either an object
or an array. When you iterate over an array, the iterator simply iterates
over all records in the array.
</p>
<p>
For objects there are some things to consider. If the object that you iterate
over implements the Iterator or IteratorAggregate interface, the C++ iterator
uses these built-in interfaces and calls its methods to traverse the object.
For regular objects (the ones that do not implement Iterator or IteratorAggregate)
the iterator simply iterates over all the <i>public</i> properties of the object.
</p>
<p>
An iterator can be used in two directions: both the operator ++ as well as
the operator -- are available. But be careful with using the -- operator: If
the Php::Value object holds an object that implements Iterator or
IteratorAggregate, reverse iterating does not work, because the internal
iterator only has a next() method, and there is no way for the PHP-CPP
library to instruct the internal iterator to move backwards.
</p>
<p>
Also be careful with the return value of the ++ postfix operator. Normally,
a postfix increment operation returns the original value <i>before</i>
the operation. This is different when you iterate over objects that implement
Iterator or IteratorAggregate, because it is impossible for the PHP-CPP
library to make a copy of a PHP iterator. As a result, the ++ postfix operator
(only when using it on a Iterator or IteratorAggregate object) returns a brand
new iterator that is back at the front position of the object. But remember that
in C++ and PHP (and in many other programming languages) it is much wiser to
use the ++ <i>prefix</i> operator, as this does not require making a copy of
the original object, so you should not use the ++ postfix operator anyway!
</p>
<h2 id="functions">Functions</h2>
<p>
When a Php::Value object holds a <i>callable</i>, you can use the () operator
to call this function or method.
</p>
<p>
<pre class="language-c++"><code>
// create a string with a function name
Php::Value date = "date";
// "date" is a built-in PHP function and thus can it be called
Php::out << date("Y-m-d H:i:s") << std::endl;
// create a date-time object
Php::Object now = Php::Object("DateTime","now");
// create an array with two members, the datetime object
// and the name of a method
Php::Array array();
array[0] = now;
array[1] = "format";
// an array with two members can be called too, the first
// member is seen as the object, and the second as the
// name of the method
Php::out << array("Y-m-d H:i:s") << std::endl;
</code></pre>
</p>
<h2 id="global-variables">Global variables</h2>
<p>
To read or update global PHP variables, you can use the Php::GLOBALS
variable. This variable works more or less the same as the $GLOBALS
variable in a PHP script.
</p>
<p>
<pre class="language-c++"><code>
// set a global PHP variable
Php::GLOBALS["a"] = 12345;
// global variables can be of any type
Php::GLOBALS["b"] = Php::Array({1,2,3,4});
// nested calls are (of course) supported
Php::GLOBALS["b"][4] = 5;
// and global variables can also be read
Php::out << Php::GLOBALS["b"] << std::endl;
</code></pre>
</p>
<p>
Next to the $GLOBALS variable, PHP allows you to access variables using
the $_GET, $_POST, $_COOKIE, $_FILES, $_SERVER, $_REQUEST and $_ENV variables.
In your C++ extension you can do something similar with the global variables
Php::GET, Php::POST, Php::COOKIE, Php::FILES, Php::SERVER, Php::REQUEST and
Php::ENV. These are global, read-only, objects with an overloaded operator[]
method. You can thus access them as if it were associative arrays.
</p>
<p>
<pre class="language-c++"><code>
// retrieve the value of a request variable
int age = Php::REQUEST["name"];
// or retrieve the value of a server variable
std::string referer = Php::SERVER["HTTP_REFERER"];
</code></pre>
</p>
<h2 id="global-natives">Be careful with global C++ variables</h2>
<p>
Unlike PHP scripts, that only handle single pageviews, an extension is
used to handle multiple pageviews after each other. This means that when
you use global C++ (!) variables in your extension, that these variables are
not set back to their initial value in between the pageviews. The
Php::GLOBALS variable however, is always re-initialized at the beginning
of every new pageview.
</p>
<p>
You can read more about this in the article about the
<a href="extension-callbacks">the extension callbacks</a>.
</p>
|