mirror of
https://github.com/php/php-src.git
synced 2024-09-21 18:07:23 +00:00
- Add some documentation for ext_skel and a note about it's existence.
This commit is contained in:
parent
f79e3fa02f
commit
d09ec3261f
123
README.EXT_SKEL
Normal file
123
README.EXT_SKEL
Normal file
@ -0,0 +1,123 @@
|
||||
|
||||
WHAT IT IS
|
||||
|
||||
It's a tool for automatically creating the basic framework for a PHP module
|
||||
and writing C code handling arguments passed to your functions from a simple
|
||||
configuration file. See an example at the end of this file.
|
||||
|
||||
HOW TO USE IT
|
||||
|
||||
Very simple. First, cd do directory ext/ in PHP 4 sources. If you just need
|
||||
the basic framework and will be writing all the code in your functions
|
||||
yourself, you can now do './ext_skel your_module_name' and everything you
|
||||
need is placed in directory your_module_name. In fact, if you don't need to
|
||||
test the existence of any external header files, libraries or functions in
|
||||
them, the module is already almost ready to be compiled in PHP. Just remove
|
||||
3 comments in your_module_name/config.m4, cd back up to PHP sources top
|
||||
directory, and do './buildconf; ./configure --enable-your_module_name; make'.
|
||||
|
||||
But if you already have planned the overall scheme of your module, what
|
||||
functions it will contain, their return types and the arguments they take
|
||||
(a very good idea) and don't want to bother yourself with creating function
|
||||
definitions and handling arguments passed yourself, it's time to create a
|
||||
function definitions file, which you will give as the second argument to
|
||||
ext_skel.
|
||||
|
||||
FORMAT OF FUNCTION DEFINITIONS FILE
|
||||
|
||||
All the definitions must be on one line. In it's simplest form, it's just
|
||||
the function name, ie.
|
||||
|
||||
my_function
|
||||
|
||||
but then you'll be left with an almost empty function body without any
|
||||
argument handling.
|
||||
|
||||
Arguments are given in parenthesis after the function name, and are of
|
||||
the form 'argument_type argument_name'. Arguments are separated from each
|
||||
other with a comma and optional space. Argument_type can be one of int,
|
||||
double, string, array, object or mixed.
|
||||
|
||||
An optional argument is separated from the previous by an optional space,
|
||||
then '[' and of course comma and optional space, like all the other
|
||||
arguments. You should close a row of optional arguments with same amount of
|
||||
']'s as there where '['s. Currently, it does not harm if you forget to do it
|
||||
or there is a wrong amount of ']'s, but this may change in the future.
|
||||
|
||||
An example:
|
||||
|
||||
my_function(int arg1, int arg2 [, int arg3 [, int arg4]])
|
||||
|
||||
Arguments arg3 and arg4 are optional.
|
||||
|
||||
If possible, the function definition should also contain it's return type
|
||||
in front of the definition. It's not actually used for any C code generating
|
||||
purposes but PHP in-source documentation instead, and as such, very useful.
|
||||
It can be any of int, double, string, bool, array, object, resource, mixed
|
||||
or void.
|
||||
|
||||
The file must contain nothing else but function definitions, no comments or
|
||||
empty lines.
|
||||
|
||||
CURRENT LIMITATIONS AND BUGS
|
||||
|
||||
Only arguments of types int, float, string and array are handled. For other
|
||||
types you must write the code yourself. And for type mixed, it wouldn't even
|
||||
be possible to write anything, because only you know what to expect.
|
||||
|
||||
It doesn't yet handle correctly grouped optional arguments, ie. it thinks
|
||||
'type function(type arg1 [, type arg2, type arg3]' to actually be
|
||||
'type function(type arg1 [, type arg2 [, type arg3]]', so you have to
|
||||
manually correct the switch construct created. But it's nothing more than
|
||||
deleting a few 'case ?:' lines and fixing PHP in-source documentation proto.
|
||||
|
||||
It creates incorrect code to handle arguments passed to function when an
|
||||
optional argument is of type 'resource'.
|
||||
|
||||
EXAMPLE
|
||||
|
||||
The following _one_ line
|
||||
|
||||
bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
|
||||
|
||||
will create this function definition for you (note that there are a few
|
||||
question marks to be replaced by you, and you must of course add your own
|
||||
value definitions too):
|
||||
|
||||
/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y[, int color])
|
||||
*/
|
||||
PHP_FUNCTION(my_drawtext)
|
||||
{
|
||||
zval **image, **text, **font, **x, **y, **color;
|
||||
int argc;
|
||||
int image_id = -1;
|
||||
int font_id = -1;
|
||||
???LS_FETCH();
|
||||
|
||||
argc = ZEND_NUM_ARGS();
|
||||
if (argc < 5 || argc > 6 || zend_get_parameters_ex(argc, &image, &text, &font, &x, &y, &color) == FAILURE) {
|
||||
WRONG_PARAM_COUNT;
|
||||
}
|
||||
|
||||
ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???G());
|
||||
ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???G());
|
||||
|
||||
switch (argc) {
|
||||
case 6:
|
||||
convert_to_long_ex(color);
|
||||
/* Fall-through. */
|
||||
case 5:
|
||||
convert_to_long_ex(y);
|
||||
convert_to_long_ex(x);
|
||||
/* font: fetching resources already handled. */
|
||||
convert_to_string_ex(text);
|
||||
/* image: fetching resources already handled. */
|
||||
break;
|
||||
default:
|
||||
WRONG_PARAM_COUNT;
|
||||
}
|
||||
|
||||
php_error(E_WARNING, "my_drawtext: not yet implemented");
|
||||
}
|
||||
/* }}} */
|
||||
|
@ -107,8 +107,13 @@ fi
|
||||
|
||||
CREATING SOURCE FILES
|
||||
|
||||
[You are currently alone here. There are a lot of existing modules,
|
||||
use a simply module as a starting point and add your own code.]
|
||||
ext_skel can be of great help when creating the common code for all modules
|
||||
in PHP for you and also writing basic function definitions and C code for
|
||||
handling arguments passed to your functions. See README.EXT_SKEL for further
|
||||
information.
|
||||
|
||||
As for the rest, you are currently alone here. There are a lot of existing
|
||||
modules, use a simple module as a starting point and add your own code.
|
||||
|
||||
|
||||
CREATING THE SELF-CONTAINED EXTENSION
|
||||
|
Loading…
Reference in New Issue
Block a user