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