xref: /PHP-5.4/README.EXT_SKEL (revision d65ddb63)
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    int text_len;
168    int font_id = -1;
169    long x;
170    long y;
171    long color;
172    zval *image = NULL;
173    zval *font = NULL;
174
175    if (zend_parse_parameters(argc TSRMLS_CC, "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
189