repo_zf1/documentation/manual/es/module_specs/Zend_Controller-Request.xml

<?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 17597 -->
    <!-- Reviewed: no -->
<sect1 id="zend.controller.request">
    <title>La solicitud del Objeto</title>
    <sect2 id="zend.controller.request.introduction">
        <title>Introducción</title>
        <para>
            El objeto request es un objeto de valor simple que es pasado
            entre
            <classname>Zend_Controller_Front</classname>
            y el router,
            dispatcher, y clases de controlador. Empaqueta los nombres del
            módulo
            solicitado, controlador, acción, y los parámetros opcionales,
            así como el resto del
            entorno de la solicitud, ya sea
            <acronym>HTTP</acronym>
            , el
            <acronym>CLI</acronym>
            , o
            <acronym>PHP</acronym>
            -GTK.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    El nombre del módulo es accedido por
                    <methodname>getModuleName()</methodname>
                    y
                    <methodname>setModuleName()</methodname>
                    .
                </para>
            </listitem>

            <listitem>
                <para>
                    El nombre del controlador es accedido por
                    <methodname>getControllerName()</methodname>
                    y
                    <methodname>setControllerName()</methodname>
                    .
                </para>
            </listitem>

            <listitem>
                <para>
                    El nombre de la acción que llamar dentro del controlador
                    es accedido por
                    <methodname>getActionName()</methodname>
                    y
                    <methodname>setActionName()</methodname>
                    .
                </para>
            </listitem>

            <listitem>
                <para>
                    Los parámetros accesibles por la acción son un array
                    asociativo de pares
                    clave/valor que son recuperados por
                    <methodname>getParams()</methodname>
                    y configurados con
                    <methodname>setParams()</methodname>
                    , o configurados
                    individualmente por
                    <methodname>getParam()</methodname>
                    y
                    <methodname>setParam()</methodname>
                    .
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Basado en el tipo de solicitud, puede haber más métodos
            disponibles. La solicitud por
            defecto usada,
            <classname>Zend_Controller_Request_Http</classname>
            , por
            ejemplo, tiene métodos para recuperar la
            <acronym>URI</acronym>
            de
            la solicitud, ruta de la información, parámetros
            <varname>$_GET</varname>
            y
            <varname>$_POST</varname>
            , etc.
        </para>

        <para>El objeto request es pasado al controlador front, o si no es
            provisto, es instanciado
            al principio del proceso dispatcher, antes
            de que ocurra el enrutamiento. Es pasado a
            través de todos los
            objetos en la cadena del dispatcher.</para>

        <para>
            Adicionalmente, la solicitud objeto es particularmente útil en
            pruebas. El desarrolador
            puede cambiar el entorno de la solicitud,
            incluyendo módulos, controladores, acciones,
            parámetros,
            <acronym>URI</acronym>
            , etc, y pasar la solicitud objeto al
            controlador front para probar el flujo de la
            aplicación. Cuando se
            vincula con el
            <link linkend="zend.controller.response">objeto
                respuesta </link>
            , es posible elaborar y precisar una unidad de
            pruebas de aplicaciones
            <acronym>MVC</acronym>
            .
        </para>
    </sect2>

    <sect2 id="zend.controller.request.http">
        <title>Solicitud HTTP</title>

        <sect3 id="zend.controller.request.http.dataacess">
            <title>Solicitud de acceso a datos</title>

            <para>
                <classname>Zend_Controller_Request_Http</classname>
                encapsula el
                acceso a relevantes valores tal como el nombre de la llave y el
                valor
                para el controlador y variables de aación enrutamiento y
                todos los parámetros
                adicionales analizados desde el
                <acronym>URI</acronym>
                . Adiccionalmente permite el acceso a
                valores contenidos en las superglobales como
                miembros públicos y
                administra la actual base
                <acronym>URL</acronym>
                y la solicitud
                <acronym>URI</acronym>
                . los valores Superglobales no pueden
                ser determinados en una solicitud objeto, en
                vez usar los
                métodos
                <methodname>setParam()</methodname>
                y
                <methodname>getParam()</methodname>
                para determinar o
                recuperar los parámetros del usuario.
            </para>

            <note>
                <title>Datos Superglobales</title>
                <para>
                    Cuando se accede a datos Superglobales a través
                    <classname>Zend_Controller_Request_Http</classname>
                    como
                    propiedades de miembros públicos, es necesario mantener en
                    mente que el
                    nombre de la propiedad (supergloabl array key)
                    corresponda a una supergloabl en
                    un específico orden de
                    precedencia:1.
                    <constant>GET</constant>
                    , 2.
                    <constant>POST</constant>
                    , 3.
                    <constant>COOKIE</constant>
                    , 4.
                    <constant>SERVER</constant>
                    , 5.
                    <constant>ENV</constant>
                    .
                </para>
            </note>

            <para>
                Las supergloables específicas pueden ser accedidas usando un
                método público como una
                alternativa. Por ejemplo, el valor
                original de
                <varname>$_POST['user']</varname>
                puede ser accedido
                llamando a
                <methodname>getPost('user')</methodname>
                en la
                solicitud objeto. Esto incluye
                <methodname>getQuery()</methodname>
                para recuperar elementos
                <varname>$_GET</varname>
                , y
                <methodname>getHeader()</methodname>
                para recuperar la
                solicitud de los encabezadores (headers).
            </para>

            <note>
                <title>Datos GET y POST</title>
                <para>Sea cauteloso cuando accede a los datos de la solicitud
                    objeto como no es
                    filtrado en ninguna manera. El router y
                    dispatcher valida y filtra datos para
                    usar con sus tareas,
                    pero dejan los datos intactos en la solicitud objeto.
               </para>
            </note>

            <note>
                <title>Recuperando los datos POST sin procesar</title>

                <para>
                    Como 1.5.0, se puede recuperar los datos sin procesar a
                    través del método
                    <methodname>getRawBody()</methodname>
                    .
                    Este método retorna falso si los datos han sido enviados de
                    esa manera, pero si
                    no retorna el cuerpo entero del post.
                </para>

                <para>
                    Esto es primordialmente útil para aceptar el contenido
                    cuando se desarrolla una
                    aplicación
                    <acronym>MVC</acronym>
                    simple.
                </para>
            </note>

            <para>
                Usted puede determinar parámetros de usuario en la solicitud
                objeto usando
                <methodname>setParam()</methodname>
                y recuperar
                los mismos despues usando
                <methodname>getParam()</methodname>
                .
                El router hace uso de esta funcionalidad para determinar
                parámetros correspondientes
                en la solicitud
                <acronym>URI</acronym>
                a la solicitud objeto.
            </para>

            <note>
                <title>getParam() Recupera mas que Parámetros de Usuario</title>

                <para>
                    En orden para hacer el mismo trabajo,
                    <methodname>getParam()</methodname>
                    recupera actualmente
                    desde muchas fuentes. En orden de prioridad, estas incluyen:
                    parámetros de usuario determinados a través de
                    <methodname>setParam()</methodname>
                    , parámetros
                    <constant>GET</constant>
                    , y finalmente parámetros
                    <constant>POST</constant>
                    . Ser conciente de esto cuando
                    se sacan datos a través de este método.
                </para>

                <para>
                    Si se desea sacar solo desde parámetros se configura a
                    través de
                    <methodname>setParam()</methodname>
                    , use
                    <methodname>getUserParam()</methodname>
                    .
                </para>

                <para>
                    Además, a partir de 1.5.0, puede bloquear el parámetro
                    que se buscará en las
                    fuentes.
                    <methodname>setParamSources()</methodname>
                    le permite
                    especificar un array vacío o un array con uno o más de los
                    valores
                    '_GET' o '_POST', indicando que fuente de parámetro
                    se permite (por defecto,
                    ambos son permitidos); si se desea
                    restringir el acceso a solamente '_GET'
                    especificar
                    <methodname>setParamSources
                        (array('_GET'))</methodname>
                    .
                </para>
            </note>

            <note>
                <title>Apache Quirks</title>
                <para>
                    Si está usando Apache 404 handler para pasar If you are
                    using Apache's 404
                    handler to pass incoming requests to the
                    front controller, or using a PT flag
                    with rewrite rules,
                    <varname>$_SERVER['REDIRECT_URL']</varname>
                    contains the
                    <acronym>URI</acronym>
                    you need, not
                    <varname>$_SERVER['REQUEST_URI']</varname>
                    . If you are
                    using such a setup and getting invalid routing, you should
                    use the
                    <classname>Zend_Controller_Request_Apache404</classname>
                    class instead of the default
                    <acronym>HTTP</acronym>
                    class for your request
                    object:
                </para>

                <programlisting language="php"><![CDATA[
$request = new Zend_Controller_Request_Apache404();
$front->setRequest($request);
]]></programlisting>

                <para>
                    This class extends the
                    <classname>Zend_Controller_Request_Http</classname>
                    class and simply modifies the autodiscovery of the request
                    URI. It can be used as
                    a drop-in replacement.
                </para>
            </note>
        </sect3>

        <sect3 id="zend.controller.request.http.baseurl">
            <title>Base Url and Subdirectories</title>

            <para>
                <classname>Zend_Controller_Request_Http</classname>
                allows
                <classname>Zend_Controller_Router_Rewrite</classname>
                to be
                used in subdirectories.
                <classname>Zend_Controller_Request_Http</classname>
                will
                attempt to automatically detect your base
                <acronym>URL</acronym>
                and set it accordingly.
            </para>

            <para>
                For example, if you keep your
                <filename>index.php</filename>
                in a webserver subdirectory named
                <filename>/projects/myapp/index.php</filename>
                , base
                <acronym>URL</acronym>
                (rewrite base) should be set to
                <filename>/projects/myapp</filename>
                . This string will
                then be stripped from the beginning of the path before
                calculating
                any route matches. This frees one from the necessity
                of prepending it to any of your
                routes. A route of
                <command>'user/:username'</command>
                will match
                <acronym>URI</acronym>
                s like
                <filename>http://localhost/projects/myapp/user/martel</filename>
                and
                <filename>http://example.com/user/martel</filename>
                .
            </para>

            <note>
                <title>URL Detection is Case Sensitive</title>
                <para>
                    Automatic base
                    <acronym>URL</acronym>
                    detection is case
                    sensitive, so make sure your
                    <acronym>URL</acronym>
                    will
                    match a subdirectory name in a filesystem (even on Windows
                    machines). If it
                    doesn't, an exception will be raised.
                </para>
            </note>

            <para>
                Should base
                <acronym>URL</acronym>
                be detected incorrectly
                you can override it with your own base path with the help of
                the
                <methodname>setBaseUrl()</methodname>
                method of either the
                <classname>Zend_Controller_Request_Http</classname>
                class,
                or the
                <classname>Zend_Controller_Front</classname>
                class. The
                easiest method is to set it in
                <classname>Zend_Controller_Front</classname>
                , which will
                proxy it into the request object. Example usage to set a custom
                base
                <acronym>URL</acronym>
                :
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Dispatch Request with custom base URL with Zend_Controller_Front.
 */
$router     = new Zend_Controller_Router_Rewrite();
$controller = Zend_Controller_Front::getInstance();
$controller->setControllerDirectory('./application/controllers')
           ->setRouter($router)
           ->setBaseUrl('/projects/myapp'); // set the base url!
$response   = $controller->dispatch();
]]></programlisting>

        </sect3>

        <sect3 id="zend.controller.request.http.method">
            <title>Determining the Request Method</title>

            <para>
                <methodname>getMethod()</methodname>
                allows you to determine the
                <acronym>HTTP</acronym>
                request method used to request the
                current resource. Additionally, a variety of
                methods exist that
                allow you to get boolean responses when asking if a specific
                type
                of request has been made:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>isGet()</methodname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>isPost()</methodname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>isPut()</methodname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>isDelete()</methodname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>isHead()</methodname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>isOptions()</methodname>
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                The primary use case for these is for creating RESTful
                <acronym>MVC</acronym>
                architectures.
            </para>
        </sect3>

        <sect3 id="zend.controller.request.http.ajax">
            <title>Detecting AJAX Requests</title>

            <para>
                <classname>Zend_Controller_Request_Http</classname>
                has a
                rudimentary method for detecting
                <acronym>AJAX</acronym>
                requests:
                <methodname>isXmlHttpRequest()</methodname>
                . This
                method looks for an
                <acronym>HTTP</acronym>
                request header
                <emphasis>X-Requested-With</emphasis>
                with the value
                'XMLHttpRequest'; if found, it returns
                <constant>TRUE</constant>
                .
            </para>

            <para>Currently, this header is known to be passed by default with
                the following JS
                libraries:</para>

            <itemizedlist>
                <listitem>
                    <para>Prototype/Scriptaculous (and libraries derived from
                        Prototype)</para>
                </listitem>
                <listitem>
                    <para>Yahoo! UI Library</para>
                </listitem>
                <listitem>
                    <para>jQuery</para>
                </listitem>
                <listitem>
                    <para>MochiKit</para>
                </listitem>
            </itemizedlist>

            <para>
                Most
                <acronym>AJAX</acronym>
                libraries allow you to send
                custom
                <acronym>HTTP</acronym>
                request headers; if your library does not send this
                header, simply add it as a
                request header to ensure the
                <methodname>isXmlHttpRequest()</methodname>
                method works for
                you.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.controller.request.subclassing">
        <title>Subclassing the Request Object</title>

        <para>
            The base request class used for all request objects is the
            abstract class
            <classname>Zend_Controller_Request_Abstract</classname>
            . At its
            most basic, it defines the following methods:
        </para>

        <programlisting language="php"><![CDATA[
abstract class Zend_Controller_Request_Abstract
{
    /**
     * @return string
     */
    public function getControllerName();

    /**
     * @param string $value
     * @return self
     */
    public function setControllerName($value);

    /**
     * @return string
     */
    public function getActionName();

    /**
     * @param string $value
     * @return self
     */
    public function setActionName($value);

    /**
     * @return string
     */
    public function getControllerKey();

    /**
     * @param string $key
     * @return self
     */
    public function setControllerKey($key);

    /**
     * @return string
     */
    public function getActionKey();

    /**
     * @param string $key
     * @return self
     */
    public function setActionKey($key);

    /**
     * @param string $key
     * @return mixed
     */
    public function getParam($key);

    /**
     * @param string $key
     * @param mixed $value
     * @return self
     */
    public function setParam($key, $value);

    /**
     * @return array
     */
     public function getParams();

    /**
     * @param array $array
     * @return self
     */
    public function setParams(array $array);

    /**
     * @param boolean $flag
     * @return self
     */
    public function setDispatched($flag = true);

    /**
     * @return boolean
     */
    public function isDispatched();
}
]]></programlisting>

        <para>La solicitud objeto es un contenedor para entorno de la
            solicitud. La cadena del
            controlador sólo necesita saber cómo
            establecer y recuperar el controlador, la acción,
            los parámetros
            opcionales, y el estado del despachador. Por defecto, la solicitud
            buscará
            sus propios parámetros mediante el controlador o las llaves
            de la acción con el fin de
            determinar el controlador y la acción.</para>

        <para>
            Para ampliar esta clase, o uno de sus derivados, cuando se
            necesita la clase solicitud
            que interactue con un entorno específico
            con el fin de recuperar los datos para su uso en
            las tareas antes
            descritas. Los ejemplos incluyen
            <link linkend="zend.controller.request.http">
                el entorno
                <acronym>HTTP</acronym>
            </link>
            , un entorno
            <acronym>CLI</acronym>
            , o un entorno de
            <acronym>PHP</acronym>
            -GTK.
        </para>
    </sect2>
</sect1>