Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:25728
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
To: internals@lists.php.net,derick@php.net, rasmus@php.net, ilia@prohost.org
Date: Sat, 16 Sep 2006 12:54:31 +0200
Message-ID: <20060916125431.42e9a5dd@pierre-u64>
Reply-To: pierre.php@gmail.com
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Subject: ext/filter, Final API proposal
From: pierre.php@gmail.com (Pierre)

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);