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