2003-06-30 00:07:18 +08:00
|
|
|
(NOTE: you may also want to take a look at the pear package
|
|
|
|
PECL_Gen, a PHP-only alternative for this script that
|
|
|
|
supports way more extension writing tasks and is
|
|
|
|
supposed to replace ext_skel completely in the long run ...)
|
|
|
|
|
|
|
|
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, change to the ext/ directory of the 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 --extname=module_name
|
|
|
|
|
|
|
|
and everything you need is placed in directory module_name.
|
|
|
|
|
|
|
|
[ Note that GNU awk is likely required for this script to work. Debian
|
|
|
|
systems seem to default to using mawk, so you may need to change the
|
|
|
|
#! line in skeleton/create_stubs and the cat $proto | awk line in
|
|
|
|
ext_skel to use gawk explicitly. ]
|
|
|
|
|
|
|
|
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,
|
|
|
|
change back up to PHP sources top directory, and do
|
|
|
|
|
|
|
|
./buildconf; ./configure --enable-module_name; make
|
|
|
|
|
2013-10-14 22:07:26 +08:00
|
|
|
The definition of PHP_MODULE_NAME_VERSION will be present in the
|
|
|
|
php_module_name.h and injected into the zend_module_entry definition. This
|
|
|
|
is required by the PECL website for the version string conformity checks
|
|
|
|
against package.xml
|
|
|
|
|
2003-06-30 00:07:18 +08:00
|
|
|
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 an argument to ext_skel
|
|
|
|
with option
|
|
|
|
|
|
|
|
--proto=filename.
|
|
|
|
|
2014-01-26 17:31:27 +08:00
|
|
|
SOURCE AND HEADER FILE NAME
|
|
|
|
|
|
|
|
./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source
|
|
|
|
and header files. Keep these names.
|
|
|
|
|
|
|
|
Module functions (User functions) must be named
|
|
|
|
|
|
|
|
module_name_function()
|
|
|
|
|
|
|
|
When you need to expose module functions to other modules, expose functions
|
|
|
|
strictly needed by others. Exposed internal function must be named
|
|
|
|
|
|
|
|
php_module_name_function()
|
|
|
|
|
|
|
|
See also CODING_STANDARDS.
|
|
|
|
|
|
|
|
|
2003-06-30 00:07:18 +08:00
|
|
|
FORMAT OF FUNCTION DEFINITIONS FILE
|
|
|
|
|
|
|
|
All the definitions must be on one line. In it's simplest form, it's just
|
|
|
|
the function name, e.g.
|
|
|
|
|
2014-01-26 17:31:27 +08:00
|
|
|
module_name_function
|
2003-06-30 00:07:18 +08:00
|
|
|
|
|
|
|
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,
|
|
|
|
bool, double, float, 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 additional short description may be added after the parameters.
|
|
|
|
If present it will be filled into the 'proto' header comments in the stubs
|
|
|
|
code and the <refpurpose> tag in the XML documentation.
|
|
|
|
|
|
|
|
An example:
|
|
|
|
|
2014-01-26 17:31:27 +08:00
|
|
|
module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]])
|
2003-06-30 00:07:18 +08:00
|
|
|
|
2014-01-27 05:50:11 +08:00
|
|
|
Arguments arg1 and arg2 are required.
|
2003-06-30 00:07:18 +08:00
|
|
|
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.
|
|
|
|
|
|
|
|
OTHER OPTIONS
|
|
|
|
|
|
|
|
--no-help
|
|
|
|
|
|
|
|
By default, ext_skel creates both comments in the source code and a test
|
|
|
|
function to help first time module writers to get started and testing
|
|
|
|
configuring and compiling their module. This option turns off all such things
|
|
|
|
which may just annoy experienced PHP module coders. Especially useful with
|
|
|
|
|
|
|
|
--stubs=file
|
|
|
|
|
|
|
|
which will leave out also all module specific stuff and write just function
|
|
|
|
stubs with function value declarations and passed argument handling, and
|
|
|
|
function entries and definitions at the end of the file, for copying and
|
|
|
|
pasting into an already existing module.
|
|
|
|
|
2008-06-20 01:59:35 +08:00
|
|
|
--xml[=file]
|
2003-06-30 00:07:18 +08:00
|
|
|
|
|
|
|
Creates the basics for phpdoc .xml file.
|
|
|
|
|
|
|
|
--full-xml
|
|
|
|
|
|
|
|
Not implemented yet. When or if there will ever be created a framework for
|
|
|
|
self-contained extensions to use phpdoc system for their documentation, this
|
|
|
|
option enables it on the created xml file.
|
|
|
|
|
|
|
|
CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
|
|
|
|
|
|
|
|
Only arguments of types int, bool, double, 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 can't handle correctly, and probably never will, variable list of
|
|
|
|
of arguments. (void foo(int bar [, ...])
|
|
|
|
|
|
|
|
Don't trust the generated code too much. It tries to be useful in most of
|
|
|
|
the situations you might encounter, but automatic code generation will never
|
|
|
|
beat a programmer who knows the real situation at hand. ext_skel is generally
|
|
|
|
best suited for quickly generating a wrapper for c-library functions you
|
|
|
|
might want to have available in PHP too.
|
|
|
|
|
|
|
|
This program doesn't have a --help option. It has --no-help instead.
|
|
|
|
|
|
|
|
EXAMPLE
|
|
|
|
|
|
|
|
The following _one_ line
|
|
|
|
|
2014-01-26 17:31:27 +08:00
|
|
|
bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color])
|
2003-06-30 00:07:18 +08:00
|
|
|
|
|
|
|
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):
|
|
|
|
|
2014-01-26 17:31:27 +08:00
|
|
|
/* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color])
|
2003-06-30 00:07:18 +08:00
|
|
|
*/
|
2014-01-26 17:31:27 +08:00
|
|
|
PHP_FUNCTION(module_name_drawtext)
|
2003-06-30 00:07:18 +08:00
|
|
|
{
|
2008-06-20 01:59:35 +08:00
|
|
|
char *text = NULL;
|
|
|
|
int argc = ZEND_NUM_ARGS();
|
|
|
|
int image_id = -1;
|
2015-01-21 15:56:51 +08:00
|
|
|
size_t text_len;
|
2008-06-20 01:59:35 +08:00
|
|
|
int font_id = -1;
|
2015-01-21 15:56:51 +08:00
|
|
|
zend_long x;
|
|
|
|
zend_long y;
|
|
|
|
zend_long color;
|
2008-06-20 01:59:35 +08:00
|
|
|
zval *image = NULL;
|
|
|
|
zval *font = NULL;
|
|
|
|
|
2016-02-18 14:36:01 +08:00
|
|
|
if (zend_parse_parameters(argc, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE)
|
2008-06-20 01:59:35 +08:00
|
|
|
return;
|
|
|
|
|
|
|
|
if (image) {
|
|
|
|
ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
|
|
|
|
}
|
|
|
|
if (font) {
|
|
|
|
ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
|
|
|
|
}
|
|
|
|
|
2014-01-26 17:31:27 +08:00
|
|
|
php_error(E_WARNING, "module_name_drawtext: not yet implemented");
|
2003-06-30 00:07:18 +08:00
|
|
|
}
|
|
|
|
/* }}} */
|
|
|
|
|