Skip to content

[Sync-En] filter: split the constants into separate files #1361

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] filter: split the constants into separate files #1361

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
115 changes: 115 additions & 0 deletions reference/filter/constants.callback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a109099b7deda187b68d43d8a90393620eaeb8e1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes Maintainer: Marqitos -->
<section xml:id="filter.constants.callback" xmlns="http://docbook.org/ns/docbook">
<title>Filtro definido por el usuario</title>
&extension.constants;
<variablelist>
<varlistentry xml:id="constant.filter-callback">
<term>
<constant>FILTER_CALLBACK</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Este filtro delega el filtrado a una función definida por el usuario.
El <type>callable</type> se pasa a través del
parámetro <parameter>options</parameter> como el valor asociado a
la clave <literal>'options'</literal>.
</simpara>
<para>
La retrollamada debe tener la siguiente firma:
<methodsynopsis>
<type>mixed</type><methodname><replaceable>callback</replaceable></methodname>
<methodparam><type>string</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<variablelist role="function_parameters">
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<simpara>
El valor que está siendo filtrado.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<simpara>
El valor devuelto por la retrollamada será el valor devuelto por
la función de filtro invocada.
</simpara>
</note>
<example>
<title>
Ejemplo de uso de <constant>FILTER_CALLBACK</constant> para validar
un nombre de inicio de sesión
</title>
<programlisting role="php">
<![CDATA[
<?php
function validate_login(string $value): ?string
{
if (strlen($value) >= 5 && ctype_alnum($value)) {
return $value;
}
return null;
}

$login = "val1dL0gin";
$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']);
var_dump($filtered_login);

$login = "f&ke login";
$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']);
var_dump($filtered_login);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(10) "val1dL0gin"
NULL
]]>
</screen>
</example>
<note>
<simpara>
A partir de PHP 8.1.25 y 8.2.12, los flags estructurales
<constant>FILTER_REQUIRE_ARRAY</constant>,
<constant>FILTER_FORCE_ARRAY</constant> y
<constant>FILTER_REQUIRE_SCALAR</constant> se aplican a este filtro, y
<constant>FILTER_NULL_ON_FAILURE</constant> cambia la forma en que se
informa de tal fallo estructural. En versiones anteriores todos los flags
eran ignorados. Los flags específicos del filtro siempre son ignorados y,
dado que el valor devuelto por la retrollamada es el resultado, la
retrollamada en sí misma no puede fallar: ningún flag convierte un
<literal>false</literal> devuelto por la retrollamada en &null; o en una
excepción.
</simpara>
</note>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- 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:"~/.phpdoc/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
-->
108 changes: 108 additions & 0 deletions reference/filter/constants.flags.generic.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a109099b7deda187b68d43d8a90393620eaeb8e1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes Maintainer: Marqitos -->
<section xml:id="filter.constants.flags.generic" xmlns="http://docbook.org/ns/docbook">
<title>Flags genéricos de filtro</title>
&extension.constants;
<variablelist>
<varlistentry xml:id="constant.filter-flag-none">
<term>
<constant>FILTER_FLAG_NONE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Sin flags.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-require-scalar">
<term>
<constant>FILTER_REQUIRE_SCALAR</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Flag utilizado para requerir que la entrada del filtro sea un escalar.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-require-array">
<term>
<constant>FILTER_REQUIRE_ARRAY</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Flag utilizado para requerir que la entrada del filtro sea un <type>array</type>.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-force-array">
<term>
<constant>FILTER_FORCE_ARRAY</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Este flag envuelve las entradas escalares en un <type>array</type> de un elemento
para filtros que operan sobre arrays.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-null-on-failure">
<term>
<constant>FILTER_NULL_ON_FAILURE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Usar &null; en lugar de &false; en caso de fallo.
</simpara>
<simpara>
Utilizable con cualquier filtro de validación
<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-throw-on-failure">
<term>
<constant>FILTER_THROW_ON_FAILURE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Lanza una <exceptionname>Filter\FilterFailedException</exceptionname> cuando un
filtro de validación falla, en lugar de devolver &false;.
</simpara>
<simpara>
Utilizable con cualquier filtro de validación
<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>.
</simpara>
<simpara>
Disponible a partir de PHP 8.5.0.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- 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:"~/.phpdoc/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
-->
120 changes: 120 additions & 0 deletions reference/filter/constants.flags.sanitization.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a109099b7deda187b68d43d8a90393620eaeb8e1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes Maintainer: Marqitos -->
<section xml:id="filter.constants.flags.sanitization" xmlns="http://docbook.org/ns/docbook">
<title>Flags de filtro de saneamiento</title>
&extension.constants;
<variablelist>
<varlistentry xml:id="constant.filter-flag-strip-low">
<term>
<constant>FILTER_FLAG_STRIP_LOW</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Elimina caracteres con valor ASCII menor que 32.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-strip-high">
<term>
<constant>FILTER_FLAG_STRIP_HIGH</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Elimina caracteres con valor ASCII mayor que 127.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-strip-backtick">
<term>
<constant>FILTER_FLAG_STRIP_BACKTICK</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Elimina caracteres de comilla invertida (<literal>`</literal>).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-encode-low">
<term>
<constant>FILTER_FLAG_ENCODE_LOW</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Codifica caracteres con valor ASCII menor que 32.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-encode-high">
<term>
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Codifica caracteres con valor ASCII mayor que 127.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-encode-amp">
<term>
<constant>FILTER_FLAG_ENCODE_AMP</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Codifica <literal>&amp;</literal>.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-no-encode-quotes">
<term>
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Las comillas simples y dobles (<literal>'</literal> y <literal>"</literal>)
no serán codificadas.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.filter-flag-empty-string-null">
<term>
<constant>FILTER_FLAG_EMPTY_STRING_NULL</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
<!-- TODO Document/check which filters accept this flag (FILTER_UNSAFE_RAW and FILTER_SANITIZE_STRING only) -->
Si el saneamiento de un string resulta en un string vacío,
convierte el valor a &null;
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- 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:"~/.phpdoc/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
-->
Loading
Loading