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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15103 -->
<!-- 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 HTTP, el CLI, o PHP-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 URI de la solicitud, ruta de la 
            información, parámetros <methodname>$_GET</methodname> y <methodname>$_POST</methodname>,
            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, URI, 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
                MVC.
        </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 URI. Adiccionalmente permite el acceso
                a valores contenidos en las superglobales como miembros públicos y 
                administra la actual base URL y la solicitud URI. los valores
                Superglobales no pueden ser determinados en una solicitud objeto, en vez usar los
                métodos setParam/getParam 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. GET, 2.
                    POST, 3. COOKIE, 4. SERVER, 5. ENV.
                </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
                <methodname>$_POST['user']</methodname> puede ser accedido llamando a 
                <methodname>getPost('user')</methodname> en la solicitud objeto. Esto 
                incluye <methodname>getQuery()</methodname> para recuperar elementos
                <methodname>$_GET</methodname>, 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 MVC 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 URI 
                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 <methodname>GET</methodname>, y finalmente parámetros <methodname>POST</methodname>. 
                    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, <methodname>$_SERVER['REDIRECT_URL']</methodname>
                    contains the URI you need, not
                    <methodname>$_SERVER['REQUEST_URI']</methodname>. 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 Http 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 URL and set it accordingly.
            </para>

            <para>
                For example, if you keep your <methodname>index.php</methodname> in a
                webserver subdirectory named
                <methodname>/projects/myapp/index.php</methodname>, base URL (rewrite base)
                should be set to <methodname>/projects/myapp</methodname>. 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
                <methodname>'user/:username'</methodname> will match URIs like
                <methodname>http://localhost/projects/myapp/user/martel</methodname> and
                <methodname>http://example.com/user/martel</methodname>.
            </para>

            <note>
                <title>URL Detection is Case Sensitive</title>
                <para>
                    Automatic base URL detection is case sensitive, so make sure your URL
                    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 URL 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 URL:
            </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 HTTP
                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 MVC
                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 AJAX requests:
                <methodname>isXmlHttpRequest()</methodname>. This method looks for an
                HTTP request header <methodname>X-Requested-With</methodname> with the value
                'XMLHttpRequest'; if found, it returns true.
            </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 AJAX libraries allow you to send custom HTTP 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 HTTP
                                </link>, un entorno CLI, o un entorno de PHP-GTK.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->