See https://wiki.php.net/rfc/zpp_improv
* cataphract/zpp_improv:
Update README.PARAMETER_PARSING_API
Export zend_parse_parameter()
Expose zend_parse_arg() as zend_parse_parameter()
zend_parse_parameters: allow ! for non pointers
Sometimes, one wants to accept several types for a given parameter. zpp
has special functionality for detecting the NULL type, since the NULL
type is frequently used to skip parameters.
However, supporting several types is otherwise very tedious. There are
many cases where this situation arises -- for instance one may want
to accept an arbitrary number of integer and expect them in an array,
but allow a bare integer too; one may want to accept something that
will be used as an array key (which can be either and int or a string);
one may want to accept integer and double numbers. A search for IS_LONG
reveals many situations where this need arises.
The usual solution is to fetch the argument with 'z'/'Z', check its
type, and then convert the argument, e.g. with convert_to_long_ex().
As explain in the last commit, this has different behavior and
generates inconsistency.
Another -- even more flawed strategy --, is to try zpp with a specific
format, forcing it quiet, and if it fails retrying with another form.
But because zpp changes the arguments directly in the stack (for
instance, using "l" converts the zval in the stack to IS_LONG), the
arguments may look different after the first zpp, leaving subtle bugs.
This commit also allows more complex scenarios, for instance where the
expected type of one parameter depends on other parameters.
This commit allows getting information about whether a certain value
was a NULL value by using the ! modifier together with the l/L, d and
b.
Example:
long l;
zend_bool is_null;
zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l!", &l, &is_null)
For the specifiers l/L, d and b, NULL values are reported as 0, 0., or
false. But sometimes one wants to distinguish NULL from those other
values -- for instance, to give NULL the same effect as the argument
not having been passed.
The usual way this problem is handled is by fetching the parameter
with 'z' or 'Z', check if it is NULL and if not use
convert_to_long_ex()/convert_to_double_ex(), etc. Unfortunately, this
is not equivalent. convert_to_long_ex() does a cast, while zpp() is
stricter. For instance, zpp will not accept 'foo' for a long argument,
and it will emit a notice when encountering '5foo'.
In fact, the only way to otherwise zpp semantics (without duplicating
its logic) is to fetch the raw zval from the stack and check whether
it's NULL (with zpp itself or its relatives) and then run zpp again.
That is not an elegant solution.
