From 63c68778956904c9b6e69c554fbc933bea0ed860 Mon Sep 17 00:00:00 2001
From: Pierre Joye <pajoye@php.net>
Date: Fri, 20 Oct 2006 01:47:29 +0000
Subject: [PATCH] - filter api shakeup 1/2

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@222047 c90b9560-bf6c-de11-be94-00142212c4b1
---
 ...ut-has-variable.xml => filter-has-var.xml} |   6 +-
 ...input-name-to-filter.xml => filter-id.xml} |   8 +-
 .../filter/functions/filter-input-array.xml   | 174 ++++++++++++++++++
 .../{input-get.xml => filter-input.xml}       |  36 ++--
 ...input-filters-list.xml => filter-list.xml} |  14 +-
 ...nput-get-args.xml => filter-var-array.xml} |  34 ++--
 .../{filter-data.xml => filter-var.xml}       |  28 +--
 7 files changed, 225 insertions(+), 75 deletions(-)
 rename reference/filter/functions/{input-has-variable.xml => filter-has-var.xml} (92%)
 rename reference/filter/functions/{input-name-to-filter.xml => filter-id.xml} (87%)
 create mode 100644 reference/filter/functions/filter-input-array.xml
 rename reference/filter/functions/{input-get.xml => filter-input.xml} (76%)
 rename reference/filter/functions/{input-filters-list.xml => filter-list.xml} (83%)
 rename reference/filter/functions/{input-get-args.xml => filter-var-array.xml} (80%)
 rename reference/filter/functions/{filter-data.xml => filter-var.xml} (77%)

diff --git a/reference/filter/functions/input-has-variable.xml b/reference/filter/functions/filter-has-var.xml
similarity index 92%
rename from reference/filter/functions/input-has-variable.xml
rename to reference/filter/functions/filter-has-var.xml
index b3b382afd5..b1237d9334 100644
--- a/reference/filter/functions/input-has-variable.xml
+++ b/reference/filter/functions/filter-has-var.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision: 1.1 $ -->
 <!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
-<refentry id="function.input-has-variable">
+<refentry id="function.filter-has-var">
  <refnamediv>
-  <refname>input_has_variable</refname>
+  <refname>filter_has_var</refname>
   <refpurpose>Checks if variable of specified type exists</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>bool</type><methodname>input_has_variable</methodname>
+   <type>bool</type><methodname>filter_has_var</methodname>
    <methodparam><type>int</type><parameter>type</parameter></methodparam>
    <methodparam><type>string</type><parameter>variable_name</parameter></methodparam>
   </methodsynopsis>
diff --git a/reference/filter/functions/input-name-to-filter.xml b/reference/filter/functions/filter-id.xml
similarity index 87%
rename from reference/filter/functions/input-name-to-filter.xml
rename to reference/filter/functions/filter-id.xml
index 9eb9bdb79c..15d86b6d7a 100644
--- a/reference/filter/functions/input-name-to-filter.xml
+++ b/reference/filter/functions/filter-id.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- $Revision: 1.1 $ -->
 <!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
-<refentry id="function.input-name-to-filter">
+<refentry id="function.filter-id">
  <refnamediv>
-  <refname>input_name_to_filter</refname>
+  <refname>filter_id</refname>
   <refpurpose>Returns the filter ID belonging to a named filter</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>int</type><methodname>input_name_to_filter</methodname>
+   <type>int</type><methodname>filter_id</methodname>
    <methodparam><type>string</type><parameter>filtername</parameter></methodparam>
   </methodsynopsis>
 
@@ -42,7 +42,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>input_filters_list</function></member>
+    <member><function>filter_list</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/filter/functions/filter-input-array.xml b/reference/filter/functions/filter-input-array.xml
new file mode 100644
index 0000000000..627d8e1036
--- /dev/null
+++ b/reference/filter/functions/filter-input-array.xml
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+<refentry id="function.filter-input-array">
+ <refnamediv>
+  <refname>filter_input_array</refname>
+  <refpurpose>Gets multiple variables from outside PHP and optionally filters them</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>mixed</type><methodname>filter_input_array</methodname>
+   <methodparam><type>int</type><parameter>type</parameter></methodparam>
+   <methodparam><type>array</type><parameter>options</parameter></methodparam>
+  </methodsynopsis>
+  &warn.experimental.func;
+  <para>
+   This function is useful for retrieving many values without
+   repetitively calling <function>filter_input</function>.
+  </para>
+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>type</parameter></term>
+     <listitem>
+      <para>
+       One of <constant>INPUT_GET</constant>, <constant>INPUT_POST</constant>,
+       <constant>INPUT_COOKIE</constant>, <constant>INPUT_SERVER</constant>,
+       <constant>INPUT_ENV</constant>, <constant>INPUT_SESSION</constant>, or
+       <constant>INPUT_DATA</constant>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>definition</parameter></term>
+     <listitem>
+      <para>
+       An array defining the arguments. A valid key is a <type>string</type>
+       containing a variable name and a valid value is either a filter type,
+       or an <type>array</type> optionally specifying the filter, flags and
+       options. If the value is an array, valid keys are
+       <literal>filter</literal> which specifies the filter type,
+       <literal>flags</literal> which specifies any flags that apply to the
+       filter, and <literal>options</literal> which specifies any options
+       that apply to the filter. See the example below for a better
+       understanding.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   An array containing the values of the requested variables on success, or &false; 
+   on failure. An array value will be &false; if the filter fails, or &null; if 
+   the variable is not set. Or if the flag <constant>FILTER_NULL_ON_FAILURE</constant>
+   is used, it returns &false; if the variable is not set and &null; if the filter 
+   fails.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>A <function>filter_input_array</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+error_reporting(E_ALL | E_STRICT);
+$data = array(
+    'product_id'    => 'libgd<script>',
+    'component'     => '10',
+    'versions'      => '2.0.33',
+    'testscalar'    => array('2', '23', '10', '12'),
+    'testarray'     => '2',
+);
+
+$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,
+                           )
+
+);
+
+$myinputs = filter_input_array(INPUT_DATA, $args, $data);
+
+var_dump($myinputs);
+echo "\n";
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+array(6) {
+  ["product_id"]=>
+  array(1) {
+    [0]=>
+    string(17) "libgd%3Cscript%3E"
+  }
+  ["component"]=>
+  array(1) {
+    [0]=>
+    int(10)
+  }
+  ["versions"]=>
+  array(1) {
+    [0]=>
+    string(6) "2.0.33"
+  }
+  ["doesnotexist"]=>
+  NULL
+  ["testscalar"]=>
+  bool(false)
+  ["testarray"]=>
+  array(1) {
+    [0]=>
+    int(2)
+  }
+}
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>filter_input</function></member>
+    <member><function>filter_var_array</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/filter/functions/input-get.xml b/reference/filter/functions/filter-input.xml
similarity index 76%
rename from reference/filter/functions/input-get.xml
rename to reference/filter/functions/filter-input.xml
index 40ec676e27..5e16616aeb 100644
--- a/reference/filter/functions/input-get.xml
+++ b/reference/filter/functions/filter-input.xml
@@ -1,20 +1,19 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.1 $ -->
 <!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
-<refentry id="function.input-get">
+<refentry id="function.filter-input">
  <refnamediv>
-  <refname>input_get</refname>
+  <refname>filter_input</refname>
   <refpurpose>Gets variable from outside PHP and optionally filters it</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>mixed</type><methodname>input_get</methodname>
+   <type>mixed</type><methodname>filter_input</methodname>
    <methodparam><type>int</type><parameter>type</parameter></methodparam>
    <methodparam><type>string</type><parameter>variable_name</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>filter</parameter></methodparam>
-   <methodparam choice="opt"><type>mixed</type><parameter>flags</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>options</parameter></methodparam>
   </methodsynopsis>
 
   &warn.experimental.func;
@@ -31,7 +30,7 @@
        One of <constant>INPUT_GET</constant>, <constant>INPUT_POST</constant>,
        <constant>INPUT_COOKIE</constant>, <constant>INPUT_SERVER</constant>,
        <constant>INPUT_ENV</constant>, <constant>INPUT_SESSION</constant> (not
-       implemented yet) and 99 (serves for REQUEST for now).
+       implemented yet) and INPUT_REQUEST.
       </para>
      </listitem>
     </varlistentry>
@@ -52,7 +51,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>flags</parameter></term>
+     <term><parameter>options</parameter></term>
      <listitem>
       <para>
        Associative array of options or bitwise disjunction of flags. If filter
@@ -60,15 +59,6 @@
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
-     <term><parameter>charset</parameter></term>
-     <listitem>
-      <para>
-       Character set used for filtering. Currently no filter uses this
-       parameter.
-      </para>
-     </listitem>
-    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -77,6 +67,8 @@
   <para>
    Value of the requested variable on success, &false; if the filter fails,
    or &null; if the <parameter>variable_name</parameter> variable is not set.
+   If the flag <constant>FILTER_NULL_ON_FAILURE</constant> is used, it
+   returns &false; if the variable is not set and &null; if the filter fails.
    </para>
  </refsect1>
 
@@ -84,12 +76,12 @@
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>input_get</function> example</title>
+    <title>A <function>filter_input</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-$search_html = input_get(INPUT_GET, 'search', FILTER_SANITIZE_SPECIAL_CHARS);
-$search_url = input_get(INPUT_GET, 'search', FILTER_SANITIZE_ENCODED);
+$search_html = filter_input(INPUT_GET, 'search', FILTER_SANITIZE_SPECIAL_CHARS);
+$search_url = filter_input(INPUT_GET, 'search', FILTER_SANITIZE_ENCODED);
 echo "You have searched for $search_html.\n";
 echo "<a href='?search=$search_url'>Search again.</a>";
 ?>
@@ -110,7 +102,9 @@ You have searched for Me &#38; son.
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>filter_data</function></member>
+    <member><function>filter_var</function></member>
+    <member><function>filter_input_array</function></member>
+    <member><function>filter_var_array</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/filter/functions/input-filters-list.xml b/reference/filter/functions/filter-list.xml
similarity index 83%
rename from reference/filter/functions/input-filters-list.xml
rename to reference/filter/functions/filter-list.xml
index eaf56e4569..16be93d102 100644
--- a/reference/filter/functions/input-filters-list.xml
+++ b/reference/filter/functions/filter-list.xml
@@ -1,15 +1,15 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.1 $ -->
 <!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
-<refentry id="function.input-filters-list">
+<refentry id="function.filter-list">
  <refnamediv>
-  <refname>input_filters_list</refname>
+  <refname>filter_list</refname>
   <refpurpose>Returns a list of all supported filters</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>array</type><methodname>input_filters_list</methodname>
+   <type>array</type><methodname>filter_list</methodname>
    <void/>
   </methodsynopsis>
 
@@ -21,7 +21,7 @@
   <para>
    Returns an array of names of all supported filters, empty array if there
    are no such filters. Indexes of this array are not filter IDs, they can be
-   obtained with <function>input_name_to_filter</function> from a name instead.
+   obtained with <function>filter_id</function> from a name instead.
   </para>
  </refsect1>
 
@@ -29,11 +29,11 @@
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>input_filters_list</function> example</title>
+    <title>A <function>filter_list</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-print_r(input_filters_list());
+print_r(filter_list());
 ?>
 ]]>
     </programlisting>
diff --git a/reference/filter/functions/input-get-args.xml b/reference/filter/functions/filter-var-array.xml
similarity index 80%
rename from reference/filter/functions/input-get-args.xml
rename to reference/filter/functions/filter-var-array.xml
index 3dedcb0d2f..1ddf22966e 100644
--- a/reference/filter/functions/input-get-args.xml
+++ b/reference/filter/functions/filter-var-array.xml
@@ -1,22 +1,21 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
-<refentry id="function.input-get-args">
+<!-- $Revision: 1.1 $ -->
+<refentry id="function.filter-var-array">
  <refnamediv>
-  <refname>input_get_args</refname>
+  <refname>filter_var_array</refname>
   <refpurpose>Gets multiple variables from outside PHP and optionally filters them</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>mixed</type><methodname>input_get_args</methodname>
+   <type>mixed</type><methodname>filter_var_array</methodname>
    <methodparam><type>int</type><parameter>type</parameter></methodparam>
-   <methodparam><type>array</type><parameter>definition</parameter></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter>data</parameter></methodparam>
+   <methodparam><type>array</type><parameter>options</parameter></methodparam>
   </methodsynopsis>
   &warn.experimental.func;
   <para>
-   This function is useful for retrieving a large amount of values without
-   repetitively calling <function>input_get</function>.
+   This function is useful for retrieving many values without
+   repetitively calling <function>filter_var</function>.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -50,15 +49,6 @@
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
-     <term><parameter>data</parameter></term>
-     <listitem>
-      <para>
-       Data to filter. Used if the <parameter>type</parameter> parameter is
-       set to <constant>INPUT_DATA</constant>.
-      </para>
-     </listitem>
-    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -75,7 +65,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>input_get_args</function> example</title>
+    <title>A <function>filter_var_array</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -107,8 +97,7 @@ $args = array(
 
 );
 
-//$myinputs = input_get_args(INPUT_POST, $args);
-$myinputs = input_get_args(INPUT_DATA, $args, $data);
+$myinputs = input_var_array($data, $args);
 
 var_dump($myinputs);
 echo "\n";
@@ -153,8 +142,9 @@ array(6) {
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>input_get</function></member>
-    <member><function>filter_data</function></member>
+    <member><function>filter_input_array</function></member>
+    <member><function>filter_var</function></member>
+    <member><function>filter_input</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/filter/functions/filter-data.xml b/reference/filter/functions/filter-var.xml
similarity index 77%
rename from reference/filter/functions/filter-data.xml
rename to reference/filter/functions/filter-var.xml
index c84540f234..38fade4d5d 100644
--- a/reference/filter/functions/filter-data.xml
+++ b/reference/filter/functions/filter-var.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.1 $ -->
 <!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
-<refentry id="function.filter-data">
+<refentry id="function.filter-var">
  <refnamediv>
-  <refname>filter_data</refname>
-  <refpurpose>Filters data with a specified filter</refpurpose>
+  <refname>filter_var</refname>
+  <refpurpose>Filters a variable with a specified filter</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -12,8 +12,7 @@
    <type>mixed</type><methodname>filter_data</methodname>
    <methodparam><type>mixed</type><parameter>variable</parameter></methodparam>
    <methodparam><type>int</type><parameter>filter</parameter></methodparam>
-   <methodparam choice="opt"><type>mixed</type><parameter>filter_options</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>options</parameter></methodparam>
   </methodsynopsis>
 
   &warn.experimental.func;
@@ -40,7 +39,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>filter_options</parameter></term>
+     <term><parameter>options</parameter></term>
      <listitem>
       <para>
        Associative array of options or bitwise disjunction of flags. If filter
@@ -49,15 +48,6 @@
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
-     <term><parameter>charset</parameter></term>
-     <listitem>
-      <para>
-       Character set used for filtering. Currently no filter uses this
-       parameter.
-      </para>
-     </listitem>
-    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -72,7 +62,7 @@
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>filter_data</function> example</title>
+    <title>A <function>filter_var</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -96,7 +86,9 @@ bool(false)
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>input_get</function></member>
+    <member><function>filter_var_array</function></member>
+    <member><function>filter_input</function></member>
+    <member><function>filter_input_array</function></member>
     <member>&seealso.callback;</member>
    </simplelist>
   </para>