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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 18940 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.router"  xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>El Router Standard</title>
    <sect2 id="zend.controller.router.introduction">
        <title>Introducción</title>
        <para>
            <classname>Zend_Controller_Router_Rewrite</classname> Es el router 
            standard del Framework. Routing es el proceso de tomar la parte 
            final de una <acronym>URI</acronym> (la parte de la <acronym>URI</acronym> que viene después de la <acronym>URL</acronym> 
            base) y la descomposición en parámetros para determinar qué módulo, 
            qué controlador y acción de ese controlador debe recibir la solicitud. 
            Estos valores del módulo, controlador, acción y otros parámetros 
            están enpaquetados en un objeto 
            <classname>Zend_Controller_Request_Http</classname> el cual es 
            procesado luego por <classname>Zend_Controller_Dispatcher_Standard</classname>. 
            El routing ocurre sólo una vez: cuando se recibió inicialmente la 
            solicitud y antes del dispatch del primer controlador.
        </para>

        <para>
            <classname>Zend_Controller_Router_Rewrite</classname> está diseñado 
            para permitir que una funcionalidad tipo mod_rewrite se pueda usar 
            en estructuras <acronym>PHP</acronym> puras. Se basa muy vagamente en el routing de 
            Ruby on Rails (RoR) y no requiere ningún conocimiento previo de 
            reescritura de la <acronym>URL</acronym> del webserver. Está diseñado para trabajar 
            con solo una regla mod_rewrite de Apache (one of):
        </para>

         <programlisting language="php"><![CDATA[
RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php
]]></programlisting>

        <para>
            o (preferido):
        </para>

         <programlisting language="php"><![CDATA[
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
]]></programlisting>

        <para>
            El router rewrite también puede utilizarse con el <acronym>IIS</acronym> webserver (versions &lt;= 7.0) si <ulink
                url="http://www.isapirewrite.com">Isapi_Rewrite</ulink> 
                se ha instalado como una extensión Isapi con la siguiente 
                regla de reescribir:
        </para>

         <programlisting language="php"><![CDATA[
RewriteRule ^[\w/\%]*(?:\.(?!(?:js|ico|gif|jpg|png|css|html)$)[\w\%]*$)? /index.php [I]
]]></programlisting>

        <note>
            <title>IIS Isapi_Rewrite</title>
            <para>
                Cuando se usa <acronym>IIS</acronym>, <varname>$_SERVER['REQUEST_URI']</varname> puede 
                no existir, o establecerlo como un string vacío. En este caso,
                <classname>Zend_Controller_Request_Http</classname> 
                intentará usar el valor de 
                <varname>$_SERVER['HTTP_X_REWRITE_URL']</varname> 
                establecido por la extensión Isapi_Rewrite.
            </para>
        </note>

        <para>
            IIS 7.0 introduce un módulo nativo de reescribir la URL, y puede ser 
            configurado como sigue:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
     <system.webServer>
         <rewrite>
             <rules>
                 <rule name="Imported Rule 1" stopProcessing="true">
                     <match url="^.*$" />
                     <conditions logicalGrouping="MatchAny">
                         <add input="{REQUEST_FILENAME}"
                             matchType="IsFile" pattern=""
                             ignoreCase="false" />
                         <add input="{REQUEST_FILENAME}"
                             matchType="IsDirectory"
                             pattern="" ignoreCase="false" />
                     </conditions>
                     <action type="None" />
                 </rule>
                 <rule name="Imported Rule 2" stopProcessing="true">
                     <match url="^.*$" />
                     <action type="Rewrite" url="index.php" />
                 </rule>
             </rules>
         </rewrite>
     </system.webServer>
</configuration>]></programlisting>

        <para>
            Si está usando Lighttpd, la siguiente regla de reescritura es válida:
        </para>

        <programlisting language="lighttpd"><![CDATA[
url.rewrite-once = (
    ".*\?(.*)$" => "/index.php?$1",
    ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
    "" => "/index.php"
)
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.router.usage">
        <title>Usando un Router</title>

        <para>
            Para utilizar adecuadamente el router de reescritura debe 
            instanciarlo, agregar algunas rutas definidas por el usuario y 
            luego inyectarlo en el controlador. El siguiente código ilustra el 
            procedimiento:
        </para>

         <programlisting language="php"><![CDATA[
// Crear un router

$router = $ctrl->getRouter(); // returns a rewrite router by default
$router->addRoute(
    'user',
    new Zend_Controller_Router_Route('user/:username',
                                     array('controller' => 'user',
                                           'action' => 'info'))
);
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.router.basic">
        <title>Operación Básica del Rewrite Router</title>

        <para>
            El corazón del RewriteRouter es la definición de la rutas definidas 
            por el usuario. Las rutas se agregan llamando al método addRoute 
            de RewriteRouter y pasándole una nueva instancia de una clase que 
            implementó a 
            <classname>Zend_Controller_Router_Route_Interface</classname>. Eg.:
        </para>

         <programlisting language="php"><![CDATA[
$router->addRoute('user',
                  new Zend_Controller_Router_Route('user/:username'));
]]></programlisting>

        <para>
            El Rewrite Router viene con seis tipos básicos de rutas (uno de los 
            cuales es especial):
        </para>

        <itemizedlist mark="opencircle">
            <listitem>
                <para>
                    <link
                        linkend="zend.controller.router.routes.standard">Zend_Controller_Router_Route</link>
                </para>
            </listitem>
            <listitem>
                <para>
                    <link
                        linkend="zend.controller.router.routes.static">Zend_Controller_Router_Route_Static</link>
                </para>
            </listitem>
            <listitem>
                <para>
                    <link
                        linkend="zend.controller.router.routes.regex">Zend_Controller_Router_Route_Regex</link>
                </para>
            </listitem>
            <listitem>
                <para>
                    <link
                        linkend="zend.controller.router.routes.hostname">Zend_Controller_Router_Route_Hostname</link>
                </para>
            </listitem>
            <listitem>
                <para>
                    <link
                        linkend="zend.controller.router.routes.chain">Zend_Controller_Router_Route_Chain</link>
                </para>
            </listitem>
            <listitem>
                <para>
                    <link
                        linkend="zend.controller.router.default-routes">Zend_Controller_Router_Rewrite</link>
                    *
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Las rutas pueden ser utilizadas numerosas veces para crear una cadena 
            o un esquema de aplicación de ruteo definido por el usuario.  
            Puede usar cualquier número de rutas en cualquier configuración, 
            con la excepción de la ruta del Módulo, la cual debe ser utilizada 
            una vez y probablemente como la ruta más genérica (es decir, 
            por defecto). Cada ruta se describe en mayor detalle más adelante.
        </para>

        <para>
            El primer parámetro a addRoute es el nombre de la ruta. 
            Se utiliza como un manejador para sacar las rutas del router 
            (por ejemplo, con fines de generación de <acronym>URL</acronym>). 
            El segundo parámetro es la ruta misma.
        </para>

        <note>
            <para>
                El uso más común del nombre de ruta es por medio del 
                ayudante de <acronym>URL</acronym> <classname>Zend_View</classname>:
            </para>

             <programlisting language="php"><![CDATA[
<a href=
"<?php echo $this->url(array('username' => 'martel'), 'user') ?>">Martel</a>
]]></programlisting>

            <para>
                Que resultaría en la href: <methodname>user/martel</methodname>.
            </para>
        </note>

        <para>
            El routing es un simple proceso de iteración a través de todas las 
            rutas provistas y la equiparación de sus definiciones con la petición 
            actual de <acronym>URI</acronym>. Cuando se encuentra una concordancia, se devuelven 
            valores de variables desde la instancia Route y se inyecta en el 
            objeto <classname>Zend_Controller_Request</classname>  
            para su posterior utilización en el dispatcher así también como en 
            los controladores creados por el usuario. En caso de no encontrar 
            ninguna concordancia, se comprobará la siguiente ruta en la cadena.
        </para>

        <para>
            Si necesita determinar en qué ruta se encontró una concordancia, 
            puede usar el método <methodname>getCurrentRouteName()</methodname>, que devolverá 
            el identificador usado cuando registró la ruta con el router. 
            Si quiere el objeto de la ruta actual, puede usar 
            <methodname>getCurrentRoute()</methodname>.
        </para>

        <note>
            <title>Matching Inverso</title>
            <para>
                Las rutas están equiparadas en orden inverso para asegurarse 
                que las rutas más genéricas se definan primero.
            </para>
        </note>

        <note>
            <title>Valores Retornados</title>
            <para>
                Los valores retornados del routing provienen de parámetros <acronym>URL</acronym> 
                o de rutas definidas por defecto por el usuario. 
                Estas variables son accesibles posteriormente a través de los métodos 
                <methodname>Zend_Controller_Request::getParam()</methodname> o
                <methodname>Zend_Controller_Action::_getParam()</methodname>.
            </para>
        </note>

        <para>
            Hay tres variables que pueden utilizarse en las rutas - 'module', 
            'controller' y 'action'. Estas variables especiales son utilizados por 
            <classname>Zend_Controller_Dispatcher</classname> para encontrar un 
            controlador y una acción para hacer el dispatch.
        </para>

        <note>
            <title>Variables Especiales</title>
            <para>
                Los nombres de estas variables especiales pueden ser diferentes 
                si elige alterar los valores por defecto en
                <classname>Zend_Controller_Request_Http</classname> mediante los 
                métodos 
                <methodname>setControllerKey</methodname> y <methodname>setActionKey</methodname>.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.controller.router.default-routes">
        <title>Routes por Defecto</title>

        <para>
            <classname>Zend_Controller_Router_Rewrite</classname> viene 
            preconfigurado con una ruta por defecto, que se comparará con <acronym>URI</acronym>s 
            en la forma de <methodname>controller/action</methodname>. 
            Además, se puede especificar un nombre de módulo como primer 
            elemento del path, permitiendo <acronym>URI</acronym>s de la forma            
            <filename>module/controller/action</filename>. Por último, también coincidrá  
            con cualquier parámetro adicional agregado a la <acronym>URI</acronym> por defecto -
            <filename>controller/action/var1/value1/var2/value2</filename>.
        </para>

        <para>
            Algunos ejemplos de cómo están equiparadas las rutas:
        </para>

         <programlisting language="php"><![CDATA[
// Asumiendo lo siguiente:
$ctrl->setControllerDirectory(
    array(
        'default' => '/path/to/default/controllers',
        'news'    => '/path/to/news/controllers',
        'blog'    => '/path/to/blog/controllers'
    )
);

Módulo únicamente:
http://example/news
    module == news

Modulo inválido mapea al nombre del controlador:
http://example/foo
    controller == foo

Módulo + controlador:
http://example/blog/archive
    module     == blog
    controller == archive

Módulo + controlador + accción:
http://example/blog/archive/list
    module     == blog
    controller == archive
    action     == list

Módulo + controlador + accción + parámetros:
http://example/blog/archive/list/sort/alpha/date/desc
    module     == blog
    controller == archive
    action     == list
    sort       == alpha
    date       == desc
]]></programlisting>

        <para>
            La ruta por defecto es simplemente un objeto 
            <classname>Zend_Controller_Router_Route_Module</classname> 
            almacenado bajo el nombre de (index) por 'default' en RewriteRouter. 
            Está generado más o menos así:
        </para>

         <programlisting language="php"><![CDATA[
$compat = new Zend_Controller_Router_Route_Module(array(),
                                                  $dispatcher,
                                                  $request);
$this->addRoute('default', $compat);
]]></programlisting>

        <para>
            Si no quiere esta ruta en particular en su esquema por defecto de
            routing, podrá anularla creando su propia ruta por 'defecto'  
            (es decir, almacenar bajo el nombre de 'default') o eliminarla por 
            completo usando <methodname>removeDefaultRoutes()</methodname>:
        </para>

         <programlisting language="php"><![CDATA[
// Eliminar cualquier ruta por defecto
$router->removeDefaultRoutes();
]]></programlisting>

    </sect2>

    <sect2 id="zend.controller.router.rewritebase">
        <title>URL Base y Subdirectorios</title>

        <para>
            El router rewrite puede ser utilizado en subdirectorios (por 
            ejemplo <filename>http://domain.com/~user/application-root/</filename>) 
            en cuyo caso la <acronym>URL</acronym> base de la aplicación 
            (<filename>/user/application-root</filename>) debe ser detectada 
            automáticamente por <classname>Zend_Controller_Request_Http</classname> 
            y usada en consecuencia.
        </para>

        <para>
            Si la <acronym>URL</acronym> base se detecta incorrectamente se la puede anular con su 
            propio path de base usando
            <classname>Zend_Controller_Request_Http</classname> y llamando al 
            método <methodname>setBaseUrl()</methodname> (ver <xref
                linkend="zend.controller.request.http.baseurl" />):
        </para>

         <programlisting language="php"><![CDATA[
$request->setBaseUrl('/~user/application-root/');
]]></programlisting>

    </sect2>

    <sect2 id="zend.controller.router.global.parameters">
        <title>Parámetros Globales</title>

        <para>
            Puede establecer los parámetros globales en un router que se 
            proporcionan automáticamente a una ruta cuando se ensamblasn mediante  
            <methodname>setGlobalParam</methodname>. Si se establece un parámetro global 
            pero también se lo entrega directamente al método de ensamblaje, 
            el parámetro del usuario sobreescribe al parámetro global. 
            Puede establecer un parámetro global esta forma:
        </para>

         <programlisting language="php"><![CDATA[
$router->setGlobalParam('lang', 'en');
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.router.routes">
        <title>Tipos de Route</title>
        <xi:include href="Zend_Controller-Router-Route.xml" />
        <xi:include href="Zend_Controller-Router-Route-Static.xml" />
        <xi:include href="Zend_Controller-Router-Route-Regex.xml" />
        <xi:include href="Zend_Controller-Router-Route-Hostname.xml" />
        <xi:include href="Zend_Controller-Router-Route-Chain.xml" />
    </sect2>

    <sect2 id="zend.controller.router.add-config">
        <title>Usando <classname>Zend_Config</classname> con RewriteRouter</title>

        <para>
            A veces es más conveniente para actualizar un archivo de 
            configuración con nuevas rutas que modificar el código. 
            Esto es posible a través del método <methodname>addConfig()</methodname>.
            Básicamente, se crea una configuración compatible con 
            <classname>Zend_Config</classname>. 
            Y en su código lo lee y lo pasa a RewriteRouter.
        </para>

        <para>
            Como ejemplo, considere el siguiente archivo  <acronym>INI</acronym>:
        </para>

         <programlisting language="php"><![CDATA[
[production]
routes.archive.route = "archive/:year/*"
routes.archive.defaults.controller = archive
routes.archive.defaults.action = show
routes.archive.defaults.year = 2000
routes.archive.reqs.year = "\d+"

routes.news.type = "Zend_Controller_Router_Route_Static"
routes.news.route = "news"
routes.news.defaults.controller = "news"
routes.news.defaults.action = "list"

routes.archive.type = "Zend_Controller_Router_Route_Regex"
routes.archive.route = "archive/(\d+)"
routes.archive.defaults.controller = "archive"
routes.archive.defaults.action = "show"
routes.archive.map.1 = "year"
; O: routes.archive.map.year = 1
]]></programlisting>

        <para>
            Entonces el archivo <acronym>INI</acronym> puede ser leído por un objeto
            <classname>Zend_Config</classname> como sigue:
        </para>

         <programlisting language="php"><![CDATA[
$config = new Zend_Config_Ini('/path/to/config.ini', 'production');
$router = new Zend_Controller_Router_Rewrite();
$router->addConfig($config, 'routes');
]]></programlisting>

        <para>
            En el ejemplo de arriba, le decimos el router que utilice la 
            sección 'routes' del archivo <acronym>INI</acronym> para utilizarlo en sus rutas. 
            Cada clave de primer nivel en esa sección será utilizada para definir 
            un nombre de ruta; el ejemplo anterior define las rutas 'archive' y 
            'news'. Entonces cada ruta requiere, como mínimo, una entrada a la 
            'ruta' y una o más entradas por 'default'; opcionalmente puede 
            proporcionarse una o más 'reqs' (abreviación de 'required'). 
            Dicho todo esto, estos corresponden a los tres argumentos que se le 
            suministran al objeto 
            <classname>Zend_Controller_Router_Route_Interface</classname>. 
            Puede utilizarse una clave opcional 'type' para especificar el 
            tipo de clase de ruta a utilizar en esa ruta en particular; 
            por defecto, usa 
            <classname>Zend_Controller_Router_Route</classname>. 
            En el ejemplo de arriba, la ruta 'news' está definida para usar 
            <classname>Zend_Controller_Router_Route_Static</classname>.
        </para>
    </sect2>

    <sect2 id="zend.controller.router.subclassing">
        <title>Subclassing del Router</title>

        <para>
            El standard rewrite router debería proporcionarle más funcionalidad 
            si la necesita; más a menudo, sólo necesitará crear un nuevo 
            tipo de ruta a fin de ofrecer funcionalidades nuevas o modificadas  
            sobre las tutas provistas.
        </para>

        <para>
            Dicho esto, en algún momento puede encontrarse a si mismo deseando 
            usar un paradigma diferente de routing. La intefaz  
            <classname>Zend_Controller_Router_Interface</classname> proporciona 
            la información mínima necesaria para crear un router, y consiste en 
            un único método.
        </para>

         <programlisting language="php"><![CDATA[
interface Zend_Controller_Router_Interface
{
  /**
   * @param  Zend_Controller_Request_Abstract $request
   * @throws Zend_Controller_Router_Exception
   * @return Zend_Controller_Request_Abstract
   */
  public function route(Zend_Controller_Request_Abstract $request);
}
]]></programlisting>

        <para>
            El routing sólo ocurre una vez: cuando la petición es recibida por 
            primera vez en el sistema. El propósito del router es determinar el 
            controlador, la acción, y los parámetros opcionales sobre la base 
            del medio ambiente de la solicitud, y luego ajustarlos en la solicitud. 
            El objeto solicitud se pasa entonces al dispatcher. 
            Si no es posible trazar una ruta hacia un dispatch token, 
            el router no debe hacer nada con el objeto solicitud.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->