|
|
@@ -0,0 +1,219 @@
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- EN-Revision: 17344 -->
|
|
|
+<sect1 id="zend.filter.introduction">
|
|
|
+
|
|
|
+ <title>Introducción</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ El componente <classname>Zend_Filter</classname> proporciona un conjunto
|
|
|
+ de filtros de datos comúnmente necesarios. También proporciona un sencillo
|
|
|
+ mecanismo de encadenar varios filtros que se puedan aplicar a un solo dato
|
|
|
+ en un orden definido por el usuario.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <sect2 id="zend.filter.introduction.definition">
|
|
|
+
|
|
|
+ <title>¿Qué es un filtro?</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ En el mundo físico, un filtro se suele utilizar para eliminar
|
|
|
+ partes no deseadas de lo ingresado, y la vez lo ingresado
|
|
|
+ pasa a través de un filtro de salida (por ejemplo, el café).
|
|
|
+ En este caso, un filtro es un operador que devuelve una parte de los
|
|
|
+ datos de entrada. Este tipo de filtro es útil para aplicaciones web,
|
|
|
+ para la supresión de entradas ilegales y/o que no se ajustan,
|
|
|
+ eliminación de los espacios en blanco innecesarios, etc
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ This basic definition of a filter may be extended to include
|
|
|
+ generalized transformations upon input. A common transformation
|
|
|
+ applied in web applications is the escaping of HTML entities. For
|
|
|
+ example, if a form field is automatically populated with untrusted
|
|
|
+ input (e.g., from a web browser), this value should either be free
|
|
|
+ of HTML entities or contain only escaped HTML entities, in order to
|
|
|
+ prevent undesired behavior and security vulnerabilities. To meet
|
|
|
+ this requirement, HTML entities that appear in the input must
|
|
|
+ either be removed or escaped. Of course, which approach is more
|
|
|
+ appropriate depends on the situation. A filter that removes the
|
|
|
+ HTML entities operates within the scope of the first definition of
|
|
|
+ filter - an operator that produces a subset of the input. A filter
|
|
|
+ that escapes the HTML entities, however, transforms the input
|
|
|
+ (e.g., "<code>&</code>" is transformed to
|
|
|
+ "<code>&amp;</code>"). Supporting such use cases for web
|
|
|
+ developers is important, and "to filter," in the context of using
|
|
|
+ <classname>Zend_Filter</classname>, means to perform some transformations upon input data.
|
|
|
+ </para>
|
|
|
+
|
|
|
+
|
|
|
+ Esta definición básica de un filtro puede ser extendido para incluir
|
|
|
+ transformaciones generalizadas sobre la entrada. Una transformación común
|
|
|
+ requerida en las aplicaciones web es la de escapar las entidades HTML. Por
|
|
|
+ ejemplo, si un campo del formulario es completado automáticamente y contiene datos no verificados
|
|
|
+ (por ejemplo, datos ingresados desde un navegador web), este valor debe estar libre
|
|
|
+ de las entidades HTML o sólo contener entidades HTML de forma escapada, a fin de
|
|
|
+ evitar comportamientos no deseados y vulnerabilidades de seguridad. Para cumplir
|
|
|
+ este requerimiento, las entidades HTML que aparecen en los datos introducidos deben
|
|
|
+ ser suprimidos o escapados. Por supuesto, el enfoque más
|
|
|
+ adecuado depende del contexto y de la situción. Un filtro que quita las
|
|
|
+ entidades HTML funciona dentro del ámbito o alcance de la primera definición del
|
|
|
+ filtro - un operador que produce un subconjunto de la entrada. Un filtro
|
|
|
+ que escapa a las entidades HTML, sin embargo, transforma la entrada
|
|
|
+ (por ejemplo, "<code> &</code>" se transforma en
|
|
|
+ "<code> &amp;</code>"). El Apoyo a los casos de uso como para la web
|
|
|
+ los desarrolladores es importante, y "filtrar", en el contexto de la utilización de
|
|
|
+ <classname> Zend_Filter </ className>, los medios para realizar algunas transformaciones en los datos de entrada.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="zend.filter.introduction.using">
|
|
|
+
|
|
|
+ <title>Uso básico de los filtros</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Having this filter definition established provides the foundation
|
|
|
+ for <classname>Zend_Filter_Interface</classname>, which requires a single
|
|
|
+ method named <methodname>filter()</methodname> to be implemented by a filter
|
|
|
+ class.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Following is a basic example of using a filter upon two input data,
|
|
|
+ the ampersand (<code>&</code>) and double quote
|
|
|
+ (<code>"</code>) characters:
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$htmlEntities = new Zend_Filter_HtmlEntities();
|
|
|
+
|
|
|
+echo $htmlEntities->filter('&'); // &
|
|
|
+echo $htmlEntities->filter('"'); // "
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ </para>
|
|
|
+
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="zend.filter.introduction.static">
|
|
|
+
|
|
|
+ <title> Usando el método estático staticFilter()</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ If it is inconvenient to load a given filter class and create an
|
|
|
+ instance of the filter, you can use the static method
|
|
|
+ <methodname>Zend_Filter::filterStatic()</methodname> as an alternative invocation style.
|
|
|
+ The first argument of this method is a data input value, that you
|
|
|
+ would pass to the <methodname>filter()</methodname> method. The second
|
|
|
+ argument is a string, which corresponds to the basename of the
|
|
|
+ filter class, relative to the Zend_Filter namespace. The
|
|
|
+ <methodname>staticFilter()</methodname> method automatically loads the class, creates
|
|
|
+ an instance, and applies the <methodname>filter()</methodname> method to the data
|
|
|
+ input.
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+echo Zend_Filter::filterStatic('&', 'HtmlEntities');
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ You can also pass an array of constructor arguments, if they
|
|
|
+ are needed for the filter class.
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+echo Zend_Filter::filterStatic('"', 'HtmlEntities', array(ENT_QUOTES));
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The static usage can be convenient for invoking a filter ad hoc,
|
|
|
+ but if you have the need to run a filter for multiple inputs,
|
|
|
+ it's more efficient to follow the first example above,
|
|
|
+ creating an instance of the filter object and calling its
|
|
|
+ <methodname>filter()</methodname> method.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Also, the <classname>Zend_Filter_Input</classname> class allows you to instantiate and run
|
|
|
+ multiple filter and validator classes on demand to process
|
|
|
+ sets of input data. See <xref linkend="zend.filter.input" />.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <sect3 id="zend.filter.introduction.static.namespaces">
|
|
|
+
|
|
|
+ <title>Namespaces</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ When working with self defined filters you can give a forth parameter
|
|
|
+ to <methodname>Zend_Filter::filterStatic()</methodname> which is the namespace
|
|
|
+ where your filter can be found.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+echo Zend_Filter::filterStatic(
|
|
|
+ '"',
|
|
|
+ 'MyFilter',
|
|
|
+ array($parameters),
|
|
|
+ array('FirstNamespace', 'SecondNamespace')
|
|
|
+);
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <classname>Zend_Filter</classname> allows also to set namespaces as default.
|
|
|
+ This means that you can set them once in your bootstrap and have not to give
|
|
|
+ them again for each call of <methodname>Zend_Filter::filterStatic()</methodname>.
|
|
|
+ The following code snippet is identical to the above one.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+Zend_Filter::setDefaultNamespaces(array('FirstNamespace', 'SecondNamespace'));
|
|
|
+echo Zend_Filter::filterStatic('"', 'MyFilter', array($parameters));
|
|
|
+echo Zend_Filter::filterStatic('"', 'OtherFilter', array($parameters));
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ For your convinience there are following methods which allow the handling of
|
|
|
+ namespaces:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ <emphasis><methodname>Zend_Filter::getDefaultNamespaces()</methodname></emphasis>:
|
|
|
+ Returns all set default namespaces as array.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ <emphasis><methodname>Zend_Filter::setDefaultNamespaces()</methodname></emphasis>:
|
|
|
+ Sets new default namespaces and overrides any previous set. It accepts
|
|
|
+ eighter a string for a single namespace of an array for multiple namespaces.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ <emphasis><methodname>Zend_Filter::addDefaultNamespaces()</methodname></emphasis>:
|
|
|
+ Adds additional namespaces to already set ones. It accepts eighter a string
|
|
|
+ for a single namespace of an array for multiple namespaces.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ <emphasis><methodname>Zend_Filter::hasDefaultNamespaces()</methodname></emphasis>:
|
|
|
+ Returns true when one or more default namespaces are set, and false when no
|
|
|
+ default namespaces are set.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+</sect1>
|
|
|
+<!--
|
|
|
+vim:se ts=4 sw=4 et:
|
|
|
+-->
|
benjamin-gonzales