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 (bool)
71C  - class (zend_class_entry*)
72d  - double (double)
73f  - PHP callable containing php function/method call info (returned as
74     zend_fcall_info and zend_fcall_info_cache).
75     The FCC may be uninitialized if the callable is a trampoline.
76F  - PHP callable containing php function/method call info (returned as
77     zend_fcall_info and zend_fcall_info_cache).
78     The FCC will *always* be initialized, even if the callable is a trampoline.
79     A trampoline *must* be consumed or released with
80     zend_release_fcall_info_cache().
81h  - array (returned as HashTable*)
82H  - array or HASH_OF(object) (returned as HashTable*)
83l  - long (zend_long)
84n  - long or double (zval*)
85o  - object of any type (zval*)
86O  - object of specific type given by class entry (zval*, zend_class_entry)
87p  - valid path (string without null bytes in the middle) and its length (char*, size_t)
88P  - valid path (string without null bytes in the middle) as zend_string (zend_string*)
89r  - resource (zval*)
90s  - string (with possible null bytes) and its length (char*, size_t)
91S  - string (with possible null bytes) as zend_string (zend_string*)
92z  - the actual zval (zval*)
93*  - variable arguments list (0 or more)
94+  - variable arguments list (1 or more)
95```
96
97The following characters also have a meaning in the specifier string:
98
99* `|` - indicates that the remaining parameters are optional, they should be
100  initialized to default values by the extension since they will not be touched
101  by the parsing function if they are not passed to it.
102* `/` - use SEPARATE_ZVAL() on the parameter it follows
103* `!` - the parameter it follows can be of specified type or NULL. If NULL is
104  passed, and the output for such type is a pointer, then the output pointer is
105  set to a native NULL pointer. For 'b', 'l' and 'd', an extra argument of type
106  bool* must be passed after the corresponding bool*, zend_long* or
107  double* arguments, respectively. A non-zero value will be written to the
108  bool if a PHP NULL is passed.
109  For `f` use the ``ZEND_FCI_INITIALIZED(fci)`` macro to check if a callable
110  has been provided and ``!ZEND_FCI_INITIALIZED(fci)`` to check if a PHP NULL
111  is passed.
112
113## Note on 64bit compatibility
114
115Please note that since version 7 PHP uses `zend_long` as integer type and
116`zend_string` with `size_t` as length, so make sure you pass `zend_long`s to "l"
117and `size_t` to strings length (i.e. for "s" you need to pass char `*` and
118`size_t`), not the other way round!
119
120Both mistakes might cause memory corruptions and segfaults:
121
122* 1
123
124```c
125char *str;
126long str_len; /* XXX THIS IS WRONG!! Use size_t instead. */
127zend_parse_parameters(ZEND_NUM_ARGS(), "s", &str, &str_len)
128```
129
130* 2
131
132```c
133int num; /* XXX THIS IS WRONG!! Use zend_long instead. */
134zend_parse_parameters(ZEND_NUM_ARGS(), "l", &num)
135```
136
137If you're in doubt, use check_parameters.php script to the parameters and their
138types (it can be found in `./scripts/dev/` directory of PHP sources):
139
140```bash
141php ./scripts/dev/check_parameters.php /path/to/your/sources/
142```
143
144## Examples
145
146```c
147/* Gets a long, a string and its length, and a zval */
148zend_long l;
149char *s;
150size_t s_len;
151zval *param;
152if (zend_parse_parameters(ZEND_NUM_ARGS(), "lsz",
153                          &l, &s, &s_len, &param) == FAILURE) {
154    return;
155}
156
157/* Gets an object of class specified by my_ce, and an optional double. */
158zval *obj;
159double d = 0.5;
160zend_class_entry *my_ce;
161if (zend_parse_parameters(ZEND_NUM_ARGS(), "O|d",
162                          &obj, my_ce, &d) == FAILURE) {
163    return;
164}
165
166/* Gets an object or null, and an array.
167   If null is passed for object, obj will be set to NULL. */
168zval *obj;
169zval *arr;
170if (zend_parse_parameters(ZEND_NUM_ARGS(), "o!a",
171                          &obj, &arr) == FAILURE) {
172    return;
173}
174
175/* Gets a separated array which can also be null. */
176zval *arr;
177if (zend_parse_parameters(ZEND_NUM_ARGS(), "a/!",
178                          &arr) == FAILURE) {
179    return;
180}
181
182/* Get either a set of 3 longs or a string. */
183zend_long l1, l2, l3;
184char *s;
185/*
186 * The function expects a pointer to a size_t in this case, not a long
187 * or any other type. If you specify a type which is larger
188 * than a 'size_t', the upper bits might not be initialized
189 * properly, leading to random crashes on platforms like
190 * Tru64 or Linux/Alpha.
191 */
192size_t length;
193
194if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(),
195                             "lll", &l1, &l2, &l3) == SUCCESS) {
196    /* manipulate longs */
197} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(),
198                                    "s", &s, &length) == SUCCESS) {
199    /* manipulate string */
200} else {
201    /* output error */
202
203    return;
204}
205
206/* Function that accepts only varargs (0 or more) */
207
208int i, num_varargs;
209zval *varargs = NULL;
210
211if (zend_parse_parameters(ZEND_NUM_ARGS(), "*", &varargs, &num_varargs) == FAILURE) {
212    return;
213}
214
215for (i = 0; i < num_varargs; i++) {
216    /* do something with varargs[i] */
217}
218
219if (varargs) {
220    efree(varargs);
221}
222
223/* Function that accepts a string, followed by varargs (1 or more) */
224
225char *str;
226size_t str_len;
227int i, num_varargs;
228zval *varargs = NULL;
229
230if (zend_parse_parameters(ZEND_NUM_ARGS(), "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
231    return;
232}
233
234for (i = 0; i < num_varargs; i++) {
235    /* do something with varargs[i] */
236}
237
238/* Function that takes an array, followed by varargs, and ending with a long */
239zend_long num;
240zval *array;
241int i, num_varargs;
242zval *varargs = NULL;
243
244if (zend_parse_parameters(ZEND_NUM_ARGS(), "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
245    return;
246}
247
248for (i = 0; i < num_varargs; i++) {
249    /* do something with varargs[i] */
250}
251
252/* Function that doesn't accept any arguments */
253if (zend_parse_parameters_none() == FAILURE) {
254    return;
255}
256```
257