5.10. Generar URLs a Partir de Rutas

La principal tarea de cualquier clase route es determinar si la ruta definida coincide con la petición HTTP, si hay coincidencia regresa el conjunto de parámetros con los que se puede determina un controlador y una acción. La tarea opuesta de una clase route permite generar URLs con parámetros. Esta característica se puede usar en un método de acción en el controlador para generar URLs, por ejemplo, para redireccionar a un usuario a otra página. Además, esta se puede usar dentro de la plantilla de vista para generar enlaces.

5.10.1. Generar URL en la plantilla de Vista

Las páginas web usualmente contienen enlaces a otras páginas. Estos enlaces puede apuntar tanto a una página interna de nuestro sitio como a páginas de otros sitios. Un enlace se representa con la etiqueta HTML <a> que tiene el atributo href que especifica la URL de la página de destino. Abajo se muestra un ejemplo de un enlace apuntando a una página externa:

<a href="http://example.com/path/to/page">A link to another site page</a>

Cuando generamos un enlace a un recurso interno de nuestro sitio generalmente usamos una URL relativa (sin el nombre del servidor):

<a href="/path/to/internal/page">A link to internal page</a>

Para generar URLs en nuestra plantilla de vista (archivos .phtml) podemos usar la clase ayudante de vista Url que toma el nombre de ruta como un argumento de entrada:

<!-- A hyperlink to Home page -->
<a href="<?= $this->url('home'); ?>">Home page</a>

<!-- A hyperlink to About page -->
<a href="<?= $this->url('about'); ?>">About page</a>

En las líneas de arriba generamos dos URLs relativas. En la línea 2 llamamos al ayudante de vista Url y le pasamos el nombre de ruta "home" como su parámetro. En la línea 5 pasamos el nombre de la ruta "about" como un argumento al ayudante de vista Url.

En el ejemplo de arriba el ayudante de vista Url usa internamente el objeto RouteMatch y llama a la ruta Literal para ensamblar la URL a partir del nombre de la ruta.

Luego de que la clase PhpRenderer ejecuta el código de la plantilla de vista la salida HTML será la siguiente:

<!-- A hyperlink to Home page -->
<a href="/">Home page</a>

<!-- A hyperlink to About page -->
<a href="/about">About page</a>

5.10.1.1. Pasar Parámetros

Si una ruta usa algunos parámetros variables podemos pasarlos al ayudante de vista Url como un segundo argumento:

<!-- A hyperlink to About page -->
<a href="<?= $this->url('application', ['action' => 'about']); ?>" >
  About page
</a>

<!-- A hyperlink to Barcode image -->
<a href="<?= $this->url('application', ['action' => 'barcode',
  'type' => 'code39', 'text' => 'HELLO-WORLD']); ?>" >
  Barcode image </a>

En el ejemplo de arriba usamos el ayudate de vista Url para generar dos URLs a partir de su nombre y parámetros. Pasamos el nombre de ruta "application" como el primer argumento y un arreglo de parámetros como segundo argumento.

En la línea 2 pasamos el parámetro acción para decirle a la clase route Segment que esta debe sustituir el comodín correspondiente en la cadena de ruta con la cadena "about".

Después que la clase PhpRenderer ejecuta el código de la plantilla de vista la salida HTML será como la siguiente:

<!-- A hyperlink to About page -->
<a href="/application/about" > About page </a>

<!-- A hyperlink to Barcode image -->
<a href="/application/barcode/code39/HELLO-WORLD" > Barcode image </a>

Como otro ejemplo vamos a intentar generar una URL para nuestra ruta Regex (una que sirve nuestras páginas "estáticas"):

<!-- A hyperlink to Introduction page -->
<a href="<?= $this->url('doc', ['page'=>'introduction']); ?>">
 Introduction </a>

Esto genera el siguiente código HTML:

<!-- A hyperlink to Introduction page -->
<a href="/doc/introduction.html"> Introduction </a>

5.10.1.2. Generar URLs Absolutas

Si necesitamos generar URL absolutas (que tienen un esquema y un nombre de servidor) podemos especificar el tercer parámetro del ayudante de vista Url. El tercer parámetro debería ser un arreglo que contiene una o varias opciones. Para construir una URL absoluta pasamos la opción force_canonical como se muestra abajo:

<!-- A hyperlink to Home page -->
<a href="<?= $this->url('home', [], ['force_canonical' => true]); ?>" >
  Home page </a>

<!-- A hyperlink to About page -->
<a href="<?php echo $this->url('application', ['action' => 'about'],
  ['force_canonical' => true]); ?>" > About page </a>

En la línea 2 del ejemplo de arriba pasamos el nombre de la ruta "home" como primer argumento, un arreglo vacío como segundo argumento y un arreglo que contiene la opción force_canonical como el tercer argumento. Además, en las líneas 6-7 pasamos la opción force_canonical como tercer argumento para generar la URL de la página About.

El resultado HTML del código de arriba se mostrará de la siguiente manera:

<!-- A hyperlink to Home page -->
<a href="http://localhost/" > Home page </a>

<!-- A hyperlink to About page -->
<a href="http://localhost/application/index/about" > About page </a>

5.10.1.3. Especificar la Query Part

Si queremos que nuestra URL tenga una query part podemos especificar la opción query como tercer argumento en el ayudante de vista Url. Por ejemplo, suponiendo que tenemos la acción "search" en algún controlador (y una ruta asociada a esta acción) y queremos pasar un parámetro de consulta y contar los resultados por página. La URL para esta acción sería como esta: "http://localhost/search?q=topic&count=10". Para generar una URL como esta podemos usar el siguiente código:

<a href="<?= $this->url('search', [], ['force_canonical' => true,
         'query'=>['q'=>'topic', 'count'=>10]]); ?>" >
  Search </a>

En el código de arriba especificamos la opción query que es un arreglo que contiene el par name=>value como parámetros de consulta.

5.10.2. Generar las URL en el Controlador

Podemos generar URLs dentro de nuestro método de acción en el controlador usado el controlador complementario Url. Para generar una URL llamamos al método fromRoute() del controlador complementario Url como en el ejemplo de abajo:

// An example action method
public function someAction()
{
    // Generate a URL pointing to the Home page ('/')
    $url1 = $this->url()->fromRoute('home');

    // Generate an absolute URL pointing to the About page
    // ('http://localhost/application/about')
    $url2 = $this->url()->fromRoute('application',
              ['action'=>'about'], ['force_canonical'=>true]);
}

Los argumentos que toma el complemento Url son los mismos que los del ayudante de vista Url. Así, podemos generar URLs absolutas y relativas de la misma manera que lo hacemos en nuestras plantillas de vista.

5.10.3. Codificación de la URL

Cuando se generan URLs tanto con el ayudante de vista Url o con el controlador complementaria Url deberíamos recordar que las URLs solo pueden contener caracteres "seguros", caracteres del conjunto de caracteres ASCII. Si pasamos un parámetro que contiene caracteres inseguros estos caracteres se reemplazarán con una secuencia constituida por el carácter porcentaje y dos dígitos.

Por ejemplo, vamos a intentar generar una URL para nuestra ruta Regex y pasarla con el parámetro "page" que tendrá el valor "/chapter1/introduction".

<!-- A hyperlink to Introduction page -->
<a href="<?= $this->url('doc', ['page'=>'chapter1/introduction']); ?>">
  Introduction </a>

Podemos asumir que se generará una URL como "/doc/chapter1/introduction.html". Pero como la barra ('/') es un carácter inseguro será reemplazado por seguridad por los caracteres "%2F" con lo que se obtiene un código HTML como el siguiente:

<!-- A hyperlink to Introduction page -->
<a href="/doc/chapter1%2Fintroduction.html"> Introduction </a>

Desafortunadamente este enlace no es útil por que no coincidirá con nuestra ruta Regex.