mirrors/php-src
0
0
Fork 0
mirror of https://github.com/php/php-src.git synced 2024-11-24 10:24:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
9712a4b3c8
php-src/apidoc.txt
Sascha Schumann 62a9f2137c I think that is the preferred way as of now
1999-05-28 18:51:51 +00:00

493 lines
20 KiB
Plaintext
Raw Blame History

PHP Version 3.0 API Documentation
Table of Contents
-----------------
1. Function Prototype
2. Function Arguments
3. Variable number of function arguments
4. Using the function arguments
5. Memory management in functions
6. Setting variables in the symbol table
7. Returning values from functions
8. Returning 'complex' values from functions (arrays or objects)
9. Using the resource list
10. Using the persistent resource table
11. Adding runtime configuration directives
-----------------
1. Function Prototype
All functions look like this:
PHP_FUNCTION(foo) {
}
Even if your function doesn't take any arguments, this is how it is
called.
-----------------
2. Function Arguments
Arguments are always of type pval. This type contains a union which
has the actual type of the argument. So, if your function takes two
arguments, you would do something like the following at the top of your
function:
pval *arg1, *arg2;
if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) {
WRONG_PARAM_COUNT;
}
NOTE: Arguments can be passed either by value or by reference. In both
cases you will need to pass &(pval *) to getParameters. If you want to
check if the n'th parameter was sent to you by reference or not, you can
use the function, ParameterPassedByReference(ht,n). It will return either
1 or 0.
When you change any of the passed parameters, whether they are sent by
reference or by value, you can either start over with the parameter by
calling pval_destructor on it, or if it's an ARRAY you want to add to,
you can use functions similar to the ones in internal_functions.h which
manipulate return_value as an ARRAY.
Also if you change a parameter to IS_STRING make sure you first assign
the new estrdup'ed string and the string length, and only later change the
type to IS_STRING. If you change the string of a parameter which already
IS_STRING or IS_ARRAY you should run pval_destructor on it first.
-----------------
3. Variable number of function arguments
A function can take a variable number of arguments. If your function can
take either 2 or 3 arguments, use the following:
pval *arg1, *arg2, *arg3;
int arg_count = ARG_COUNT(ht);
if (arg_count<2 || arg_count>3 ||
getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) {
WRONG_PARAM_COUNT;
}
------------------
4. Using the function arguments
The type of each argument is stored in the pval type field:
This type can be any of the following:
IS_STRING String
IS_DOUBLE Double-precision floating point
IS_LONG Long
IS_ARRAY Array
IS_EMPTY ??
IS_USER_FUNCTION ??
IS_INTERNAL_FUNCTION ?? (if some of these cannot be passed to a
function - delete)
IS_CLASS ??
IS_OBJECT ??
If you get an argument of one type and would like to use it as another,
or if you just want to force the argument to be of a certain type, you
can use one of the following conversion functions:
convert_to_long(arg1);
convert_to_double(arg1);
convert_to_string(arg1);
convert_to_boolean_long(arg1); If the string is "" or "0" it
becomes 0, 1 otherwise
convert_string_to_number(arg1); Converts string to either LONG or
DOUBLE depending on string
These function all do in-place conversion. They do not return anything.
The actual argument is stored in a union.
For type IS_STRING, use arg1->value.str.val
IS_LONG arg1->value.lval
IS_DOUBLE arg1->value.dval
-------------------
5. Memory management in functions
Any memory needed by a function should be allocated with either emalloc()
or estrdup(). These are memory handling abstraction functions that look
and smell like the normal malloc() and strdup() functions. Memory should
be freed with efree().
There are two kinds of memory in this program. Memory which is returned
to the parser in a variable and memory which you need for temporary
storage in your internal function. When you assign a string to a
variable which is returned to the parser you need to make sure you first
allocate the memory with either emalloc or estrdup. This memory
should NEVER be freed by you, unless you later, in the same function
overwrite your original assignment (this kind of programming practice is
not good though).
For any temporary/permanent memory you need in your functions/library you
should use the three emalloc(), estrdup(), and efree() functions. They
behave EXACTLY like their counterpart functions. Anything you emalloc()
or estrdup() you have to efree() at some point or another, unless it's
supposed to stick around until the end of the program, otherwise there
will be a memory leak. The meaning of "the functions behave exactly like
their counterparts" is if you efree() something which was not
emalloc()'ed nor estrdup()'ed you might get a segmentation fault. So
please take care and free all of your wasted memory. One of the biggest
improvements in PHP 3.0 will hopefully be the memory management.
If you compile with "-DDEBUG", PHP3 will print out a list of all
memory that was allocated using emalloc() and estrdup() but never
freed with efree() when it is done running the specified script.
-------------------
6. Setting variables in the symbol table
A number of macros are available which make it easier to set a variable
in the symbol table:
SET_VAR_STRING(name,value) **
SET_VAR_DOUBLE(name,value)
SET_VAR_LONG(name,value)
** Be careful here. The value part must be malloc'ed manually because
the memory management code will try to free this pointer later. Do
not pass statically allocated memory into a SET_VAR_STRING
Symbol tables in PHP 3.0 are implemented as hash tables. At any given time,
&symbol_table is a pointer to the 'main' symbol table, and active_symbol_table
points to the currently active symbol table (these may be identical like in
startup, or different, if you're inside a function).
The following examples use 'active_symbol_table'. You should replace it with
&symbol_table if you specifically want to work with the 'main' symbol table.
Also, the same funcions may be applied to arrays, as explained below.
* To check whether a variable named $foo already exists in a symbol table:
if (hash_exists(active_symbol_table,"foo",sizeof("foo"))) { exists... }
else { doesn't exist }
* If you also need to get the type of the variable, you can use:
hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue);
check(pvalue.type);
Arrays in PHP 3.0 are implemented using the same hashtables as symbol tables.
This means the two above functions can also be used to check variables
inside arrays.
If you want to define a new array in a symbol table, you should do this:
1. Possibly check it exists and abort, using hash_exists()
or hash_find().
2. Code:
pval arr;
if (array_init(&arr) == FAILURE) { failed... };
hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL);
This code declares a new array, named $foo, in the active symbol table.
This array is empty.
Here's how to add new entries to it:
pval entry;
entry.type = IS_LONG;
entry.value.lval = 5;
hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL); /* defines $foo["bar"] = 5 */
hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL); /* defines $foo[7] = 5 */
hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); /* defines the next free place in $foo[],
* $foo[8], to be 5 (works like php2)
*/
If you'd like to modify a value that you inserted to a hash, you must first retreive it from the hash. To
prevent that overhead, you can supply a pval ** to the hash add function, and it'll be updated with the
pval * address of the inserted element inside the hash. If that value is NULL (like in all of the
above examples) - that parameter is ignored.
hash_next_index_insert() works more or less using the same logic
"$foo[] = bar;" works in PHP 2.0.
If you are building an array to return from a function, you can initialize
the array just like above by doing:
if (array_init(return_value) == FAILURE) { failed...; }
and then adding values with the helper functions:
add_next_index_long(return_value,long_value);
add_next_index_double(return_value,double_value);
add_next_index_string(return_value,estrdup(string_value));
Of course, if the adding isn't done right after the array
initialization, you'd probably have to look for the array first:
pval *arr;
if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... }
else { use arr->value.ht... }
Note that hash_find receives a pointer to a pval pointer, and
not a pval pointer.
Just about any hash function returns SUCCESS or FAILURE (except for
hash_exists() that returns a boolean truth value).
-------------------
7. Returning 'simple' values from functions (integers, floats or strings)
A number of macros are available to make it easier to return things from
functions:
These set the return value and return from the function:
RETURN_FALSE
RETURN_TRUE
RETURN_LONG(l)
RETURN_STRING(s,dup) If dup is true, duplicates the string
RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l).
RETURN_DOUBLE(d)
These only set the return value:
RETVAL_FALSE
RETVAL_TRUE
RETVAL_LONG(l)
RETVAL_STRING(s,dup) If dup is true, duplicates the string
RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l).
RETVAL_DOUBLE(d)
The string macros above will all estrdup() the passed 's' argument,
so you can safely free the argument after calling the macro, or
alternatively use statically allocated memory.
If your function returns boolean success/error responses, always use
RETURN_TRUE and RETURN_FALSE respectively.
-------------------
8. Returning 'complex' values from functions (arrays or objects)
Your function can also return a complex data type such as an object
or an array.
Returning an object:
1. Call object_init(return_value).
2. Fill it up with values:
add_property_long(return_value,property_name,l) Add a property named 'property_name', of type long, equals to 'l'
add_property_double(return_value,property_name,d) Same, only a double
add_property_string(return_value,property_name,str) Same, only a string
add_property_stringl(return_value,property_name,str,l) Add a property named 'property_name', of type string, string is 'str' with length 'l'
3. Possibly, register functions for this object. In order to
obtain values from the object, the function would have to fetch
"this" from the active_symbol_table. Its type should be IS_OBJECT,
and it's basically a regular hash table (i.e., you can use regular
hash functions on .value.ht). The actual registration of the
function can be done using:
add_method(return_value,function_name,function_ptr)
Returning an array:
1. Call array_init(return_value).
2. Fill it up with values:
add_assoc_long(return_value,key,l) add associative entry with key 'key' and long value 'l'
add_assoc_double(return_value,key,d)
add_assoc_string(return_value,key,str)
add_assoc_stringl(return_value,key,str,length) specify the string length
add_index_long(return_value,index,l) add entry in index 'index' with long value 'l'
add_index_double(return_value,index,d)
add_index_string(return_value,index,str)
add_index_stringl(return_value,index,str,length) specify the string length
add_next_index_long(return_value,l) add an array entry in the next free offset with long value 'l'
add_next_index_double(return_value,d)
add_next_index_string(return_value,str)
add_next_index_stringl(return_value,str,length) specify the string length
-------------------
9. Using the resource list
PHP 3.0 has a standard way of dealing with various types of resources,
that replaces all of the local linked lists in PHP 2.0.
Available functions:
php3_list_insert(ptr, type) returns the 'id' of the newly inserted resource
php3_list_delete(id) delete the resource with the specified id
php3_list_find(id,*type) returns the pointer of the resource with the specified id, updates 'type' to the resource's type
Typically, these functions are used for SQL drivers but they can be
used for anything else, and are used, for instance, for maintaining
file descriptors.
Typical list code would look like this:
Adding a new resource:
RESOURCE *resource;
...allocate memory for resource and acquire resource...
/* add a new resource to the list */
return_value->value.lval = php3_list_insert((void *) resource, LE_RESOURCE_TYPE);
return_value->type = IS_LONG;
Using an existing resource:
pval *resource_id;
RESOURCE *resource;
int type;
convert_to_long(resource_id);
resource = php3_list_find(resource_id->value.lval, &type);
if (type != LE_RESOURCE_TYPE) {
php3_error(E_WARNING,"resource index %d has the wrong type",resource_id->value.lval);
RETURN_FALSE;
}
...use resource...
Deleting an existing resource:
pval *resource_id;
RESOURCE *resource;
int type;
convert_to_long(resource_id);
php3_list_delete(resource_id->value.lval);
The resource types should be registered in php3_list.h, in enum
list_entry_type. In addition, one should add shutdown code for any
new resource type defined, in list.c's list_entry_destructor() (even if
you don't have anything to do on shutdown, you must add an empty case).
-------------------
10. Using the persistent resource table
PHP 3.0 has a standard way of storing persistent resources (i.e.,
resources that are kept in between hits). The first module to use
this feature was the MySQL module, and mSQL followed it, so one can
get the general impression of how a persistent resource should be
used by reading mysql.c. The functions you should look at are:
php3_mysql_do_connect()
php3_mysql_connect()
php3_mysql_pconnect()
The general idea of persistence modules is this:
1. Code all of your module to work with the regular resource list
mentioned in section (9).
2. Code extra connect functions that check if the resource already
exists in the persistent resource list. If it does, register it
as in the regular resource list as a pointer to the persistent
resource list (because of 1., the rest of the code
should work immediately). If it doesn't, then create it, add it
to the persistent resource list AND add a pointer to it from the
regular resource list, so all of the code would work since it's
in the regular resource list, but on the next connect, the
resource would be found in the persistent resource list and be
used without having to recreate it.
You should register these resources with a different type (e.g.
LE_MYSQL_LINK for non-persistent link and LE_MYSQL_PLINK for
a persistent link).
If you read mysql.c, you'll notice that except for the more complex
connect function, nothing in the rest of the module has to be changed.
The very same interface exists for the regular resource list and the
persistent resource list, only 'list' is replaced with 'plist':
php3_plist_insert(ptr, type) returns the 'id' of the newly inserted resource
php3_plist_delete(id) delete the resource with the specified id
php3_plist_find(id,*type) returns the pointer of the resource with the specified id, updates 'type' to the resource's type
However, it's more than likely that these functions would prove
to be useless for you when trying to implement a persistent module.
Typically, one would want to use the fact that the persistent resource
list is really a hash table. For instance, in the MySQL/mSQL modules,
when there's a pconnect() call (persistent connect), the function
builds a string out of the host/user/passwd that were passed to the
function, and hashes the SQL link with this string as a key. The next
time someone calls a pconnect() with the same host/user/passwd, the
same key would be generated, and the function would find the SQL link
in the persistent list.
Until further documented, you should look at mysql.c or msql.c to
see how one should use the plist's hash table abilities.
One important thing to note: resources going into the persistent
resource list must *NOT* be allocated with PHP's memory manager, i.e.,
they should NOT be created with emalloc(), estrdup(), etc. Rather,
one should use the regular malloc(), strdup(), etc. The reason for
this is simple - at the end of the request (end of the hit), every
memory chunk that was allocated using PHP's memory manager is deleted.
Since the persistent list isn't supposed to be erased at the end
of a request, one mustn't use PHP's memory manager for allocating
resources that go to it.
Shutting down persistent resources:
When you register resource that's going to be in the persistent list,
you should add destructors to it both in the non-persistent list
and in the persistent list.
The destructor in the non-persistent list destructor shouldn't do anything.
The one in the persistent list destructor should properly free any
resources obtained by that type (e.g. memory, SQL links, etc). Just like
with the non-persistent resources, you *MUST* add destructors for every
resource, even it requires no destructotion and the destructor would
be empty.
Remember, since emalloc() and friends aren't to be used in conjunction
with the persistent list, you mustn't use efree() here either.
-------------------
11. Adding runtime configuration directives
Many of the features of PHP3 can be configured at runtime. These
configuration directives can appear in either the designated php3.ini
file, or in the case of the Apache module version in the Apache .conf
files. The advantage of having them in the Apache .conf files is that
they can be configured on a per-directory basis. This means that one
directory may have a certain safemodeexecdir for example, while another
directory may have another. This configuration granularity is especially
handy when a server supports multiple virtual hosts.
The steps required to add a new directive:
1. Add directive to php3_ini_structure struct in mod_php4.h.
2. In main.c, edit the php3_module_startup function and add the
appropriate cfg_get_string() or cfg_get_long() call.
3. Add the directive, restrictions and a comment to the php3_commands
structure in mod_php4.c. Note the restrictions part. RSRC_CONF are
directives that can only be present in the actual Apache .conf files.
Any OR_OPTIONS directives can be present anywhere, include normal
.htaccess files.
4. In either php3take1handler() or php3flaghandler() add the appropriate
entry for your directive.
5. In the configuration section of the _php3_info() function in
functions/info.c you need to add your new directive.
6. And last, you of course have to use your new directive somewhere.
It will be addressable as php3_ini.directive
Reference in New Issue View Git Blame Copy Permalink