# ext/filter, Final API proposal

- Thread: https://externals.io/message/25728
- Original archive: https://news-web.php.net/php.internals/25728
- Started by Pierre on 2006-09-16T10:54:31+00:00
- Messages: 22
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #25728 — Pierre — 2006-09-16T10:54:31+00:00

URL: https://externals.io/message/25728#25728

Hello,

Given the recent discussion about the filter API in the pecl-dev list
(http://news.php.net/php.pecl.dev/4123), I summarize again what I
proposed a while back. It is very important to agree on an API now or
we will have to remove filter from 5.2.0.

This proposal does not reflect what we have now in CVS.

The major changes are:
- drop filter_data, input_get will use INPUT_DATA just like
  input_get_args

- input_get accepts takes no option or flag by default, only the filter 
  type. If you need options or flags, you pass them and the filter type
  as array. Consistent and flexible.


Please reply as soon as possible (yes, many of us are on their way
home :). Also I ask you to focus on the API itself, not on a missing
filter type, option or flag. Such things can be added anytime after
5.2.0.

Proposal:
**********

I. Availalbe functions:
   -------------------

* input_get
Gets variable from outside PHP or from a userland variable and
optionally filters it using one filter and its options or flags. It
accepts only scalar by default, array can be returned using 
ALLOW_ARRAY.

* input_get_args
Gets multiple variables from outside PHP or from a userland variable
and optionally filters them using different filters and options/flags.
It accepts only scalar by default, array can be returned using
ALLOW_ARRAY.

* input_has_variable
Checks if variable of specified type exists.

* input_name_to_filter
Returns the filter ID belonging to a named filter

* input_ filters_ list
Returns a list of all supported filters

II input_get usages

II.1 without options or flags

?mystring=<b>bold</b>
input_get(INPUT_POST, 'mystring', FILTER_SANITIZE_SPECIAL_CHARS);

?myint=493
input_get(INPUT_GET, 'myint', FILTER_VALIDATE_INT);

Using a user variable: $userint = 493;
input_get(INPUT_DATA, $userint, FILTER_VALIDATE_INT);


II.2 with options or flags

/*mystring=<b>bold</b>*/
input_get(INPUT_GET, 'mystring', array(
                                 'filter'  =>FILTER_SANITIZE_STRING,
                                 'flags'   => `FILTER_FLAG_ENCODE_HIGH` 
                                             |FILTER_FLAG_ENCODE_LOW
                                 )
         );

/*myint=493*/
input_get(INPUT_POST, 'myint', array(
                                    'filter'  => FILTER_VALIDATE_INT,
                                    'options' => array(
                                                   'min_range'=>0,
                                                   'max_range=500
                                                ),
                                    'flags'   => `FILTER_FLAG_ALLOW_HEX` 
                                    )
         );



Using a user variable: $userint = 493;
input_get(INPUT_DATA, $myint, array(
                        'filter'    =>FILTER_VALIDATE_INT,
                        'options'   => array(
                                          'min_range'=>0,
                                          'max_range=500
                                       ),
                        'flags'      => `FILTER_FLAG_ALLOW_HEX` 
                        )
         );


III. input_get_args (require array as arguments)

$args = array(
   'product_id'  => FILTER_SANITIZE_ENCODED,
   'component'    => array('filter'    => FILTER_VALIDATE_INT,
                           'flags'    => FILTER_FLAG_ARRAY,
                           'options'  => array('min_range' => 1,
                                       'max_range' => 10)
                           ),
   'versions'    => FILTER_SANITIZE_ENCODED,
   'doesnotexist' => FILTER_VALIDATE_INT,
   'testscalar'  => array(
                           'filter' => FILTER_VALIDATE_INT,
                           'flags'  => FILTER_FLAG_SCALAR,
                           ),
   'testarray'    => array(
                           'filter' => FILTER_VALIDATE_INT,
                           'flags'  => FILTER_FLAG_ARRAY,
                           )

);

Using external data
$myinputs = input_get_args(INPUT_POST, $args);

Using user variable
$myinputs = input_get_args(INPUT_DATA, $args, $data);

---

## #25730 — Christian Schneider — 2006-09-16T13:57:07+00:00

URL: https://externals.io/message/25728#25730 · In reply to: #25728

Pierre wrote:
> Proposal:
> **********
> 
> I. Availalbe functions:
>    -------------------
> 
> * input_get
> Gets variable from outside PHP or from a userland variable and
> optionally filters it using one filter and its options or flags. It
> accepts only scalar by default, array can be returned using 
> ALLOW_ARRAY.

Looks good.

> * input_get_args
> Gets multiple variables from outside PHP or from a userland variable
> and optionally filters them using different filters and options/flags.
> It accepts only scalar by default, array can be returned using
> ALLOW_ARRAY.

The current documentation page shows an example where all return values 
are an array:
array(6) {
   ["product_id"]=>
   array(1) {
     [0]=>
     string(17) "libgd%3Cscript%3E"
   }
...

I would prefer if it would return
array(6) {
   ["product_id"]=>
     string(17) "libgd%3Cscript%3E"
...
unless FILTER_FLAG_ARRAY is given in which case it should behave like 
before. This would make it easier to use the filtered values IMHO.

> * input_has_variable
> Checks if variable of specified type exists.
> 
> * input_name_to_filter
> Returns the filter ID belonging to a named filter
> 
> * input_ filters_ list
> Returns a list of all supported filters
> 
> II input_get usages
> 
> II.1 without options or flags
> 
> ?mystring=<b>bold</b>
> input_get(INPUT_POST, 'mystring', FILTER_SANITIZE_SPECIAL_CHARS);

The documentation mentions 99 as $_REQUEST for input type right now. I'd 
prefer to be able to say `INPUT_GET` | `INPUT_POST` to get values from a 
combination of sources. Or at least have INPUT_REQUEST as constant 
definition instead of 99.

My two cents,
- Chris

---

## #25731 — Pierre — 2006-09-16T14:32:40+00:00

URL: https://externals.io/message/25728#25731 · In reply to: #25730

Hello,


> Pierre wrote:
> > […]
>
> Looks good.
>
> > […]
>
> The current documentation page shows an example where all return values
> are an array:
> array(6) {
>    ["product_id"]=>
>    array(1) {
>      [0]=>
>      string(17) "libgd%3Cscript%3E"
>    }
> ...
>
> I would prefer if it would return
> array(6) {
>    ["product_id"]=>
>      string(17) "libgd%3Cscript%3E"
> ...
> unless FILTER_FLAG_ARRAY is given in which case it should behave like
> before. This would make it easier to use the filtered values IMHO.

It always returns an array when FILTER_FLAG_ARRAY is given.  Even when
the input value was a scalar. It spares yet another is_array/isset
test. And it accepts only scalar by default or when FILTER_FLAG_SCALAR
is given.



> > […]
>
> The documentation mentions 99 as $_REQUEST for input type right now. I'd
> prefer to be able to say `INPUT_GET` | `INPUT_POST` to get values from a
> combination of sources. Or at least have INPUT_REQUEST as constant
> definition instead of 99.

It uses INPUT_REQUEST (which is not yet implemented, and will not be
for 5.2.0). One should  rely only on the constants not their values :)

However, the point was about the API changes (signature, way to call
them, etc...). I suppose you like it?

--Pierre

---

## #25732 — Christian Schneider — 2006-09-16T14:46:23+00:00

URL: https://externals.io/message/25728#25732 · In reply to: #25731

Pierre wrote:
> It always returns an array when FILTER_FLAG_ARRAY is given.  Even when
> the input value was a scalar. It spares yet another is_array/isset
> test. And it accepts only scalar by default or when FILTER_FLAG_SCALAR
> is given.

Makes sense but the example shows:
$args = array(
...
    'versions'    => FILTER_SANITIZE_ENCODED,

resulting in
array(6) {
...
   ["versions"]=>
   array(1) {
     [0]=>
     string(6) "2.0.33"
   }

instead of the (by me) expected
array(6) {
...
   ["versions"]=>
     string(6) "2.0.33"

even though FILTER_FLAG_ARRAY is not given for versions. I see three 
possibilities and wonder which one is true:
a) This is a documentation bug
b) FILTER_FLAG_ARRAY is 'inherited' from the previous arg ('component')
c) The values are always returned as array

My favourite one being a) :-)

> It uses INPUT_REQUEST (which is not yet implemented, and will not be
> for 5.2.0). One should  rely only on the constants not their values :)

I agree wholeheartedly but I think it would be nice to have 
INPUT_REQUEST for 5.2.0 already. Or are you advising people to use

$myinputs = input_get_args(INPUT_GET, $args, $data) + 
input_get_args(INPUT_POST, $args, $data) [ + ... ];

as work-around for now? Just wondering...

> However, the point was about the API changes (signature, way to call
> them, etc...). I suppose you like it?

Yes, the API looks great as far as I can tell.

- Chris

---

## #25733 — Pierre — 2006-09-16T15:11:10+00:00

URL: https://externals.io/message/25728#25733 · In reply to: #25732

Hello,


> Pierre wrote:
> > […]
>
> Makes sense but the example shows:


Again, this proposal is not based on the current neither on the
examples in the manual (I did not check them recently, there is maybe
mistakes).


> a) This is a documentation bug
> b) FILTER_FLAG_ARRAY is 'inherited' from the previous arg ('component')
> c) The values are always returned as array
>
> My favourite one being a) :-)

This is what this proposal says too, so I consider that you agree :)

> > […]
>
> I agree wholeheartedly but I think it would be nice to have
> INPUT_REQUEST for 5.2.0 already. Or are you advising people to use

Sadly no, it will not be in 5.2.0. We do not have the time, the
resources and the required tests to implement it before 5.2.0.

> $myinputs = input_get_args(INPUT_GET, $args, $data) +
> input_get_args(INPUT_POST, $args, $data) [ + ... ];
>
> as work-around for now? Just wondering...

It will be array_merge(G,P,C,S) then, but this is not the goal of this
thread :-)

> > […]
>
> Yes, the API looks great as far as I can tell.

Danke!

--Pierre

---

## #25734 — Dan Scott — 2006-09-16T15:35:22+00:00

URL: https://externals.io/message/25728#25734 · In reply to: #25728

<snip>

> Proposal:
> **********
>
> I. Availalbe functions:
>    -------------------
>
> * input_get
> Gets variable from outside PHP or from a userland variable and
> optionally filters it using one filter and its options or flags. It
> accepts only scalar by default, array can be returned using
> ALLOW_ARRAY.
>
> * input_get_args
> Gets multiple variables from outside PHP or from a userland variable
> and optionally filters them using different filters and options/flags.
> It accepts only scalar by default, array can be returned using
> ALLOW_ARRAY.
>
> * input_has_variable
> Checks if variable of specified type exists.
>
> * input_name_to_filter
> Returns the filter ID belonging to a named filter

Minor: Can this be something like 'input_identify_filter' or
'input_id_filter'? The current name of the function doesn't suggest to
me that I'm going to get an ID back; it currently sounds like I'm
sending a name into a filter.

> * input_ filters_ list
> Returns a list of all supported filters

Minor: the general structure of the function names are
<prefix>_<verb>_<noun>, so it would be more consistent if this was
'input_list_filters'.

Overall: +1 (with bonus points if you go with <prefix>_<verb>_<noun>
for the two identified cases)

Dan

---

## #25735 — Andrei Zmievski — 2006-09-16T16:03:13+00:00

URL: https://externals.io/message/25728#25735 · In reply to: #25728

> * input_get
> Gets variable from outside PHP or from a userland variable and
> optionally filters it using one filter and its options or flags. It
> accepts only scalar by default, array can be returned using
> ALLOW_ARRAY.

What about the charset parameter for input_get()? We'll need it for  
PHP 6 so having it for forward compatibility could be good.

-Andrei

---

## #25736 — Ilia Alshanetsky — 2006-09-16T16:59:30+00:00

URL: https://externals.io/message/25728#25736 · In reply to: #25734

> Minor: the general structure of the function names are
> <prefix>_<verb>_<noun>, so it would be more consistent if this was
> 'input_list_filters'.
>
> Overall: +1 (with bonus points if you go with <prefix>_<verb>_<noun>
> for the two identified cases)

I for one think we should try to keep the names of something that  
(hopefully) will be used often as short possible to reduce the likely  
hood of typos.

Ilia Alshanetsky

---

## #25737 — Dan Scott — 2006-09-16T17:28:58+00:00

URL: https://externals.io/message/25728#25737 · In reply to: #25736

>
> 
>
> > […]
>
> I for one think we should try to keep the names of something that
> (hopefully) will be used often as short possible to reduce the likely
> hood of typos.
>
> Ilia Alshanetsky

Agreed. input_id_filter() is shorter than input_name_to_filter(), and
input_list_filters() is the same length as input_filters_list().

Dan

---

## #25738 — Ilia Alshanetsky — 2006-09-16T17:35:42+00:00

URL: https://externals.io/message/25728#25738 · In reply to: #25737

> Agreed. input_id_filter() is shorter than input_name_to_filter(), and
> input_list_filters() is the same length as input_filters_list().

Why not change the function prefixes to filter_*, which in turn  
allows for MUCH shorter name,
Ex: input_list_filters -> `filter_list()`

Ilia Alshanetsky

---

## #25739 — Pierre — 2006-09-16T17:46:13+00:00

URL: https://externals.io/message/25728#25739 · In reply to: #25737

Hello,


> 
> > […]
>
> Agreed. input_id_filter() is shorter than input_name_to_filter(), and
> input_list_filters() is the same length as input_filters_list().

It should be something_to_something, not something_something. "is it
id_to_filter or id_filter?", no, I'm not going to ask me this question
in the next few years.

Also it is not a ID but its name, its ID is internal, numeric and
defined by a constant. name_to_filter reflects this fact, we can use
name_to_id if you prefer, but not id_to_filter.
However, that's nitpicking, you will use this function once a month
for debugging/testing/abstraction purposes.

input_filters_list or input_list_filters, I don't care, please choose one :)

--Pierre

---

## #25765 — Derick Rethans — 2006-09-19T21:26:10+00:00

URL: https://externals.io/message/25728#25765 · In reply to: #25731

> 
> > […]
> 
> It always returns an array when FILTER_FLAG_ARRAY is given.  Even when
> the input value was a scalar. It spares yet another is_array/isset
> test. And it accepts only scalar by default or when FILTER_FLAG_SCALAR
> is given.

I would not expect that... I thought the FLAG would just mean that it 
would iterate over a whole array and allow it. I think that we should
add a second flag called "FORCE_ARRAY" or something instead.

> 
> 
> 
> > […]
> 
> It uses INPUT_REQUEST (which is not yet implemented, and will not be
> for 5.2.0). One should  rely only on the constants not their values :)

Right... INPUT_REQUEST is better than doing `INPUT_GET` | `INPUT_POST` in my 
opinion.

regards,
Derick

---

## #25766 — Derick Rethans — 2006-09-19T21:26:13+00:00

URL: https://externals.io/message/25728#25766 · In reply to: #25728

> Hello,
> 
> Given the recent discussion about the filter API in the pecl-dev list
> (http://news.php.net/php.pecl.dev/4123), I summarize again what I
> proposed a while back. It is very important to agree on an API now or
> we will have to remove filter from 5.2.0.
> 
> This proposal does not reflect what we have now in CVS.
> 
> The major changes are:
> - drop filter_data, input_get will use INPUT_DATA just like
>   input_get_args
> 
> - input_get accepts takes no option or flag by default, only the filter 
>   type. If you need options or flags, you pass them and the filter type
>   as array. Consistent and flexible.

I think that is a bad idea, and it's also something I disliked in the 
_get_args() implementation as we'd basically be overloading the 
parameter then. I would not want that for input_get(), and I think we 
should also come up with something else for the definition in 
input_get_args() there as well.

> Please reply as soon as possible (yes, many of us are on their way
> home :). Also I ask you to focus on the API itself, not on a missing
> filter type, option or flag. Such things can be added anytime after
> 5.2.0.
> 
> Proposal:
> **********
> 
> I. Availalbe functions:
>    -------------------
> 
> * input_get
> Gets variable from outside PHP or from a userland variable and
> optionally filters it using one filter and its options or flags. It
> accepts only scalar by default, array can be returned using 
> ALLOW_ARRAY.
> 
> * input_get_args
> Gets multiple variables from outside PHP or from a userland variable
> and optionally filters them using different filters and options/flags.
> It accepts only scalar by default, array can be returned using
> ALLOW_ARRAY.
> 
> * input_has_variable
> Checks if variable of specified type exists.
> 
> * input_name_to_filter
> Returns the filter ID belonging to a named filter
> 
> * input_ filters_ list
> Returns a list of all supported filters

Without the spaces I hope :)

> 
> II input_get usages
> 
> II.1 without options or flags
> 
> ?mystring=<b>bold</b>
> input_get(INPUT_POST, 'mystring', FILTER_SANITIZE_SPECIAL_CHARS);
> 
> ?myint=493
> input_get(INPUT_GET, 'myint', FILTER_VALIDATE_INT);
> 
> Using a user variable: $userint = 493;
> input_get(INPUT_DATA, $userint, FILTER_VALIDATE_INT);
> 
> 
> II.2 with options or flags
> 
> /*mystring=<b>bold</b>*/
> input_get(INPUT_GET, 'mystring', array(
>                                  'filter'  =>FILTER_SANITIZE_STRING,
>                                  'flags'   => `FILTER_FLAG_ENCODE_HIGH` 
>                                              |FILTER_FLAG_ENCODE_LOW
>                                  )
>          );

I think we should just stick to the old syntax here:

input_get(INPUT_GET, 'mystring', FILTER_SANITIZE_STRING, FILTER_FLAG_ENCODE_HIGH|FILTER_FLAG_ENCODE_LOW );

[snip two examples]

In that case INPUT_DATA becomes ugly so I prefer a different function 
for filtering already existing data in variables (as you're not 
getting any input as "input_get" refers to). 

[snip III. input_get_args (require array as arguments)]

regards,
Derick

---

## #25767 — Derick Rethans — 2006-09-19T21:28:24+00:00

URL: https://externals.io/message/25728#25767 · In reply to: #25737

> 
> > […]
> 
> Agreed. input_id_filter() is shorter than input_name_to_filter(), and
> input_list_filters() is the same length as input_filters_list().

This function won't be used a lot, so a longer name is fine. I would go 
for input_get_filter_id() and input_list_filters().

regards,
Derick

---

## #25769 — Pierre — 2006-09-19T21:45:01+00:00

URL: https://externals.io/message/25728#25769 · In reply to: #25765

Hello,



> > […]
>
> I would not expect that... I thought the FLAG would just mean that it
> would iterate over a whole array and allow it. I think that we should
> add a second flag called "FORCE_ARRAY" or something instead.

The flag allows arrays and always returns an array. It is obvious as
if you allow array or scalar, you have to use is_array, that's a step
we easily drop internally by always returning an array. I do not see
the point to have ALLOW_ARRAY and FORCE_ARRAY. It is confusing.

--Pierre

---

## #25770 — Pierre — 2006-09-19T21:53:30+00:00

URL: https://externals.io/message/25728#25770 · In reply to: #25766

Hello,


> 
>
> > […]
>
> I think that is a bad idea, and it's also something I disliked in the
> _get_args() implementation as we'd basically be overloading the
> parameter then. I would not want that for input_get(), and I think we
> should also come up with something else for the definition in
> input_get_args() there as well.

There is no other choices. Unless we add naming argument in php 5.2,
we are out of choicses. I also not think a function with five
arguments and one of them being mixed is a good thing, it is what we
did in the early versions of php, it was and is a mistake.

Having an array is just readable, easy to remember and to extend.
Everyone here agreed.



> I think we should just stick to the old syntax here:
>
> input_get(INPUT_GET, 'mystring', FILTER_SANITIZE_STRING, FILTER_FLAG_ENCODE_HIGH|FILTER_FLAG_ENCODE_LOW );

And you have to use an array if you have options, add a fifth argument
for the upcoming charset, and a sixth if we need another one? That's
insane and confusing, sorry.

> In that case INPUT_DATA becomes ugly so I prefer a different function
> for filtering already existing data in variables (as you're not
> getting any input as "input_get" refers to).

It is consistent. All function works the same way. The same definition
works for both filter_get and filter_get_args.

About this extension being more core and being able to do not follow
the CS, please convince everyone else here. I really don't care about
filter_ or input_. But I really care about API consisitency, code
simplicity (internally and in userland). I have a patch ready for this
proposal, the code is much more simple and smaller. I thought you will
follow other devs oppinion, my bad...

--Pierre

---

## #25771 — Christian Schneider — 2006-09-19T22:36:11+00:00

URL: https://externals.io/message/25728#25771 · In reply to: #25769

Pierre wrote:
> The flag allows arrays and always returns an array. It is obvious as
> if you allow array or scalar, you have to use is_array, that's a step
> we easily drop internally by always returning an array. I do not see
> the point to have ALLOW_ARRAY and FORCE_ARRAY. It is confusing.

I agree with you there. And I also like the function names you guys came 
up with.

But my real reason to write this email is this: Is there any chance 
INPUT_REQUEST would make it into 5.2 if I come up with a patch? What 
would be the time frame for it? Is your current patch online so I could 
base it on that?

The reason I'm asking is that I think it the interface without it is 
unnecessarily crippled and providing it later makes version checking 
necessary in code using this function.

- Chris

---

## #25772 — Pierre — 2006-09-19T22:51:23+00:00

URL: https://externals.io/message/25728#25772 · In reply to: #25771

Hello,


> Pierre wrote:
> > […]
>
> I agree with you there. And I also like the function names you guys came
> up with.

Thanks, the patch is even ready, but...

> But my real reason to write this email is this: Is there any chance
> INPUT_REQUEST would make it into 5.2 if I come up with a patch? What
> would be the time frame for it? Is your current patch online so I could
> base it on that?
> The reason I'm asking is that I think it the interface without it is
> unnecessarily crippled and providing it later makes version checking
> necessary in code using this function.

If Derick can make a compromise and accept to this widely approved
proposal, yes, I can make INPUT_REQUEST for 5.2. If not, I'm not even
sure that 5.2 will have filter (or any upcoming version). I'm
pessimist, I'm again blocked by a "no" without alternatives.

Please note that Dmitry was kind enough to merge a bug fix about cgi
and -d. It will allow me to add a bunch of INPUT_GET/POST/REQUEST
tests with different default filters.

--Pierre

---

## #25775 — Derick Rethans — 2006-09-20T19:54:13+00:00

URL: https://externals.io/message/25728#25775 · In reply to: #25770

> 
> > […]
> 
> There is no other choices. Unless we add naming argument in php 5.2,
> we are out of choicses. I also not think a function with five
> arguments and one of them being mixed is a good thing, it is what we
> did in the early versions of php, it was and is a mistake.

Well, you're still doing the same, but now with the parameter that also 
contains the filter. This is fundamentally different compared to the 
previous API, because both the flags and the options *modify* a filter, 
and both of them are not required. 

When I was first implementing this stuff I thought that it was 
best to always use an array to specify both options and flags as 4th 
parameter. However, there is only one filter (validate_int) that 
currently uses the options (min_range and max_range); and I found that 
having to use an array for all other filters just because of 
validate_int was a bad idea, as it unnecessarily bloats calling 
filters with funky array() syntax. Hence the status quo where you only 
have to use an array if you want to use options besides flags at well.

> > […]
> 
> And you have to use an array if you have options, add a fifth argument
> for the upcoming charset, and a sixth if we need another one? That's
> insane and confusing, sorry.

Which sixth parameter? And no, it's not more confusing then having to 
use an array as third parameter *only* in case you want flags and or 
options. As I said before: the filter is one part of the call, and the 
filter's modifiers (options/flags) are. They don't logically belong 
together in one parameter.

> > […]
> 
> It is consistent. All function works the same way. The same definition
> works for both filter_get and filter_get_args.

Actually, it's less consistent *and* it would require another parameter 
to the functions, while you just suggested that you disliked more 
parameters. Again, it's also fundamentally two different things:
- request input data
- existing variables
Therefore there should be two sets of functions, one of the classes with 
both a single filter specification and one with a filter specification 
array.


So this boils down to the following proposal:

/**
 * Returns the specified $variableName from the request input source 
 * $source filtered through the filter specified with $filterId. 
 * Filter modifiers can be passed in $filterOptions.
 *
 * @param int $source (INPUT_GET...)
 * @param string $variableName 
 * @param int $filterId
 * @param mixed $filterOptions  Integer with flags, or array with two 
 *                              elements: "flags" an "options".
 * @return mixed
 */
input_get( $source, $variableName, $filterId [ , $filterOptions ] );

/**
 * Returns an array acording to the $varSpecs from the request input
 * source $source filtered through the filter specified in the 'filter'
 * array element of $varSpecs. Filter modifiers can be passed in the
 * 'flags' and 'options' array members. (The elements in $varSpecs are
 * *always* arrays and not a single filterId).
 *
 * @param int $source (INPUT_GET...)
 * @param array(string=>array) $varSpecs
 * @return mixed
 */
input_get_args( $source, $varSpecs );

/**
 * Returns the specified $variable filtered through the filter specified
 * with $filterId.  Filter modifiers can be passed in $filterOptions.
 *
 * @param mixed $variable
 * @param int $filterId
 * @param mixed $filterOptions  Integer with flags, or array with two 
 *                              elements: "flags" an "options".
 * @return mixed
 */
input_filter_var( $variable, $filterId [ , $filterOptions ] );

/**
 * Returns an array with variables according to the $varSpecs. Each of
 * the array members of $data is filtered through the filter specified
 * in the 'filter' array element of $varSpecs. Filter modifiers can be
 * passed in the 'flags' and 'options' array members. (The elements in
 * $varSpecs are *always* arrays and not a single filterId).
 *
 * @param array(mixed) $variable
 * @param array(string=>array) $varSpecs
 * @return array(mixed)
 */
input_filter_args( $variableArray, $varSpecs );

/**
 * Returns whether the variable $varName is available in the source
 * $source.
 *
 * @param int $source (INPUT_GET...)
 * @param string $varName 
 */
input_has_variable( $source, $varName );

/**
 * Returns the filter ID belonging to the filter with the name
 * $filterName.
 *
 * @param string $filterName
 * @return int
 */
input_get_filter_id( $filterName )

/**
 * Returns an array of all filters, where the key is the filter ID and
 * the value the filter name.
 *
 * @return array(int=>string)
 */
input_filters_list();

From the mail about how FLAG_ARRAY should work:



> 
> > […]
> 
> The flag allows arrays and always returns an array. It is obvious

No it isn't obvious at all. Look at this example:

<?php
$varSpecs = array(
	'varName' => array( 'filter' => 'string', 'flags' => FILTER_FLAG_ARRAY )
);

$data = array( 'varName' => 42 );

$filteredData = input_filter_args( $data, $varSpecs );
?>

Because the variable 'varName' has the FILTER_FLAG_ARRAY you say that it 
should make an array out of this, resulting in the data:

$filterData = array( 'varName' => array( 42 ) );

Unless you want to ignore this flag for filtering already existing 
variables which makes things inconsistent again. 

Therefore we should use use the FILTER_FLAG_ARRAY to recursively go over 
the input variable that is being filtered. If the flag is not there and 
the input variable is an array, it should return false/null (whatever 
the default is).

regards,
Derick

-- 
Derick Rethans
http://derickrethans.nl | http://ez.no | http://xdebug.org

---

## #25778 — Pierre — 2006-09-20T23:11:50+00:00

URL: https://externals.io/message/25728#25778 · In reply to: #25775

Hello,

Before any further comment, we agreed on the "filter" prefix. We have
to stick to it. I also think we should respect other developers
choices.

As you said, filter is more than a simple extension, its design choice
should not be up to only one or two persons. My proposal has been
approved by many developers in this thread and in pecl-dev.

It seems that you either did not read the discussion or ignore the
popular choice. I do not think it is a good thing.

A patch with the changes we agreed on is already ready:

http://pecl.php.net/~pierre/filter_apishakeup.txt

It passes the tests (after update) and fix two bugs. That means a RC5
is possible this week, on friday.

But If you keep refuse to accept our choices, we first have to find
(again) compromises, get it approved, implement and test it. Given the
current tempo, php6 will be out before we are done! :P

However, my comments about your proposal (short version: no):


> 
>
> > […]
>
> Well, you're still doing the same, but now with the parameter that also
> contains the filter. This is fundamentally different compared to the
> previous API, because both the flags and the options *modify* a filter,
> and both of them are not required.

I know that both modify a filter. And I do think that array make the
code way more readable and easier to extend.

> When I was first implementing this stuff I thought that it was
> best to always use an array to specify both options and flags as 4th
> parameter. However, there is only one filter (validate_int) that
> currently uses the options (min_range and max_range); and I found that
> having to use an array for all other filters just because of
> validate_int was a bad idea, as it unnecessarily bloats calling
> filters with funky array() syntax. Hence the status quo where you only
> have to use an array if you want to use options besides flags at well.

More filters will use option (like IP for examples, or url, mails). An
array allows a clear and extendable signature. I don't think anyone
here can affirm that no other filter will use more options, flags or
arguments. The goal is to create an API that we will not have to break
in a near future, especially not because we added more filters. An
array gives us this security.

> > […]
>
> Which sixth parameter? And no, it's not more confusing then having to
> use an array as third parameter *only* in case you want flags and or
> options. As I said before: the filter is one part of the call, and the
> filter's modifiers (options/flags) are. They don't logically belong
> together in one parameter.


You are alone to find it more confusing. Actually you are alone to
want the old API.

> > […]
>
> Actually, it's less consistent *and* it would require another parameter
> to the functions, while you just suggested that you disliked more
> parameters. Again, it's also fundamentally two different things:
> - request input data
> - existing variables
> Therefore there should be two sets of functions, one of the classes with
> both a single filter specification and one with a filter specification
> array.

It makes no difference to filter a variable or input data. Having both
modes in one function allows easy integration of the filter API into a
more generic API. We also agreed here on this choice.

Droping custom functions to filter variables (from script, not input
data) has been requested and approved. I think it is a good thing.

Sorry, but I dislike this one, it does not the need of consistency and
clarity. I also thought about a similar API (the same without the
variable functions), but using an array for all arguments (as proposed
in my final version) is the way to go. Using the 3rd argument as flag
or array just brings us back to the current API, which is confusing.

> input_has_variable( $source, $varName );
> input_get_filter_id( $filterName )
> input_filters_list();

These three functions names have been approved and I prefer what we choose.


> From the mail about how FLAG_ARRAY should work:
>
> 
>
> > […]
>
> No it isn't obvious at all. Look at this example:
>
> <?php
> $varSpecs = array(
>         'varName' => array( 'filter' => 'string', 'flags' => FILTER_FLAG_ARRAY )
> );
>
> $data = array( 'varName' => 42 );
>
> $filteredData = input_filter_args( $data, $varSpecs );
> ?>
>
> Because the variable 'varName' has the FILTER_FLAG_ARRAY you say that it
> should make an array out of this, resulting in the data:
>
> $filterData = array( 'varName' => array( 42 ) );
>
> Unless you want to ignore this flag for filtering already existing
> variables which makes things inconsistent again.

I do not understand what you mean here.

Let me explain it again, if the flag is not set and the input is an
array, it returns false (validation fails). If it is present, you are
sure to get an array in return, even if the variable was a scalar.

> Therefore we should use use the FILTER_FLAG_ARRAY to recursively go over
> the input variable that is being filtered. If the flag is not there and
> the input variable is an array, it should return false/null (whatever
> the default is).

That's what it does when FILTER_FLAG_ARRAY is set. FILTER_FLAG_SCALAR
being the default.


--Pierre

---

## #25821 — Derick Rethans — 2006-09-25T17:18:49+00:00

URL: https://externals.io/message/25728#25821 · In reply to: #25778

> Before any further comment, we agreed on the "filter" prefix. We have
> to stick to it. I also think we should respect other developers
> choices.
> 
> As you said, filter is more than a simple extension, its design choice
> should not be up to only one or two persons. My proposal has been
> approved by many developers in this thread and in pecl-dev.

There were comments as to follow CS for the function names, but that 
doesn't mean that we can't pick the obvious choice of renaming the 
extension to "input" instead of "filter". As the functions deal with 
getting input through a filter, there is nothing wrong with using 
input_* for the function names and "input" as extension name.

> 
> > […]
> 
> I know that both modify a filter. And I do think that array make the
> code way more readable and easier to extend.

An array for the options and flags - yes. But mixing the filter itself 
with the option and flags array doesn't make sense as they are two 
*different* things that the function accepts.

> > […]
> 
> More filters will use option (like IP for examples, or url, mails). An
> array allows a clear and extendable signature. I don't think anyone
> here can affirm that no other filter will use more options, flags or
> arguments. The goal is to create an API that we will not have to break
> in a near future, especially not because we added more filters. An
> array gives us this security.

You don't have to break anything here in the future. There are many 
filters now which only take flags. Requiring to have to use array( 
'flags' => ... ) in that case is annoying and unnecesary. Ofcourse, 
the array syntax *should* be supported as as well because some filters 
will also require options. Then you will not have to break anything and 
you still allow the easier syntax in case a filter only has flags (or 
when you only need to use flags for a filter).

[snip]

> > […]
> 
> It makes no difference to filter a variable or input data. Having both
> modes in one function allows easy integration of the filter API into a
> more generic API.

Ofcourse it makes s difference. To filter an already existing 
variable with data is conceptually different from receiving variable 
data by means of an input source and variable name. Because it is 
conceptually different we shouldn't try to stick those two different 
things into one function's API. 

> We also agreed here on this choice.

"We" didn't agree on this at all otherwise I wouldn't have made a 
comment about it.

> Droping custom functions to filter variables (from script, not input
> data) has been requested and approved. I think it is a good thing.

What? You propose to drop support for callbacks here? And who approved 
that and where was it requested?

> > […]
> 
> I do not understand what you mean here.
> 
> Let me explain it again, if the flag is not set and the input is an
> array, it returns false (validation fails).

Yes, that is fine.

> If it is present, you are
> sure to get an array in return, even if the variable was a scalar.

And this is not.

We shouldn't convert a scalar to an array, as we're then basically 
mangling data. Instead we should return false just like in the case 
where an array is submitted and a scalar is expected.

regards,
Derick

---

## #25825 — Pierre — 2006-09-25T17:46:42+00:00

URL: https://externals.io/message/25728#25825 · In reply to: #25821

Hello,

Before any further comment, I have to say that I'm more than
disappointed to have put so much effort to get a concensus from the
PHP developers here and lost it right away because you, alone, thinks
that *we* made wrong choices. I cannot accept that any longuer, I do
not want to block 5.2 endlessly and this discussion is getting more
than annoyed, each time I make 10 steps forwards, you come in and put
us back behing the starting blocks.

If you like to drop our choices, please get the approbations of the developers.


> 
>
> > […]
>
> There were comments as to follow CS for the function names, but that
> doesn't mean that we can't pick the obvious choice of renaming the
> extension to "input" instead of "filter". As the functions deal with
> getting input through a filter, there is nothing wrong with using
> input_* for the function names and "input" as extension name.

We actually filter input variables and PHP defined variables, we
filter data. Filter is a valid choice (and apply to CS). But I really
don't care about input_ or filter_. filter_ being the one we (everyone
else) choosed, I accept this choice.

> An array for the options and flags - yes. But mixing the filter itself
> with the option and flags array doesn't make sense as they are two
> *different* things that the function accepts.

The filter type is per se only an argument, even if it is the main
one. it brings consistency and flexibility to the developer. You can
pass the same array to filter_get and to as element of a
filter_get_args array.


> > […]
>
> You don't have to break anything here in the future. There are many
> filters now which only take flags. Requiring to have to use array(
> 'flags' => ... ) in that case is annoying and unnecesary. Ofcourse,
> the array syntax *should* be supported as as well because some filters
> will also require options. Then you will not have to break anything and
> you still allow the easier syntax in case a filter only has flags (or
> when you only need to use flags for a filter).

The flags are considered as the common usage. Any other arguments must
use an array. The other way 'round can make sense too in some cases,
or not. It is just an arbitrary choice using the current set of
filters. My accepted proposal does not have this issue.

> > […]

> Ofcourse it makes s difference. To filter an already existing
> variable with data is conceptually different from receiving variable
> data by means of an input source and variable name. Because it is
> conceptually different we shouldn't try to stick those two different
> things into one function's API.

It is by no mean different. We only do part of the developer job,
optionally prefilter the input variables and fetch them from the rigth
array. The rest is exactly the same. There is no conceptual
difference, only different sources of the data.

> > […]
>
> "We" didn't agree on this at all otherwise I wouldn't have made a
> comment about it.

We as everyone else and me, not you and me.

> > […]
>
> What? You propose to drop support for callbacks here? And who approved
> that and where was it requested?

I meant filter_data, sorry for the confusions.

> > […]
>
> Yes, that is fine.

Good, we (everyone and you) agree at least one one thing.

> > […]
>
> And this is not.
>
> We shouldn't convert a scalar to an array, as we're then basically
> mangling data. Instead we should return false just like in the case
> where an array is submitted and a scalar is expected.

A scalar is not expected as the *ARRAY* flag has been given. It is
really handy and usefull, for all the reasons described in this
thread.

I will commit my patch tonight. It cleans a lot the code but keeps all
the features. No matter what will be the conclusions of this endless
discussion, it will be easy to change the code accordingly, if there
is an agreement.

--Pierre
