--- /dev/null
+
+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");
+}
+/* }}} */
+
projects / php / commitdiff