xref: /PHP-5.6/README.PARAMETER_PARSING_API (revision ed2e84e2)
1New parameter parsing functions
2===============================
3
4It should be easier to parse input parameters to an extension function.
5Hence, borrowing from Python's example, there are now a set of functions
6that given the string of type specifiers, can parse the input parameters
7and store the results in the user specified variables. This avoids most
8of the IS_* checks and convert_to_* conversions. The functions also
9check for the appropriate number of parameters, and try to output
10meaningful error messages.
11
12
13Prototypes
14----------
15/* Implemented. */
16int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);
17int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);
18
19The zend_parse_parameters() function takes the number of parameters
20passed to the extension function, the type specifier string, and the
21list of pointers to variables to store the results in. The _ex() version
22also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
23be used as 'flags' to specify that the function should operate quietly
24and not output any error messages.
25
26Both functions return SUCCESS or FAILURE depending on the result.
27
28The auto-conversions are performed as necessary. Arrays, objects, and
29resources cannot be auto-converted.
30
31PHP 5.5 includes a new function:
32
33int zend_parse_parameter(int flags, int arg_num TSRMLS_DC, zval **arg, const char *spec, ...);
34
35This function behaves like zend_parse_parameters_ex() except that instead of
36reading the arguments from the stack, it receives a single zval to convert
37(passed with double indirection). The passed zval may be changed in place as
38part of the conversion process.
39
40See also https://wiki.php.net/rfc/zpp_improv#expose_zend_parse_arg_as_zend_parse_parameter
41
42
43Type specifiers
44---------------
45 The following list shows the type specifier, its meaning and the parameter
46 types that need to be passed by address. All passed parameters are set
47 if the PHP parameter is non optional and untouched if optional and the
48 parameter is not present. The only exception is O where the zend_class_entry*
49 has to be provided on input and is used to verify the PHP parameter is an
50 instance of that class.
51
52 a  - array (zval*)
53 A  - array or object (zval *)
54 b  - boolean (zend_bool)
55 C  - class (zend_class_entry*)
56 d  - double (double)
57 f  - function or array containing php method call info (returned as
58      zend_fcall_info and zend_fcall_info_cache)
59 h  - array (returned as HashTable*)
60 H  - array or HASH_OF(object) (returned as HashTable*)
61 l  - long (long)
62 L  - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (long)
63 o  - object of any type (zval*)
64 O  - object of specific type given by class entry (zval*, zend_class_entry)
65 p  - valid path (string without null bytes in the middle) and its length (char*, int)
66 r  - resource (zval*)
67 s  - string (with possible null bytes) and its length (char*, int)
68 z  - the actual zval (zval*)
69 Z  - the actual zval (zval**)
70 *  - variable arguments list (0 or more)
71 +  - variable arguments list (1 or more)
72
73 The following characters also have a meaning in the specifier string:
74    | - indicates that the remaining parameters are optional, they
75        should be initialized to default values by the extension since they
76        will not be touched by the parsing function if they are not
77        passed to it.
78    / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
79    ! - the parameter it follows can be of specified type or NULL. If NULL is
80		passed and the output for such type is a pointer, then the output
81		pointer is set to a native NULL pointer.
82		For 'b', 'l' and 'd', an extra argument of type zend_bool* must be
83		passed after the corresponding bool*, long* or double* arguments,
84		respectively. A non-zero value will be written to the zend_bool iif a
85		PHP NULL is passed.
86
87
88Note on 64bit compatibility
89---------------------------
90Please do not forget that int and long are two different things on 64bit
91OSes (int is 4 bytes and long is 8 bytes), so make sure you pass longs to "l"
92and ints to strings length (i.e. for "s" you need to pass char * and int),
93not the other way round!
94Remember: "l" is the only case when you need to pass long (and that's why
95it's "l", not "i" btw).
96
97Both mistakes cause memory corruptions and segfaults on 64bit OSes:
981)
99  char *str;
100  long str_len; /* XXX THIS IS WRONG!! Use int instead. */
101  zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &str_len)
102
1032)
104  int num; /* XXX THIS IS WRONG!! Use long instead. */
105  zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num)
106
107If you're in doubt, use check_parameters.php script to the parameters
108and their types (it can be found in ./scripts/dev/ directory of PHP sources):
109
110# php ./scripts/dev/check_parameters.php /path/to/your/sources/
111
112
113Examples
114--------
115/* Gets a long, a string and its length, and a zval */
116long l;
117char *s;
118int s_len;
119zval *param;
120if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
121                          &l, &s, &s_len, &param) == FAILURE) {
122    return;
123}
124
125
126/* Gets an object of class specified by my_ce, and an optional double. */
127zval *obj;
128double d = 0.5;
129zend_class_entry *my_ce;
130if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
131                          &obj, my_ce, &d) == FAILURE) {
132    return;
133}
134
135
136/* Gets an object or null, and an array.
137   If null is passed for object, obj will be set to NULL. */
138zval *obj;
139zval *arr;
140if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
141                          &obj, &arr) == FAILURE) {
142    return;
143}
144
145
146/* Gets a separated array which can also be null. */
147zval *arr;
148if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
149                          &arr) == FAILURE) {
150    return;
151}
152
153/* Get either a set of 3 longs or a string. */
154long l1, l2, l3;
155char *s;
156/*
157 * The function expects a pointer to a integer in this case, not a long
158 * or any other type.  If you specify a type which is larger
159 * than a 'int', the upper bits might not be initialized
160 * properly, leading to random crashes on platforms like
161 * Tru64 or Linux/Alpha.
162 */
163int length;
164
165if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
166                             "lll", &l1, &l2, &l3) == SUCCESS) {
167    /* manipulate longs */
168} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
169                                    "s", &s, &length) == SUCCESS) {
170    /* manipulate string */
171} else {
172    /* output error */
173
174    return;
175}
176
177
178/* Function that accepts only varargs (0 or more) */
179
180int i, num_varargs;
181zval ***varargs = NULL;
182
183
184if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "*", &varargs, &num_varargs) == FAILURE) {
185    return;
186}
187
188for (i = 0; i < num_varargs; i++) {
189    /* do something with varargs[i] */
190}
191
192if (varargs) {
193    efree(varargs);
194}
195
196
197/* Function that accepts a string, followed by varargs (1 or more) */
198
199char *str;
200int str_len;
201int i, num_varargs;
202zval ***varargs = NULL;
203
204if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
205    return;
206}
207
208for (i = 0; i < num_varargs; i++) {
209    /* do something with varargs[i] */
210}
211
212if (varargs) {
213    efree(varargs);
214}
215
216
217/* Function that takes an array, followed by varargs, and ending with a long */
218long num;
219zval *array;
220int i, num_varargs;
221zval ***varargs = NULL;
222
223if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
224    return;
225}
226
227for (i = 0; i < num_varargs; i++) {
228    /* do something with varargs[i] */
229}
230
231if (varargs) {
232    efree(varargs);
233}
234
235