Lo básico sobre rutas 

Dentro de una aplicación de PHP, como XF2, necesitamos una forma de poder hacer una solicitud de usuario para una URL específica, entendiendo qué controlador, qué acción y qué datos representan a esa URL, para que pueda presentar una adecuada respuesta al usuario. El concepto de convertir una URL a una ubicación desde el código se conoce como "Enrutamiento".

En XF2, el enrutamiento se administra casi en su totalidad desde una ubicación dentro del panel de control de administración. Ese lugar es PCAdmin > Desarrollo > Rutas. Las rutas se agrupan de una de dos formas, Pública y Admin, y proveen el enrutamiento de solicitudes dentro de aplicaciones Públicas y Admin, respectivamente.

Un simple ejemplo

En la página de rutas (véase más arriba) debería aparecer una entrada para account/. Esta es una ruta pública y provee el enrutamiento de las solicitudes a la URL index.php?account/. Esta particular ruta es muy simple; sólo consiste en una pequeña cantidad de configuración. Notablemente, está formado por un "Prefijo de ruta", un contexto de sección y una clase controlador. Vamos a conocer esto con más detalle:

Prefijos de ruta

El prefijo de ruta está, esencialmente, un poco después de index.php? y antes de la primera /. Es el primer paso en la identificación de a qué controlador hace la solicitud la ruta.

Sección del contexto

La sección del contexto llama a los sistemas de navegación de XF y nos dice qué elemento de navegación debe seleccionarse cuando un visitante está viendo una página enrutada por esta ruta. Para rutas públicas, la sección del contexto debe ser el ID del más alto nivel de navegación. Para rutas Admin, debe referirse al ID de una entrada de navegación Admin más específica (Independientemente de la profundidad).

En el caso de la ruta account, la sección del contexto no se aplica necesariamente por defecto, porque no tenemos una pestaña de navegación "account". Pero, para ver esto en acción, sólo cambiaremos el valor "Sección del contexto" de aquí por "foros", guardamos los cambios y vamos a tu cuenta en la vista pública. Se verá ahora que la pestaña de navegación "Foros" ¡está seleccionada!

Controlador

Este es el nombre de la clase del Controlador al que se llama cuando una solicitud coincide con la ruta. En el caso de la ruta "account/", está especificada XF:Account. Esto cargará al controlador Account. (Véase Nombres cortos de clase para una mayor información). El código de esto se localiza en la siguiente ubicación src/XF/Pub/Controller/Account.php. Advertir el cómo los nombres cortos de clase son capaces de resolver desde un "infijo" así como un prefijo (XF) y un sufijo (Account). En este caso, el infijo para este controlador (Pub) se deduce del tipo de ruta Account (pública).

Acciones del controlador

Arriba se ha explicado cómo se compara la coincidencia de una ruta con un controlador específico, pero aún no conocemos cómo se llama a una acción específica en el controlador. Los controladores son esencialmente clases que contienen un número de métodos de acción y supone la parte de una URL detrás de los prefijos de ruta que indican la acción del controlador. Dada una URL como index.php?account/account-details, debe enrutarse a la clase XF\Pub\Controller\Account y al método denominado actionAccountDetails(). Si una ruta no tiene especificada una acción, el método llamado será actionIndex().

Puede leerse más sobre controladores en la sección Básicos sobre controladores.

Un más avanzado ejemplo (formatos de ruta)

Echemos un vistazo a la ruta members/. Esta ruta sigue siendo bastante simple, como la ruta account/, pero con un campo adicional cumplimentado; el "Formato de ruta". Para entender cómo trabaja esto, mira en tu propio perfil de usuario en la vista pública. Su URL luce algo como esto index.php?members/lms.1. Específicamente, toma nota de la parte lms.1. Esta es la parte para la que se busca una coincidencia usando el "Formato de ruta".

El "Formato de ruta" nos permite obtener datos desde una solicitud URL, para que se pueda pasar esa información a la acción del controlador y que la acción pueda cargar la información específica; en este caso se cargan los detalles para el perfil de usuario solicitado. Esto nos ayuda también a generar vínculos desde los datos que se pasan. Ésta es la sintaxis:

:int<user_id,username>/:page 
                

Es interesante advertir en este punto que la parte importante de una URL del perfil para encontrar ese perfil no es actualmente el trozo lms, si no que actualmente lo es el ID de usuario (1). Para demostrar esto, cambia la URL y reemplaza lms por no-es-lms. Se verá que se encuentra el perfil correcto y se realiza una redirección a la URL correcta.

El formato indicado arriba es un parámetro basado en un entero. Para construir el vínculo de salida, se extrae el entero de la clave user_id de los datos que pasan. Si se pasa una clave de nombre de usuario con los datos, será como un "balazo" y precedido al número entero del ID tal y como se ve en la URL del perfil. Para hacer coincidir URL entrante, esto se convierte dentro de una expresión regular que busca la coincidencia con el formato de parámetro entero.

:page es un atajo para generar la parte page-123 de un víncilo. En este caso, los parámetros del vínculo lucen para la página. Si se hallan, los coloca en la URL y se eliminan de los parámetros. Por el análisis de lo entrante, si hay coincidencia (puede estar vacía), agregará el número de página a los parámetros que se pasan aun controlador.

Parámetros de ruta 

Echemos un vistazo a la ruta members/. Esta ruta sigue siendo bastante simple, como la ruta account/, pero con un campo adicional cumplimentado; el "Formato de ruta". Para entender cómo trabaja esto, mira en tu propio perfil de usuario en la vista pública. Su URL luce algo como esto index.php?members/lms.1. Específicamente, toma nota de la parte lms.1. Esta es la parte para la que se busca una coincidencia usando el "Formato de ruta".

El "Formato de ruta" nos permite obtener datos desde una solicitud URL, para que se pueda pasar esa información a la acción del controlador y que la acción pueda cargar la información específica; en este caso se cargan los detalles para el perfil de usuario solicitado. Esto nos ayuda también a generar vínculos desde los datos que se pasan. Ésta es la sintaxis:

:int<user_id,username>/:page 
                

Cuando una ruta coincide con un controlador y acción específicos, cualquier parámetro de la URL queda envuelto en objeto especial que denominamos ParameterBag. Este objeto está específicamente diseñado para separar los parámetros normales de una URL con los que vienen de la ruta de coincidencia. El objeto ParameterBag se transmite a cada acción del controlador y se usa como sigue:

$userId = $params->user_id;

                

Sub-nombres

También es posible dividir las rutas en partes para promover los sub-nombres. Puede verse esto en acción mirando en la ruta members/following. En este ejemplo, following es el sub-nombre de la ruta members. Ordinariamente, una URL que luce como index.php?members/following, la parte following indicaría la acción y simplemente coinciden con la ruta members/ normal. Sin embargo, si existe una ruta que coincida con el prefijo "members" y el "sub-nombre" following, ésta se usará en su lugar. Esto es verdad aquí, por lo que se construye un vínculo como el siguiente:

members/:int/following/:page 
                

Para cada ruta entrante coincidente se comprobará la misma antes que la ruta básica members; si existe coincidencia se usará.

Este sistema de sub-nombres permite cambios de comportamiento, como el cambio de posición de parámetros o sub-agrupamiento de rutas en diferentes controladores o con diferentes parámetros. Puede verse un ejemplo de esto último en los complementos Gestor de recursos y Galería multi-media.