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 6WHAT 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 12HOW 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 The definition of PHP_MODULE_NAME_VERSION will be present in the 35 php_module_name.h and injected into the zend_module_entry definition. This 36 is required by the PECL website for the version string conformity checks 37 against package.xml 38 39 But if you already have planned the overall scheme of your module, what 40 functions it will contain, their return types and the arguments they take 41 (a very good idea) and don't want to bother yourself with creating function 42 definitions and handling arguments passed yourself, it's time to create a 43 function definitions file, which you will give as an argument to ext_skel 44 with option 45 46 --proto=filename. 47 48SOURCE AND HEADER FILE NAME 49 50 ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source 51 and header files. Keep these names. 52 53 Module functions (User functions) must be named 54 55 module_name_function() 56 57 When you need to expose module functions to other modules, expose functions 58 strictly needed by others. Exposed internal function must be named 59 60 php_module_name_function() 61 62 See also CODING_STANDARDS. 63 64 65FORMAT OF FUNCTION DEFINITIONS FILE 66 67 All the definitions must be on one line. In it's simplest form, it's just 68 the function name, e.g. 69 70 module_name_function 71 72 but then you'll be left with an almost empty function body without any 73 argument handling. 74 75 Arguments are given in parenthesis after the function name, and are of 76 the form 'argument_type argument_name'. Arguments are separated from each 77 other with a comma and optional space. Argument_type can be one of int, 78 bool, double, float, string, array, object or mixed. 79 80 An optional argument is separated from the previous by an optional space, 81 then '[' and of course comma and optional space, like all the other 82 arguments. You should close a row of optional arguments with same amount of 83 ']'s as there where '['s. Currently, it does not harm if you forget to do it 84 or there is a wrong amount of ']'s, but this may change in the future. 85 86 An additional short description may be added after the parameters. 87 If present it will be filled into the 'proto' header comments in the stubs 88 code and the <refpurpose> tag in the XML documentation. 89 90 An example: 91 92 module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]]) 93 94 Arguments arg1 and arg2 are required. 95 Arguments arg3 and arg4 are optional. 96 97 If possible, the function definition should also contain it's return type 98 in front of the definition. It's not actually used for any C code generating 99 purposes but PHP in-source documentation instead, and as such, very useful. 100 It can be any of int, double, string, bool, array, object, resource, mixed 101 or void. 102 103 The file must contain nothing else but function definitions, no comments or 104 empty lines. 105 106OTHER OPTIONS 107 108 --no-help 109 110 By default, ext_skel creates both comments in the source code and a test 111 function to help first time module writers to get started and testing 112 configuring and compiling their module. This option turns off all such things 113 which may just annoy experienced PHP module coders. Especially useful with 114 115 --stubs=file 116 117 which will leave out also all module specific stuff and write just function 118 stubs with function value declarations and passed argument handling, and 119 function entries and definitions at the end of the file, for copying and 120 pasting into an already existing module. 121 122 --xml[=file] 123 124 Creates the basics for phpdoc .xml file. 125 126 --full-xml 127 128 Not implemented yet. When or if there will ever be created a framework for 129 self-contained extensions to use phpdoc system for their documentation, this 130 option enables it on the created xml file. 131 132CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES 133 134 Only arguments of types int, bool, double, float, string and array are 135 handled. For other types you must write the code yourself. And for type 136 mixed, it wouldn't even be possible to write anything, because only you 137 know what to expect. 138 139 It can't handle correctly, and probably never will, variable list of 140 of arguments. (void foo(int bar [, ...]) 141 142 Don't trust the generated code too much. It tries to be useful in most of 143 the situations you might encounter, but automatic code generation will never 144 beat a programmer who knows the real situation at hand. ext_skel is generally 145 best suited for quickly generating a wrapper for c-library functions you 146 might want to have available in PHP too. 147 148 This program doesn't have a --help option. It has --no-help instead. 149 150EXAMPLE 151 152 The following _one_ line 153 154 bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) 155 156 will create this function definition for you (note that there are a few 157 question marks to be replaced by you, and you must of course add your own 158 value definitions too): 159 160/* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) 161 */ 162PHP_FUNCTION(module_name_drawtext) 163{ 164 char *text = NULL; 165 int argc = ZEND_NUM_ARGS(); 166 int image_id = -1; 167 size_t text_len; 168 int font_id = -1; 169 zend_long x; 170 zend_long y; 171 zend_long color; 172 zval *image = NULL; 173 zval *font = NULL; 174 175 if (zend_parse_parameters(argc, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE) 176 return; 177 178 if (image) { 179 ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id); 180 } 181 if (font) { 182 ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id); 183 } 184 185 php_error(E_WARNING, "module_name_drawtext: not yet implemented"); 186} 187/* }}} */ 188
