A resource is an abstract value that can hold any kind
of information. As previously mentioned, this information often consists of
data such as file handles, database connection structures, and other complex
types.
An Introduction to Writing PHP Extensions Chap. 15
The main reason for using resources is that they are managed via a cen-
tralized list that automatically destroys the resource in case the PHP devel-
oper hasn’t done so explicitly in his script.
For instance, consider writing a script that opens a MySQL connection
via the call mysql_connect(), but doesn’t call mysql_close() to close it once the
database connection resource isn’t in use anymore. In PHP, the resource mech-
anism detects when this resource should be destroyed, and will destroy it (at
the latest) at the end of the current request and often much earlier. This gives
a bulletproof mechanism for eliminating the possibility for resource leaks.
Without such a mechanism, after a few web requests, the web server could be
potentially leaking a lot of resources, which could lead to server crashes or
malfunction.
Registering Resources Types
How do you use resources?
The Zend Engine has made it relatively easy to work with resources. The
first thing you have to do is register your resource type with the engine.
The API function to use is
int zend_register_list_destructors_ex(rsrc_dtor_func_t ld,
rsrc_dtor_func_t pld, char *type_name, int module_number)
The function returns a resource type id, which should be saved by the
extension in a global variable and will be passed to other resource API calls
when necessary. ld, the destructor function, should be called for this resource.
pld is used for persistent resources that can survive in between requests and
won’t be covered in this chapter. type_name is a string with a descriptive name
for the type. module_number is used internally by the engine, and when we call
this function, we will just pass through an already defined module_number vari-
able.
Back to our example: We will add the following code to our myfile.c
source file. It includes the definition for the destructor function that is passed
to the zend_register_list_destructors_ex() registration function (it should be
added early in the file so that it’s defined by the time you make the
zend_register_list_destructors_ex() call):
static void myfile_dtor(zend_rsrc_list_entry *rsrc TSRMLS_DC)
{
FILE *fp = (FILE *) rsrc->ptr;
fclose(fp);
}
f t e r a d d i n g t h e r e g i s t r a t i o n l i n e t o y o u r a u t o - g e n e r a t e d
PHP_MINIT_FUNCTION() function, it should look similar to the following:
PHP_MINIT_FUNCTION(myfile)
{
/* If you have INI entries, uncomment these lines
ZEND_INIT_MODULE_GLOBALS(myfile, php_myfile_init_globals,
NULL);
REGISTER_INI_ENTRIES();
*/
le_myfile = zend_register_list_destructors_ex(myfile_dtor,
NULL,”standard-c-file”, module_number);
return SUCCESS;
}
* Note that le_myfile is a global variable that is already defined by the ext_skel
script.
PHP_MINIT_FUNCTION() is the per-module (extension) startup function that
is part of the API exposed to your extension. Table 15.3 gives you a short over-
view of the available functions and how you can use them.
Table 15.3 Function Declaration Macros
Function Declaration Macro
Semantics
PHP_MINIT_FUNCTION()
The module startup function is called by the engine when
PHP loads and allows it to do necessary one-time initial-
izations, such as registering resource types, registering
INI values, and more.
PHP_MSHUTDOWN_FUNCTION()
The module shutdown function is called by the engine
when PHP shuts down completely and is usually used for
unregistering INI entries.
PHP_RINIT_FUNCTION()
The per-request startup function is called at the begin-
ning of each request served by PHP, and it is used to
manage per-request logic.
PHP_RSHUTDOWN_FUNCTION()
The per-request shutdown function is called at the end of
each request served by PHP, and it is most often used to
clean up the per-request startup function’s logic.
PHP_MINFO_FUNCTION()
The module info function is called during the PHP
phpinfo() function and prints out this modules
information.