php-src/apidoc-zend.txt

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_php3.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).