Skip to content

[Sync-EN] Add examples for filter_var_array() and filter_input_array() #1790

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

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[Sync-EN] Add examples for filter_var_array() and filter_input_array() #1790

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
170 changes: 99 additions & 71 deletions reference/filter/functions/filter-input-array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 53054bf8decc8648cf2e90a493692a161e2371af Maintainer: shein Status: ready -->
<!-- EN-Revision: 85264ba268a398c4b90c1948839d54ce688dd5cd Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="function.filter-input-array">
<refnamediv>
Expand Down Expand Up @@ -39,12 +39,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 @@ -56,98 +52,130 @@
</simpara>
<simpara>
Функция возвращает значение &false; в случае возникновения ошибки.
Если входной массив, определяемый параметром <parameter>type</parameter>, не заполнен,
функция вернёт значение &null;, если флаг <constant>FILTER_NULL_ON_FAILURE</constant>
не задан.
Если входной массив, который определяет параметр <parameter>type</parameter>,
не заполнен, функция вместо этого вернёт значение &null;.
</simpara>
<simpara>
Недостающие записи входного массива будут заполнены в возвращаемый массив (&array;),
если значение параметра <parameter>add_empty</parameter> равно &true;.
В этом случае отсутствующим записям будем присвоено значение &null;,
если только не используется флаг <constant>FILTER_NULL_ON_FAILURE</constant>,
в этом случае записям будет присвоено значение &false;.
Недостающие записи входного массива добавляются в возвращаемый массив (&array;)
со значением &null;, если значение параметра <parameter>add_empty</parameter>
равно &true;, и полностью пропускаются, если оно равно &false;.
В отличие от функции <function>filter_input</function>, флаг
<constant>FILTER_NULL_ON_FAILURE</constant> это не меняет: отсутствующая
запись всегда равна &null;.
</simpara>
<simpara>
Элемент возвращаемого массива (&array;) будет &false;,
если фильтр не сработал, если только не используется флаг <constant>FILTER_NULL_ON_FAILURE</constant>,
в этом случае он будет &null;.
С флагом <constant>FILTER_FORCE_ARRAY</constant> это значение неудачи,
как и любой другой результат, оборачивается в массив из одного элемента.
</simpara>

</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Пример использования <function>filter_input_array</function></title>
<title>Пример использования функции <function>filter_input_array</function></title>
<simpara>
Пример предполагает GET-запрос вида
<literal>?email=user@example.com&amp;age=twenty&amp;url=https://example.com</literal>.
Запись <literal>age</literal> не проходит фильтр, потому что
<literal>twenty</literal> — не целое число; значение за пределами диапазона
от <literal>1</literal> до <literal>120</literal> не прошло бы фильтр так же.
</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,
];

/* данные, полученные методом POST
$_POST = array(
'product_id' => 'libgd<script>',
'component' => array('10'),
'version' => '2.0.33',
'testarray' => array('2', '23', '10', '12'),
'testscalar' => '2',
);
*/
$result = filter_input_array(INPUT_GET, $filters);

$args = array(
'product_id' => FILTER_SANITIZE_ENCODED,
'component' => array('filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_ARRAY,
'options' => array('min_range' => 1, 'max_range' => 10)
),
'version' => FILTER_SANITIZE_ENCODED,
'doesnotexist' => FILTER_VALIDATE_INT,
'testscalar' => array(
'filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_SCALAR,
),
'testarray' => array(
'filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_ARRAY,
)

);
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>Фильтрация POST-данных функцией <function>filter_input_array</function></title>
<simpara>
Пример предполагает POST-запрос с полями
<literal>username=&lt;script&gt;alert&lt;/script&gt;</literal> и
<literal>comment=Hello World</literal>.
Поле <literal>missing</literal> не передали: поскольку значение параметра
<parameter>add_empty</parameter> по умолчанию равно &true;, поле всё равно
попадает в результат со значением &null;.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$filters = [
'username' => FILTER_SANITIZE_SPECIAL_CHARS,
'comment' => FILTER_SANITIZE_SPECIAL_CHARS,
'missing' => FILTER_VALIDATE_INT,
];

$myinputs = filter_input_array(INPUT_POST, $args);
$result = filter_input_array(INPUT_POST, $filters);

var_dump($myinputs);
echo "\n";
var_dump($result);
?>
]]>
</programlisting>
&example.outputs;
&example.outputs.similar;
<screen>
<![CDATA[
array(6) {
["product_id"]=>
string(17) "libgd%3Cscript%3E"
["component"]=>
array(1) {
[0]=>
int(10)
}
["version"]=>
string(6) "2.0.33"
["doesnotexist"]=>
array(3) {
["username"]=>
string(38) "&#60;script&#62;alert&#60;/script&#62;"
["comment"]=>
string(11) "Hello World"
["missing"]=>
NULL
["testscalar"]=>
int(2)
["testarray"]=>
array(4) {
[0]=>
int(2)
[1]=>
int(23)
[2]=>
int(10)
[3]=>
int(12)
}
}
]]>
</screen>
</example>
<example>
<title>Запрос незаполненного типа входных данных</title>
<simpara>
Пример предполагает GET-запрос.
Поскольку запрос не нёс POST-полей, входной массив, который определяет
константа <constant>INPUT_POST</constant>, не заполнен, и вместо массива
(&array;) функция возвращает &null;.
Это относится к каждому типу входных данных: запрос без строки запроса
точно так же даст &null; для константы <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>
Expand Down
111 changes: 102 additions & 9 deletions reference/filter/functions/filter-var-array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 627f933cfe6a033dccac32982cd68e7c1b86927f Maintainer: shein Status: ready -->
<!-- EN-Revision: 85264ba268a398c4b90c1948839d54ce688dd5cd Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.filter-var-array">
<refnamediv>
Expand Down Expand Up @@ -46,7 +46,7 @@
</simpara>
<simpara>
Массив опций – это ассоциативный массив, в котором ключ соответствует ключу
в массиве данных параметра <parameter>array</parameter>,
во входном массиве,
а связанное с ним значение – это либо фильтр, который нужно применить к этой записи,
либо ассоциативный массив, описывающий, как и какой фильтр должен быть применён к этой записи.
</simpara>
Expand All @@ -56,8 +56,8 @@
который может быть одной из констант <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>,
<constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>,
<constant>FILTER_UNSAFE_RAW</constant> или <constant>FILTER_CALLBACK</constant>.
Дополнительно может содержать ключ <literal>'flags'</literal>, задающий флаги,
которые применяются к фильтру и ключ <literal>'options'</literal>,
Дополнительно может содержать ключ <literal>'flags'</literal>, задающий любые флаги,
которые применяются к фильтру, и ключ <literal>'options'</literal>,
задающий любые опции, которые применяются к фильтру.
</simpara>
</listitem>
Expand All @@ -75,17 +75,38 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Массив, содержащий значения запрошенных переменных в случае успешного выполнения, или &false;
в случае возникновения ошибки. Значение массива будет &false;, если фильтрация завершилась неудачей, или &null;,
если переменная не определена.
</para>
<simpara>
В случае успешного выполнения функция возвращает массив (&array;),
который содержит значения запрошенных переменных.
</simpara>
<simpara>
Функция возвращает значение &false; в случае возникновения ошибки.
</simpara>
<simpara>
Недостающие записи входного массива добавляются в возвращаемый массив (&array;)
со значением &null;, если значение параметра <parameter>add_empty</parameter>
равно &true;, и полностью пропускаются, если оно равно &false;.
</simpara>
<simpara>
Элемент возвращаемого массива (&array;) будет &false;,
если фильтр не сработал, если только не используется флаг
<constant>FILTER_NULL_ON_FAILURE</constant>, в этом случае он будет &null;.
С флагом <constant>FILTER_FORCE_ARRAY</constant> это значение неудачи,
как и любой другой результат, оборачивается в массив из одного элемента.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Пример использования <function>filter_var_array</function></title>
<simpara>
Записи фильтруются как скалярные значения, если не указали флаг
<constant>FILTER_REQUIRE_ARRAY</constant> или
<constant>FILTER_FORCE_ARRAY</constant>.
Поэтому флаг <constant>FILTER_REQUIRE_SCALAR</constant> у записи
<literal>testscalar</literal> ниже лишь задаёт это поведение явно.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
Expand Down Expand Up @@ -150,6 +171,78 @@ array(6) {
["doesnotexist"]=>
NULL
}
]]>
</screen>
</example>
<example>
<title>Применение одного фильтра ко всем значениям</title>
<simpara>
Когда в параметре <parameter>options</parameter> передали целое число
(&integer;), один и тот же фильтр применяется к каждой записи массива.
</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>Применение фильтра <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
Loading