release/src/router/php/README.EXT_SKEL

   1 (NOTE: you may also want to take a look at the pear package
   2              PECL_Gen, a PHP-only alternative for this script that
   3                          supports way more extension writing tasks and is
   4                          supposed to replace ext_skel completely in the long run ...)
   5
   6 WHAT IT IS
   7
   8   It's a tool for automatically creating the basic framework for a PHP module
   9   and writing C code handling arguments passed to your functions from a simple
  10   configuration file. See an example at the end of this file.
  11
  12 HOW TO USE IT
  13
  14   Very simple. First, change to the ext/ directory of the PHP 4 sources. If
  15   you just need the basic framework and will be writing all the code in your
  16   functions yourself, you can now do
  17
  18    ./ext_skel --extname=module_name
  19
  20   and everything you need is placed in directory module_name.
  21
  22   [ Note that GNU awk is likely required for this script to work.  Debian
  23     systems seem to default to using mawk, so you may need to change the
  24     #! line in skeleton/create_stubs and the cat $proto | awk line in
  25     ext_skel to use gawk explicitly. ]
  26
  27   If you don't need to test the existence of any external header files,
  28   libraries or functions in them, the module is already almost ready to be
  29   compiled in PHP.  Just remove 3 comments in your_module_name/config.m4,
  30   change back up to PHP sources top directory, and do
  31
  32     ./buildconf; ./configure --enable-module_name; make
  33
  34   But if you already have planned the overall scheme of your module, what
  35   functions it will contain, their return types and the arguments they take
  36   (a very good idea) and don't want to bother yourself with creating function
  37   definitions and handling arguments passed yourself, it's time to create a
  38   function definitions file, which you will give as an argument to ext_skel
  39   with option
  40
  41     --proto=filename.
  42
  43 FORMAT OF FUNCTION DEFINITIONS FILE
  44
  45   All the definitions must be on one line. In it's simplest form, it's just
  46   the function name, e.g.
  47
  48     my_function
  49
  50   but then you'll be left with an almost empty function body without any
  51   argument handling.
  52
  53   Arguments are given in parenthesis after the function name, and are of
  54   the form 'argument_type argument_name'. Arguments are separated from each
  55   other with a comma and optional space. Argument_type can be one of int,
  56   bool, double, float, string, array, object or mixed.
  57
  58   An optional argument is separated from the previous by an optional space,
  59   then '[' and of course comma and optional space, like all the other
  60   arguments. You should close a row of optional arguments with same amount of
  61   ']'s as there where '['s. Currently, it does not harm if you forget to do it
  62   or there is a wrong amount of ']'s, but this may change in the future.
  63
  64         An additional short description may be added after the parameters.
  65   If present it will be filled into the 'proto' header comments in the stubs
  66   code and the <refpurpose> tag in the XML documentation.
  67
  68   An example:
  69
  70     my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st
  71
  72   Arguments arg3 and arg4 are optional.
  73
  74   If possible, the function definition should also contain it's return type
  75   in front of the definition. It's not actually used for any C code generating
  76   purposes but PHP in-source documentation instead, and as such, very useful.
  77   It can be any of int, double, string, bool, array, object, resource, mixed
  78   or void.
  79
  80   The file must contain nothing else but function definitions, no comments or
  81   empty lines.
  82
  83 OTHER OPTIONS
  84
  85     --no-help
  86
  87   By default, ext_skel creates both comments in the source code and a test
  88   function to help first time module writers to get started and testing
  89   configuring and compiling their module. This option turns off all such things
  90   which may just annoy experienced PHP module coders. Especially useful with
  91
  92     --stubs=file
  93
  94   which will leave out also all module specific stuff and write just function
  95   stubs with function value declarations and passed argument handling, and
  96   function entries and definitions at the end of the file, for copying and
  97   pasting into an already existing module.
  98
  99     --xml[=file]
 100
 101   Creates the basics for phpdoc .xml file.
 102
 103     --full-xml
 104
 105   Not implemented yet. When or if there will ever be created a framework for
 106   self-contained extensions to use phpdoc system for their documentation, this
 107   option enables it on the created xml file.
 108
 109 CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
 110
 111   Only arguments of types int, bool, double, float, string and array are
 112   handled. For other types you must write the code yourself. And for type
 113   mixed, it wouldn't even be possible to write anything, because only you
 114   know what to expect.
 115
 116   It can't handle correctly, and probably never will, variable list of
 117   of arguments. (void foo(int bar [, ...])
 118
 119   Don't trust the generated code too much. It tries to be useful in most of
 120   the situations you might encounter, but automatic code generation will never
 121   beat a programmer who knows the real situation at hand. ext_skel is generally
 122   best suited for quickly generating a wrapper for c-library functions you
 123   might want to have available in PHP too.
 124
 125   This program doesn't have a --help option. It has --no-help instead.
 126
 127 EXAMPLE
 128
 129   The following _one_ line
 130
 131   bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
 132
 133   will create this function definition for you (note that there are a few
 134   question marks to be replaced by you, and you must of course add your own
 135   value definitions too):
 136
 137 /* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
 138     */
 139 PHP_FUNCTION(my_drawtext)
 140 {
 141     char *text = NULL;
 142     int argc = ZEND_NUM_ARGS();
 143     int image_id = -1;
 144     int text_len;
 145     int font_id = -1;
 146     long x;
 147     long y;
 148     long color;
 149     zval *image = NULL;
 150     zval *font = NULL;
 151
 152     if (zend_parse_parameters(argc TSRMLS_CC, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE)
 153         return;
 154
 155     if (image) {
 156         ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
 157     }
 158     if (font) {
 159         ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
 160     }
 161
 162     php_error(E_WARNING, "my_drawtext: not yet implemented");
 163 }
 164 /* }}} */
 165