Skip to content

[Sync-En] filter: add examples for filter_var_array() and filter_input_array() #1142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julionc merged 1 commit into from
Aug 28, 2026
+225 −27
Merged

[Sync-En] filter: add examples for filter_var_array() and filter_input_array() #1142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 123 additions & 17 deletions reference/filter/functions/filter-input-array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 53054bf8decc8648cf2e90a493692a161e2371af Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 85264ba268a398c4b90c1948839d54ce688dd5cd Maintainer: Marqitos Status: ready -->
<refentry xml:id="function.filter-input-array" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
<refnamediv>
<refname>filter_input_array</refname>
Expand Down Expand Up @@ -42,12 +40,8 @@
</warning>
</listitem>
</varlistentry>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.filter-var-array')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='options']]]/.)">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.filter-var-array')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='add_empty']]]/.)">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.filter-var-array')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='options']]]/.)"/>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.filter-var-array')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='add_empty']]]/.)"/>
</variablelist>
</refsect1>

Expand All @@ -58,24 +52,136 @@
</simpara>
<simpara>
En caso de fallo, se devuelve &false;.
Excepto si el fallo es que el array de entrada designado por
<parameter>type</parameter> no está poblado, donde se devuelve &null;
si se usa el flag <constant>FILTER_NULL_ON_FAILURE</constant>.
Si el array de entrada designado por <parameter>type</parameter> no está
poblado, se devuelve &null; en su lugar.
</simpara>
<simpara>
Las entradas faltantes del array de entrada se rellenarán en el array
devuelto si <parameter>add_empty</parameter> es &true;.
En cuyo caso, las entradas faltantes se establecerán en &null;,
a menos que se use el flag <constant>FILTER_NULL_ON_FAILURE</constant>,
en cuyo caso será &false;.
Las entradas faltantes del array de entrada se añaden al &array; devuelto
como &null; si <parameter>add_empty</parameter> es &true;,
y se omiten por completo si es &false;.
A diferencia de <function>filter_input</function>,
el flag <constant>FILTER_NULL_ON_FAILURE</constant> no cambia esto:
una entrada faltante siempre es &null;.
</simpara>
<simpara>
Un valor del array devuelto será &false; si el filtro falla,
a menos que se use el flag <constant>FILTER_NULL_ON_FAILURE</constant>,
en cuyo caso será &null;.
Con el flag <constant>FILTER_FORCE_ARRAY</constant>,
ese valor de fallo se envuelve en un &array; de un solo elemento
como cualquier otro resultado.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Ejemplo de <function>filter_input_array</function></title>
<simpara>
Este ejemplo supone una petición GET a
<literal>?email=user@example.com&amp;age=twenty&amp;url=https://example.com</literal>.
La entrada <literal>age</literal> falla porque <literal>twenty</literal> no
es un entero; un valor fuera del rango de <literal>1</literal> a
<literal>120</literal> fallaría de la misma manera.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$filters = [
'email' => FILTER_VALIDATE_EMAIL,
'age' => [
'filter' => FILTER_VALIDATE_INT,
'options' => ['min_range' => 1, 'max_range' => 120],
],
'url' => FILTER_VALIDATE_URL,
];

$result = filter_input_array(INPUT_GET, $filters);

var_dump($result);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(3) {
["email"]=>
string(16) "user@example.com"
["age"]=>
bool(false)
["url"]=>
string(19) "https://example.com"
}
]]>
</screen>
</example>
<example>
<title>Filtrado de datos POST con <function>filter_input_array</function></title>
<simpara>
Este ejemplo supone una petición POST con los campos
<literal>username=&lt;script&gt;alert&lt;/script&gt;</literal> y
<literal>comment=Hello World</literal>.
No se envía ningún campo <literal>missing</literal>: como
<parameter>add_empty</parameter> vale &true; por defecto, sigue estando
presente en el resultado, establecido a &null;.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$filters = [
'username' => FILTER_SANITIZE_SPECIAL_CHARS,
'comment' => FILTER_SANITIZE_SPECIAL_CHARS,
'missing' => FILTER_VALIDATE_INT,
];

$result = filter_input_array(INPUT_POST, $filters);

var_dump($result);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(3) {
["username"]=>
string(38) "&#60;script&#62;alert&#60;/script&#62;"
["comment"]=>
string(11) "Hello World"
["missing"]=>
NULL
}
]]>
</screen>
</example>
<example>
<title>Petición de un tipo de entrada que no está poblado</title>
<simpara>
Este ejemplo supone una petición GET.
Como la petición no llevaba ningún campo POST,
el array de entrada designado por <constant>INPUT_POST</constant> no está
poblado y se devuelve &null; en lugar de un &array;.
Esto se aplica a todos los tipos de entrada:
una petición sin cadena de consulta devuelve también &null; para
<constant>INPUT_GET</constant>.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
var_dump(filter_input_array(INPUT_POST, ['a' => FILTER_VALIDATE_INT]));
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
NULL
]]>
</screen>
</example>
</refsect1>

<refsect1 role="notes">
&reftitle.notes;
<note>
Expand Down
112 changes: 102 additions & 10 deletions reference/filter/functions/filter-var-array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 627f933cfe6a033dccac32982cd68e7c1b86927f Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 85264ba268a398c4b90c1948839d54ce688dd5cd Maintainer: Marqitos Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.filter-var-array">
<refnamediv>
<refname>filter_var_array</refname>
Expand Down Expand Up @@ -50,7 +48,7 @@
</simpara>
<simpara>
La array de opciones es un array asociativo donde la clave corresponde
a una clave en la matriz de datos <parameter>array</parameter> y el valor
a una clave del array de entrada y el valor
asociado es el filtro a aplicar a esta entrada,
o un array asociativo que describe cómo y qué filtro se debe
aplicar a esta entrada.
Expand All @@ -64,7 +62,7 @@
<constant>FILTER_UNSAFE_RAW</constant>, o
<constant>FILTER_CALLBACK</constant>.
Opcionalmente, puede contener la clave <literal>'flags'</literal>,
que especifica los indicadores que se aplican al filtro,
que especifica cualquier flag que se aplique al filtro,
y la clave <literal>'options'</literal>, que especifica las opciones
que se aplican al filtro.
</simpara>
Expand All @@ -83,17 +81,39 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
En caso de éxito un array que contiene los valores de las variables que se
han pedido o &false; en caso de fallo. El valor del array será &false; si
el filtro falla o &null; si la variable no está definida.
</para>
<simpara>
En caso de éxito, un &array; que contiene los valores de las variables solicitadas.
</simpara>
<simpara>
En caso de fallo, se devuelve &false;.
</simpara>
<simpara>
Las entradas faltantes del array de entrada se añaden al &array; devuelto
como &null; si <parameter>add_empty</parameter> es &true;,
y se omiten por completo si es &false;.
</simpara>
<simpara>
Un valor del array devuelto será &false; si el filtro falla,
a menos que se use el flag <constant>FILTER_NULL_ON_FAILURE</constant>,
en cuyo caso será &null;.
Con el flag <constant>FILTER_FORCE_ARRAY</constant>,
ese valor de fallo se envuelve en un &array; de un solo elemento
como cualquier otro resultado.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Ejemplo de <function>filter_var_array</function></title>
<simpara>
Las entradas se filtran como escalares a menos que se use
<constant>FILTER_REQUIRE_ARRAY</constant> o
<constant>FILTER_FORCE_ARRAY</constant>.
Por lo tanto, el flag <constant>FILTER_REQUIRE_SCALAR</constant> en
<literal>testscalar</literal>, a continuación, solo indica ese
comportamiento por defecto de forma explícita.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
Expand Down Expand Up @@ -158,6 +178,78 @@ array(6) {
["doesnotexist"]=>
NULL
}
]]>
</screen>
</example>
<example>
<title>Aplicación de un único filtro a todos los valores</title>
<simpara>
Cuando <parameter>options</parameter> es un &integer;, se aplica el mismo
filtro a cada entrada del array.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$data = [
'name' => '<b>John</b>',
'email' => 'john@example<script>.com',
'bio' => 'Developer & writer',
];

var_dump(filter_var_array($data, FILTER_SANITIZE_SPECIAL_CHARS));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["name"]=>
string(27) "&#60;b&#62;John&#60;/b&#62;"
["email"]=>
string(32) "john@example&#60;script&#62;.com"
["bio"]=>
string(22) "Developer &#38; writer"
}
]]>
</screen>
</example>
<example>
<title>Uso de <constant>FILTER_CALLBACK</constant></title>
<programlisting role="php">
<![CDATA[
<?php
$data = [
'name' => ' John Doe ',
'city' => ' New York ',
];

$options = [
'name' => [
'filter' => FILTER_CALLBACK,
'options' => 'trim',
],
'city' => [
'filter' => FILTER_CALLBACK,
'options' => function ($value) {
return strtoupper(trim($value));
},
],
];

var_dump(filter_var_array($data, $options));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["name"]=>
string(8) "John Doe"
["city"]=>
string(8) "NEW YORK"
}
]]>
</screen>
</example>
Expand Down