<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20115 -->
    <!-- Reviewed: no -->
<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
                <acronym>HTML</acronym> 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
                <acronym>HTML</acronym> entities or contain only escaped
                <acronym>HTML</acronym> entities, in order to prevent undesired
            behavior and security vulnerabilities. To meet this requirement,
                <acronym>HTML</acronym> 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
                <acronym>HTML</acronym> 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 <acronym>HTML</acronym>
            entities, however, transforms the input (e.g., "
                <code>&amp;</code> " is transformed to "
                <code>&amp;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
            <acronym>HTML</acronym> . 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 <acronym>HTML</acronym> o sólo contener entidades
            <acronym>HTML</acronym> de forma escapada, a fin de evitar
        comportamientos no deseados y vulnerabilidades de seguridad. Para
        cumplir este requerimiento, las entidades <acronym>HTML</acronym> 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 <acronym>HTML</acronym> 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 <acronym>HTML</acronym> , sin embargo, transforma la
        entrada (por ejemplo, " <code> &amp;</code> " se transforma en "
            <code> &amp;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>&amp;</code> ) and double quote (
                <code>&quot;</code> ) characters: <programlisting language="php"><![CDATA[
$htmlEntities = new Zend_Filter_HtmlEntities();

echo $htmlEntities->filter('&'); // &amp;
echo $htmlEntities->filter('"'); // &quot;
]]></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 <constant>TRUE</constant> when one or more default
                        namespaces are set, and <constant>FALSE</constant> when no default namespaces
                        are set. </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>
