Following is a merge of two letters I sent to php4beta@lists.php.net, describing the changes in API between PHP 3.0 and PHP 4.0 (Zend). This file is by no means thorough documentation of the PHP API, and is intended for developers who are familiar with the PHP 3.0 API, and want to port their code to PHP 4.0, or take advantage of its new features. For highlights about the PHP 3.0 API, consult apidoc.txt. Zeev -------------------------------------------------------------------------- I'm going to try to list the important changes in API and programming techniques that are involved in developing modules for PHP4/Zend, as opposed to PHP3. Listing the whole PHP4 API is way beyond my scope here, it's mostly a 'diff' from the apidoc.txt, which you're all pretty familiar with. An important note that I neglected to mention yesterday - the php4 tree is based on the php 3.0.5 tree, plus all 3.0.6 patches hand-patched into it. Notably, it does NOT include any 3.0.7 patches. All of those have to be reapplied, with extreme care - modules should be safe to patch (mostly), but anything that touches the core or main.c will almost definitely require changes in order to work properly. [1] Symbol Tables One of the major changes in Zend involves changing the way symbols tables work. Zend enforces reference counting on all values and resources. This required changes in the semantics of the hash tables that implement symbol tables. Instead of storing pval in the hashes, we now store pval *. All of the API functions in Zend were changed in a way that this change is completely transparent. However, if you've used 'low level' hash functions to access or update elements in symbol tables, your code will require changes. Following are two simple examples, one demonstrates the difference between PHP3 and Zend when reading a symbol's value, and the other demonstrates the difference when writing a value. php3_read() { pval *foo; _php3_hash_find(ht, "foo", sizeof("foo"), &foo); /* foo->type is the type and foo->value is the value */ } php4_read() { pval **foo; _php3_hash_find(ht, "foo", sizeof("foo"), &foo); /* (*foo)->type is the type and (*foo)->value is the value */ } --- php3_write() { pval newval; newval.type = ...; newval.value = ...; _php3_hash_update(ht, "bar", sizeof("bar"), &newval, sizeof(pval), NULL); } php4_write() { pval *newval = (pval *) emalloc(sizeof(pval)); newval->refcount=1; newval->is_ref=0; newval->type = ...; newval->value = ...; _php3_hash_update(ht, "bar", sizeof("bar"), &newval, sizeof(pval *), NULL); } [2] Resources One of the 'cute' things about the reference counting support is that it completely eliminates the problem of resource leaking. A simple loop that included '$result = mysql_query(...)' in PHP leaked unless the user remembered to run mysql_free($result) at the end of the loop body, and nobody really did. In order to take advantage of the automatic resource deallocation upon destruction, there's virtually one small change you need to conduct. Change the result type of a resource that you want to destroy itself as soon as its no longer referenced (just about any resource I can think of) as IS_RESOURCE, instead of as IS_LONG. The rest is magic. A special treatment is required for SQL modules that follow MySQL's approach for having the link handle as an optional argument. Modules that follow the MySQL module model, store the last opened link in a global variable, that they use in case the user neglects to explicitly specify a link handle. Due to the way referenec counting works, this global reference is just like any other reference, and must increase that SQL link resource's reference count (otherwise, it will be closed prematurely). Simply, when you set the default link to a certain link, increase that link's reference count by calling zend_list_addref(). As always, the MySQL module is the one used to demonstrate 'new technology'. You can look around it and look for IS_RESOURCE, as well as zend_list_addref(), to see a clear example of how the new API should be used. [3] Thread safety issues I'm not going to say that Zend was designed with thread safety in mind, but from some point, we've decided upon several guidelines that would make the move to thread safety much, much easier. Generally, we've followed the PHP 3.1 approach of moving global variables to a structure, and encapsulating all global variable references within macros. There are three main differences: 1. We grouped related globals in a single structure, instead of grouping all globals in one structure. 2. We've used much, much shorter macro names to increase the readability of the source code. 3. Regardless of whether we're compiling in thread safe mode or not, all global variables are *always* stored in a structure. For example, you would never have a global variable 'foo', instead, it'll be a property of a global structure, for example, compiler_globals.foo. That makes development much, much easier, since your code will simply not compile unless you remember to put the necessary macro around foo. To write code that'll be thread safe in the future (when we release our thread safe memory manager and work on integrating it), you can take a look at zend_globals.h. Essentially, two sets of macros are defined, one for thread safe mode, and one for thread unsafe mode. All global references are encapsulated within ???G(varname), where ??? is the appropriate prefix for your structure (for example, so far we have CG(), EG() and AG(), which stand for the compiler, executor and memory allocator, respectively). When compiling with thread safety enabled, each function that makes use of a ???G() macro, must obtain the pointer to its copy of the structure. It can do so in one of two forms: 1. It can receive it as an argument. 2. It can fetch it. Obviously, the first method is preferable since it's much quicker. However, it's not always possible to send the structure all the way to a particular function, or it may simply bloat the code too much in some cases. Functions that receive the globals as an argument, should look like this: rettype functioname(???LS_D) <-- a function with no arguments rettype functioname(type arg1, ..., type argn ???LS_DC) <-- a funciton with arguments Calls to such functions should look like this: functionname(???LS_C) <-- a function with no arguments functionname(arg1, ..., argn ???LS_CC) <-- a function with arguments LS stands for 'Local Storage', _C stands for Call and _CC stands for Call Comma, _D stands for Declaration and _DC stands for Declaration Comma. Note that there's NO comma between the last argument and ???LS_DC or ???LS_CC. In general, every module that makes use of globals should use this approach if it plans to be thread safe. [4] Generalized INI support The code comes to solve several issues: a. The ugly long block of code in main.c that reads values from the cfg_hash into php3_ini. b. Get rid of php3_ini. The performance penalty of copying it around all the time in the Apache module probably wasn't too high, but psychologically, it annoyed me :) c. Get rid of the ugly code in mod_php4.c, that also reads values from Apache directives and puts them into the php3_ini structure. d. Generalize all the code so that you only have to add an entry in one single place and get it automatically supported in php3.ini, Apache, Win32 registry, runtime function ini_get() and ini_alter() and any future method we might have. e. Allow users to easily override *ANY* php3.ini value, except for ones they're not supposed to, of course. I'm happy to say that I think I pretty much reached all goals. php_ini.c implements a mechanism that lets you add your INI entry in a single place, with a default value in case there's no php3.ini value. What you get by using this mechanism: 1. Automatic initialization from php3.ini if available, or from the default value if not. 2. Automatic support in ini_alter(). That means a user can change the value for this INI entry at runtime, without you having to add in a single line of code, and definitely no additional function (for example, in PHP3, we had to add in special dedicated functions, like set_magic_quotes_runtime() or the likes - no need for that anymore). 3. Automatic support in Apache .conf files. 4. No need for a global php3_ini-like variable that'll store all that info. You can directly access each INI entry by name, in runtime. 'Sure, that's not revolutionary, it's just slow' is probably what some of you think - which is true, but, you can also register a callback function that is called each time your INI entry is changed, if you wish to store it in a cached location for intensive use. 5. Ability to access the current active value for a given INI entry, and the 'master' value. Of course, (2) and (3) are only applicable in some cases. Some entries shouldn't be overriden by users in runtime or through Apache .conf files - you can, of course, mark them as such. So, enough hype, how does it work. Essentially: static PHP_INI_MH(OnChangeBar); /* declare a message handler for a change in "bar" */ PHP_INI_BEGIN() PHP_INI_ENTRY("foo", "1", PHP_INI_ALL, NULL, NULL) PHP_INI_ENTRY("bar", "bah", PHP_INI_SYSTEM, OnChangeBar, NULL) PHP_INI_END() static PHP_INI_MH(OnChangeBar) { a_global_var_for_bar = new_value; return SUCCESS; } int whatever_minit(INIT_FUNC_ARGS) { ... REGISTER_INI_ENTRIES(); ... } int whatever_mshutdown(SHUTDOWN_FUNC_ARGS) { ... UNREGISTER_INI_ENTRIES(); ... } and that's it. Here's what it does. As you can probably guess, this code registers two INI entries - "foo" and "bar". They're given defaults "1" and "bah" respectively - note that all defaults are always given as strings. That doesn't reduce your ability to use integer values, simply specify them as strings. "foo" is marked so that it can be changed by anyone at any time (PHP_INI_ALL), whereas "foo" is marked so it can be changed only at startup in the php3.ini only, presumably, by the system administrator (PHP_INI_SYSTEM). When "foo" changes, no function is called. Access to it is done using the macros INI_INT("foo"), INI_FLT("foo") or INI_STR("foo"), which return a long, double or char * respectively (strings that are returned aren't duplicated - if they're manipulated, you must duplicate them first). You can also access the original value (the 'master' value, in case one of them was overriden by a user) using another pair of macros: INI_ORIG_INT("foo"), INI_ORIG_FLT("foo") and INI_ORIG_STR("foo"). When "bar" changes, a special message handler is called, OnBarChange(). Always declare those message handlers using PHP_INI_MH(), as they might change in the future. Message handlers are called as soon as an ini entry initializes or changes, and allow you to cache a certain INI value in a quick C structure. In this example, whenever "bar" changes, the new value is stored in a_global_var_for_bar, which is a global char * pointer, quickly accessible from other functions. Things get a bit more complicated when you want to implement a thread-safe module, but it's doable as well. Message handlers may return SUCCESS to acknowledge the new value, or FAILURE to reject it. That enables you to reject invalid values for some INI entries if you want. Finally, you can have a pointer passed to your message handler - that's the fifth argument to PHP_INI_ENTRY(). It is passed as mh_arg to the message handler. Remember that for certain values, there's really no reason to mess with a callback function. A perfect example for this are the syntax highlight colors, which no longer have a dedicated global C slot that stores them, but instead, are fetched from the php_ini hash on demand. "As always", for a perfect working example of this mechanism, consult functions/mysql.c. This module uses the new INI entry mechanism, and was also converted to be thread safe in general, and in its php_ini support in particular. Converting your modules to look like this for thread safety isn't a bad idea (not necessarily now, but in the long run).