When exchanging data from your own extensions with PHP scripts, one of the most important issues is the creation of variables. This section shows you how to deal with the variable types that PHP supports.
To create new variables that can be seen "from the outside" by the
executing script, you need to allocate a new zval
container, fill this container with meaningful values, and then
introduce it to Zend's internal symbol table. This basic process
is common to all variable creations:
zval *new_variable;
/* allocate and initialize new container */
MAKE_STD_ZVAL(new_variable);
/* set type and variable contents here, see the following sections */
/* introduce this variable by the name "new_variable_name" into the symbol table */
ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable);
/* the variable is now accessible to the script by using $new_variable_name */
The macro MAKE_STD_ZVAL
allocates a new
zval
container using ALLOC_ZVAL
and initializes it using INIT_ZVAL
. As
implemented in Zend at the time of this writing,
initializing means setting the reference
count to 1
and clearing the
is_ref
flag, but this process could be extended
later - this is why it's a good idea to keep using
MAKE_STD_ZVAL
instead of only using
ALLOC_ZVAL
. If you want to optimize for speed
(and you don't have to explicitly initialize the
zval
container here), you can use
ALLOC_ZVAL
, but this isn't recommended because
it doesn't ensure data integrity.
ZEND_SET_SYMBOL
takes care of introducing the
new variable to Zend's symbol table. This macro checks whether the
value already exists in the symbol table and converts the new
symbol to a reference if so (with automatic deallocation of the
old zval
container). This is the preferred method
if speed is not a crucial issue and you'd like to keep memory
usage low.
Note that ZEND_SET_SYMBOL
makes use of the Zend
executor globals via the macro EG
. By
specifying EG(active_symbol_table)
, you get access to the
currently active symbol table, dealing with the active, local scope. The local
scope may differ depending on whether the function was invoked from
within a function.
If you need to optimize for speed and don't care about optimal memory usage, you can omit the check for an existing variable with the same value and instead force insertion into the symbol table by using zend_hash_update():
zval *new_variable;
/* allocate and initialize new container */
MAKE_STD_ZVAL(new_variable);
/* set type and variable contents here, see the following sections */
/* introduce this variable by the name "new_variable_name" into the symbol table */
zend_hash_update(
EG(active_symbol_table),
"new_variable_name",
strlen("new_variable_name") + 1,
&new_variable,
sizeof(zval *),
NULL
);
This is actually the standard method used in most modules.
The variables generated with the snippet above will always be of local scope, so they reside in the context in which the function has been called. To create new variables in the global scope, use the same method but refer to another symbol table:
zval *new_variable;
// allocate and initialize new container
MAKE_STD_ZVAL(new_variable);
//
// set type and variable contents here
//
// introduce this variable by the name "new_variable_name" into the global symbol table
ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name", new_variable);
The macro ZEND_SET_SYMBOL
is now being
called with a reference to the main, global symbol table by referring
EG(symbol_table)
.
Note: The active_symbol_table
variable is a pointer, but symbol_table
is not.
This is why you have to use
EG(active_symbol_table)
and
&EG(symbol_table)
as parameters to
ZEND_SET_SYMBOL
- it requires a pointer.
Similarly, to get a more efficient version, you can hardcode the symbol table update:
zval *new_variable;
// allocate and initialize new container
MAKE_STD_ZVAL(new_variable);
//
// set type and variable contents here
//
// introduce this variable by the name "new_variable_name" into the global symbol table
zend_hash_update(
&EG(symbol_table),
"new_variable_name",
strlen("new_variable_name") + 1,
&new_variable,
sizeof(zval *),
NULL
);
例 3.9 “Creating variables with different scopes.” shows a sample source that
creates two variables - local_variable
with a local scope
and global_variable
with a global scope (see Figure 9.7).
The full example can be found on the CD-ROM.
Note: You can see that the global variable is actually not accessible from
within the function. This is because it's not imported into the local scope
using global $global_variable;
in the PHP source.
ZEND_FUNCTION(variable_creation)
{
zval *new_var1, *new_var2;
MAKE_STD_ZVAL(new_var1);
MAKE_STD_ZVAL(new_var2);
ZVAL_LONG(new_var1, 10);
ZVAL_LONG(new_var2, 5);
ZEND_SET_SYMBOL(EG(active_symbol_table), "local_variable", new_var1);
ZEND_SET_SYMBOL(&EG(symbol_table), "global_variable", new_var2);
RETURN_NULL();
}
Now let's get to the assignment of data to variables, starting with
longs. Longs are PHP's integers and are very simple to store. Looking at
the zval.value
container structure discussed earlier in this
chapter, you can see that the long data type is directly contained in the union,
namely in the lval
field. The corresponding
type
value for longs is IS_LONG
(see 例 3.10 “Creation of a long.”).
zval *new_long;
MAKE_STD_ZVAL(new_long);
new_long->type = IS_LONG;
new_long->value.lval = 10;
Alternatively, you can use the macro ZVAL_LONG
:
zval *new_long;
MAKE_STD_ZVAL(new_long);
ZVAL_LONG(new_long, 10);
Doubles are PHP's floats and are as easy to assign as longs, because their value
is also contained directly in the union. The member in the
zval.value
container is dval
;
the corresponding type is IS_DOUBLE
.
zval *new_double;
MAKE_STD_ZVAL(new_double);
new_double->type = IS_DOUBLE;
new_double->value.dval = 3.45;
Alternatively, you can use the macro ZVAL_DOUBLE
:
zval *new_double;
MAKE_STD_ZVAL(new_double);
ZVAL_DOUBLE(new_double, 3.45);
Strings need slightly more effort. As mentioned earlier, all strings
that will be associated with Zend's internal data structures need to be
allocated using Zend's own memory-management functions. Referencing of static
strings or strings allocated with standard routines is not allowed. To assign
strings, you have to access the structure str
in
the zval.value
container. The corresponding type
is IS_STRING
:
zval *new_string;
char *string_contents = "This is a new string variable";
MAKE_STD_ZVAL(new_string);
new_string->type = IS_STRING;
new_string->value.str.len = strlen(string_contents);
new_string->value.str.val = estrdup(string_contents);
Note the usage of Zend's estrdup() here.
Of course, you can also use the predefined macro
ZVAL_STRING
:
zval *new_string;
char *string_contents = "This is a new string variable";
MAKE_STD_ZVAL(new_string);
ZVAL_STRING(new_string, string_contents, 1);
ZVAL_STRING
accepts a third parameter that
indicates whether the supplied string contents should be duplicated (using
estrdup()). Setting this parameter
to 1
causes the string to be
duplicated; 0
simply uses the supplied pointer for the
variable contents. This is most useful if you want to create a new variable
referring to a string that's already allocated in Zend internal memory.
If you want to truncate the string at a certain position or you
already know its length, you can use ZVAL_STRINGL(zval,
string, length, duplicate)
, which accepts an explicit
string length to be set for the new string. This macro is faster
than ZVAL_STRING
and also binary-safe.
To create empty strings, set the string length to 0
and
use empty_string
as contents:
new_string->type = IS_STRING;
new_string->value.str.len = 0;
new_string->value.str.val = empty_string;
Of course, there's a macro for this as
well (ZVAL_EMPTY_STRING
):
MAKE_STD_ZVAL(new_string);
ZVAL_EMPTY_STRING(new_string);
Booleans are created just like longs, but have the
type IS_BOOL
. Allowed values in
lval
are 0
and 1
:
zval *new_bool;
MAKE_STD_ZVAL(new_bool);
new_bool->type = IS_BOOL;
new_bool->value.lval = 1;
The corresponding macros for this type
are ZVAL_BOOL
(allowing specification of the value) as well
as ZVAL_TRUE
and ZVAL_FALSE
(which
explicitly set the value to TRUE
and FALSE
,
respectively).
Arrays are stored using Zend's internal hash tables, which can be
accessed using the zend_hash_*() API. For every
array that you want to create, you need a new hash table handle,
which will be stored in the ht
member of the
zval.value
container.
There's a whole API solely for the creation of arrays, which is extremely handy. To start a new array, you call array_init().
zval *new_array;
MAKE_STD_ZVAL(new_array);
array_init(new_array);
array_init() always returns SUCCESS
.
To add new elements to the array, you can use numerous functions,
depending on what you want to do.
表 3.8 “Zend's API for Associative Arrays”,
表 3.9 “Zend's API for Indexed Arrays, Part 1” and
表 3.10 “Zend's API for Indexed Arrays, Part 2”
describe these functions. All functions return
FAILURE
on failure and
SUCCESS
on success.
Function | Description |
add_assoc_long(zval *array, char *key, long n);() | Adds an element of type long . |
add_assoc_unset(zval *array, char *key);() | Adds an unset element. |
add_assoc_bool(zval *array, char *key, int b);() | Adds a Boolean element. |
add_assoc_resource(zval *array, char *key, int r);() | Adds a resource to the array. |
add_assoc_double(zval *array, char *key, double d);() | Adds a floating-point value. |
add_assoc_string(zval *array, char *key, char *str, int duplicate);() |
Adds a string to the array. The
flag duplicate specifies whether the string contents have to be
copied to Zend internal memory.
|
add_assoc_stringl(zval *array, char *key, char *str, uint length, int duplicate); () |
Adds a string with the desired length length
to the array. Otherwise, behaves like
add_assoc_string().
|
add_assoc_zval(zval *array, char *key, zval *value);() | Adds a zval to the array. Useful for adding other arrays, objects, streams, etc... |
Function | Description |
add_index_long(zval *array, uint idx, long n);() | Adds an element of type long . |
add_index_unset(zval *array, uint idx);() | Adds an unset element. |
add_index_bool(zval *array, uint idx, int b);() | Adds a Boolean element. |
add_index_resource(zval *array, uint idx, int r);() | Adds a resource to the array. |
add_index_double(zval *array, uint idx, double d);() | Adds a floating-point value. |
add_index_string(zval *array, uint idx, char *str, int duplicate);() | Adds a string to the array. The
flag duplicate specifies whether the string contents have to be
copied to Zend internal memory. |
add_index_stringl(zval *array, uint idx, char *str, uint length, int duplicate);() | Adds a string with the desired
length length to the array. This function is faster and binary-safe. Otherwise, behaves like add_index_string()(). |
add_index_zval(zval *array, uint idx, zval *value);() | Adds a zval to the array. Useful for adding other arrays, objects, streams, etc... |
Function | Description |
add_next_index_long(zval *array, long n);() | Adds an element of type long . |
add_next_index_unset(zval *array);() | Adds an unset element. |
add_next_index_bool(zval *array, int b);() | Adds a Boolean element. |
add_next_index_resource(zval *array, int r);() | Adds a resource to the array. |
add_next_index_double(zval *array, double d);() | Adds a floating-point value. |
add_next_index_string(zval *array, char *str, int duplicate);() | Adds a string to the array. The
flag duplicate specifies whether the string contents have to be
copied to Zend internal memory. |
add_next_index_stringl(zval *array, char *str, uint length, int duplicate);() | Adds a string with the desired
length length to the array. This function is faster and binary-safe. Otherwise, behaves like add_index_string()(). |
add_next_index_zval(zval *array, zval *value);() | Adds a zval to the array. Useful for adding other arrays, objects, streams, etc... |
All these functions provide a handy abstraction to Zend's internal hash
API. Of course, you can also use the hash functions directly - for example, if
you already have a zval
container allocated that you want to
insert into an array. This is done using zend_hash_update()()
for associative arrays (see 例 3.11 “Adding an element to an associative array.”) and
zend_hash_index_update() for indexed arrays
(see 例 3.12 “Adding an element to an indexed array.”):
zval *new_array, *new_element;
char *key = "element_key";
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);
array_init(new_array);
ZVAL_LONG(new_element, 10);
if(zend_hash_update(new_array->value.ht, key, strlen(key) + 1, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
// do error handling here
}
zval *new_array, *new_element;
int key = 2;
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);
array_init(new_array);
ZVAL_LONG(new_element, 10);
if(zend_hash_index_update(new_array->value.ht, key, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
// do error handling here
}
To emulate the functionality of add_next_index_*(), you can use this:
zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL)
Note: To return arrays from a function, use array_init() and
all following actions on the predefined variable return_value
(given as argument to your exported function; see the earlier discussion of the call interface). You do not have to use
MAKE_STD_ZVAL
on this.
Tip: To avoid having to
write new_array->value.ht
every time, you can
use HASH_OF(new_array)
, which is also recommended for
compatibility and style reasons.
Since objects can be converted to arrays (and vice versa), you might have already guessed that they have a lot of similarities to arrays in PHP. Objects are maintained with the same hash functions, but there's a different API for creating them.
To initialize an object, you use the function object_init():
zval *new_object;
MAKE_STD_ZVAL(new_object);
if(object_init(new_object) != SUCCESS)
{
// do error handling here
}
You can use the functions described in 表 3.11 “Zend's API for Object Creation” to add members to your object.
Function | Description |
add_property_long(zval *object, char *key, long l);() | Adds a long to the object. |
add_property_unset(zval *object, char *key);() | Adds an unset property to the object. |
add_property_bool(zval *object, char *key, int b);() | Adds a Boolean to the object. |
add_property_resource(zval *object, char *key, long r);() | Adds a resource to the object. |
add_property_double(zval *object, char *key, double d);() | Adds a double to the object. |
add_property_string(zval *object, char *key, char *str, int duplicate);() | Adds a string to the object. |
add_property_stringl(zval *object, char *key, char *str, uint length, int duplicate);() | Adds a string of the specified length to the object. This function is faster than add_property_string() and also binary-safe. |
add_property_zval(zval *obect, char *key, zval *container):() |
Adds a zval container to the object. This is useful if you
have to add properties which aren't simple types like integers or strings but
arrays or other objects.
|
Resources are a special kind of data type in PHP. The term resources doesn't really refer to any special kind of data, but to an abstraction method for maintaining any kind of information. Resources are kept in a special resource list within Zend. Each entry in the list has a correspondending type definition that denotes the kind of resource to which it refers. Zend then internally manages all references to this resource. Access to a resource is never possible directly - only via a provided API. As soon as all references to a specific resource are lost, a corresponding shutdown function is called.
For example, resources are used to store database links and file descriptors. The de facto standard implementation can be found in the MySQL module, but other modules such as the Oracle module also make use of resources.
In fact, a resource can be a pointer to anything you need to handle in your functions (e.g. pointer to a structure) and the user only has to pass a single resource variable to your function.
To create a new resource you need to register a resource destruction handler for it. Since you can store any kind of data as a resource, Zend needs to know how to free this resource if its not longer needed. This works by registering your own resource destruction handler to Zend which in turn gets called by Zend whenever your resource can be freed (whether manually or automatically). Registering your resource handler within Zend returns you the resource type handle for that resource. This handle is needed whenever you want to access a resource of this type later and is most of time stored in a global static variable within your extension. There is no need to worry about thread safety here because you only register your resource handler once during module initialization.
The Zend function to register your resource handler is defined as:
ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number);
There are two different kinds of resource destruction handlers you can
pass to this function: a handler for normal resources and a handler
for persistent resources. Persistent resources are for example used
for database connection. When registering a resource, either of these
handlers must be given. For the other handler just pass
NULL
.
zend_register_list_destructors_ex() accepts the following parameters:
ld | Normal resource destruction handler callback |
pld | Pesistent resource destruction handler callback |
type_name | A string specifying the name of
your resource. It's always a good thing to
specify a unique name within PHP for the resource type
so when the user for example calls
var_dump($resource);
he also gets the name of the resource. |
module_number | The module_number
is automatically available in your
PHP_MINIT_FUNCTION
function and therefore you just pass it over. |
The return value is a unique integer ID for your resource type.
The resource destruction handler (either normal or persistent resources) has the following prototype:
void resource_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC);
The passed rsrc
is a pointer to the following structure:
typedef struct _zend_rsrc_list_entry {
void *ptr;
int type;
int refcount;
} zend_rsrc_list_entry;
The member void *ptr
is the actual pointer to
your resource.
Now we know how to start things, we define our own resource we want register within Zend. It is only a simple structure with two integer members:
typedef struct {
int resource_link;
int resource_type;
} my_resource;
Our resource destruction handler is probably going to look something like this:
void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {
// You most likely cast the void pointer to your structure type
my_resource *my_rsrc = (my_resource *) rsrc->ptr;
// Now do whatever needs to be done with you resource. Closing
// Files, Sockets, freeing additional memory, etc.
// Also, don't forget to actually free the memory for your resource too!
do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
}
One important thing to mention: If your resource is a rather complex structure which also contains pointers to memory you allocated during runtime you have to free them before freeing the resource itself!
Now that we have defined
what our resource is and
our resource destruction handler
we can go on and do the rest of the steps:
create a global variable within the extension holding the resource ID so it can be accessed from every function which needs it
define the resource name
write the resource destruction handler
and finally register the handler
// Somewhere in your extension, define the variable for your registered resources.
// If you wondered what 'le' stands for: it simply means 'list entry'.
static int le_myresource;
// It's nice to define your resource name somewhere
#define le_myresource_name "My type of resource"
[...]
// Now actually define our resource destruction handler
void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {
my_resource *my_rsrc = (my_resource *) rsrc->ptr;
do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
}
[...]
PHP_MINIT_FUNCTION(my_extension) {
// Note that 'module_number' is already provided through the
// PHP_MINIT_FUNCTION() function definition.
le_myresource = zend_register_list_destructors_ex(my_destruction_handler, NULL, le_myresource_name, module_number);
// You can register additional resources, initialize
// your global vars, constants, whatever.
}
To actually register a new resource you use can either use the zend_register_resource() function or the ZEND_REGISTER_RESOURE() macro, both defined in zend_list.h . Although the arguments for both map 1:1 it's a good idea to always use macros to be upwards compatible:
int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type);
rsrc_result | This is an already initialized
zval * container. |
rsrc_pointer | Your resource pointer you want to store. |
rsrc_type | The type which you received when
you registered the resource destruction handler. If you
followed the naming scheme this would be
le_myresource . |
The return value is a unique integer identifier for that resource.
What is really going on when you register a new resource is it gets
inserted in an internal list in Zend and the result is just stored
in the given zval *
container:
rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type);
if (rsrc_result) {
rsrc_result->value.lval = rsrc_id;
rsrc_result->type = IS_RESOURCE;
}
return rsrc_id;
The returned rsrc_id
uniquly identifies the newly
registered resource. You can use the macro
RETURN_RESOURE
to return it to the user:
RETURN_RESOURCE(rsrc_id)
It is common practice that if you want to return the resource
immediately to the user you specify the return_value
as the zval *
container.
Zend now keeps track of all references to this resource. As soon as all references to the resource are lost, the destructor that you previously registered for this resource is called. The nice thing about this setup is that you don't have to worry about memory leakages introduced by allocations in your module - just register all memory allocations that your calling script will refer to as resources. As soon as the script decides it doesn't need them anymore, Zend will find out and tell you.
Now that the user got his resource, at some point he is passing it
back to one of your functions. The value.lval
inside
the zval *
container contains the key to your
resource and thus can be used to fetch the resource with the following
macro:
ZEND_FETCH_RESOURCE
:
ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type)
rsrc | This is your pointer which will point to your previously registered resource. |
rsrc_type | This is the typecast argument for
your pointer, e.g. myresource * . |
rsrc_id | This is the address of the
zval * container the user passed to
your function, e.g. &z_resource if
zval *z_resource is given. |
default_rsrc_id | This integer specifies the default
resource ID if no resource could be fetched
or -1. |
resource_type_name | This is the name of the requested resource. It's a string and is used when the resource can't be found or is invalid to form a meaningful error message. |
resource_type | The resource_type
you got back when registering the resource destruction handler.
In our example this was le_myresource . |
This macro has no return value.
It is for the developers convenience and takes care
of TSRMLS arguments passing and also does check if the resource
could be fetched.
It throws a warning message and returns the current PHP function
with NULL
if there was a problem retrieving the
resource.
To force removal of a resource from the list, use the function
zend_list_delete(). You can also force the
reference count to increase if you know that you're creating another
reference for a previously allocated value (for example, if you're
automatically reusing a default database link). For this case, use the
function zend_list_addref(). To search for
previously allocated resource entries, use
zend_list_find(). The complete API can be found
in zend_list.h
.
In addition to the macros discussed earlier, a few macros allow
easy creation of simple global variables. These are nice to know
in case you want to introduce global flags, for example. This is
somewhat bad practice, but Table 表 3.12 “Macros for Global Variable Creation”
describes macros that do
exactly this task. They don't need any zval
allocation; you simply have to supply a variable name and value.
Macro | Description |
SET_VAR_STRING(name, value) | Creates a new string. |
SET_VAR_STRINGL(name, value,
length) | Creates a new string of the specified length. This macro
is faster than SET_VAR_STRING and also binary-safe. |
SET_VAR_LONG(name, value) | Creates a new long. |
SET_VAR_DOUBLE(name, value) | Creates a new double. |
Zend supports the creation of true constants (as opposed to
regular variables). Constants are accessed without the typical
dollar sign ($
) prefix and are available in all
scopes. Examples include TRUE
and
FALSE
, to name just two.
To create your own constants, you can use the macros in 表 3.13 “Macros for Creating Constants”. All the macros create a constant with the specified name and value.
You can also specify flags for each constant:
CONST_CS
- This constant's name is to be
treated as case sensitive.
CONST_PERSISTENT
- This constant is
persistent and won't be "forgotten" when the current process
carrying this constant shuts down.
To use the flags, combine them using a inary OR:
// register a new constant of type "long"
REGISTER_LONG_CONSTANT("NEW_MEANINGFUL_CONSTANT", 324, CONST_CS |
CONST_PERSISTENT);
There are two types of
macros - REGISTER_*_CONSTANT
andREGISTER_MAIN_*_CONSTANT
. The first type
creates constants bound to the current module. These constants are
dumped from the symbol table as soon as the module that registered
the constant is unloaded from memory. The second type creates
constants that remain in the symbol table independently of the
module.
Macro | Description |
REGISTER_LONG_CONSTANT(name, value, flags)
REGISTER_MAIN_LONG_CONSTANT(name, value, flags)
| Registers a new constant of type long. |
REGISTER_DOUBLE_CONSTANT(name, value, flags)
REGISTER_MAIN_DOUBLE_CONSTANT(name, value, flags)
| Registers a new constant of type double. |
REGISTER_STRING_CONSTANT(name, value, flags)
REGISTER_MAIN_STRING_CONSTANT(name, value, flags)
| Registers a new constant of type string. The specified string must reside in Zend's internal memory. |
REGISTER_STRINGL_CONSTANT(name, value, length, flags)
REGISTER_MAIN_STRINGL_CONSTANT(name, value, length,
flags)
| Registers a new constant of type string. The string length
is explicitly set to length . The specified string must reside
in Zend's internal memory. |