Tengo la convicción de que se aprende más de ¿cómo se pensó para resolver un problema? que de la solución en sí. De modo que voy a comenzar por mostrar el enfoque:
El problema se dividió en tres partes:
- Crear un mecanismo sencillo para definir "rutas eslash" funcionales (me gusta bautizar lo que estoy haciendo para facilitar el pensamiento al respecto)
Llamo ruta eslash a cualquier ruta que deba funcionar igual con o sin separador de directorios final ej: misitio/ayudas y misitio/ayudas/ deben operar igual.
- Crear un mecanismo para registrar rutas case-insensitivas de modo que todas las escrituras posibles de una ruta sean atendidas por un mismo controlador. Esto es muy importante porque rutas que no producen error en Mac o bajo Win_x producen error 404 o página en blanco en la familia Unix - linux.
Llamo ruta case-insensitiva (en espanglish) a una ruta con nombre independiente de mayúsculas y minúsculas.
- Crear un mecanismo para que las rutas que contengan colas a partir del último separador de directorio bajo una ruta registrada y funcional sean interpretadas como rutas con una colas de parámetros y sean atendidas sin error por el procesador y la acción registrados para ellas.
Finalmente, se debe recoger las soluciones a los puntos anteriores en una clase que permita tenerlos disponibles para definir y registrar enrutadores para aplicaciones y módulos de extensión basados en zend. Y, para verificar la solución: Iniciar la escritura de dos módulos de extensión usándola para registrar su sistema de enrutamiento.
Como no debía usarla sin pruebas en mi proyecto pensé en dos cosas que necesitara, para iniciarlas si dañar trabajo adelantado: un administrador de ayudas para documentar al vuelo proyectos en desarrollo. Y el otro para usar Twitter-Bootstrap 3x en cualquier proyecto con o sin escritura de código adicional. Estos módulos no van a ser mostrados acá (actualmente son increíblemnte grandes y no son pertinentes). Sólo mostraré el código usado para declarar y registrar sus enrutadores usando la solución.
Modelo básico de declaración de rutas en Zendframework 3x
Las rutas se suelen declarar en el archivo module/Nombre_del_Modulo/config/module.config.php
bajo la clave 'router'
Aunque, a mi me gusta definirlas en un archivo aparte para facilitar su revisión y mantenimiento así en el módulo config reemplazo los subarrays de definición de preferencias por enlaces a los archivos que las contienen:
<?php
/**
* Filename: /module/Helpedit2l/config/module.config.php
* Devuelve las opciones de configuración requeridas por el módulo Helpedit2l
*
* @author: Yo
*/
return [
'controllers' => [
'factories' => include __DIR__ . '/ControllerFactories.php'
],
'router' => [
'routes' => include __DIR__ . '/DefineRoutes.php',
],
'view_manager' => ['template_path_stack' => [__DIR__ . '/../view',],],
];
y en el archivo de declaración de rutas:
<?php
/**
* Filename: /module/Helpedit2l/config/DefineRoutes.php
*
* Registra las rutas empleadas para invocar la documentación de los objetos
* ofrecidos por Helpedit2l
*
* @author: Yo
*/
namespace Helpedit2l;
use Zend\Router\Http\Segment;
use Biblio2ls\Library\Router2ls; // La clase que ofrece la solución
$page_constraint = Router2ls::PaginateConstraints(); //ignorar; no aporta
// pero no lo puedo quitar sin volver inconsistente el código
return [
// Listado general de ayudas
'h2layudas' => [
'type' => Segment::class,
'options' => [
'route' => '/:ayudas[/p:pagina][/:letra[/p:alfapagina]]',
'constraints' => array_merge(
[ 'ayudas' => Router2ls::freeCaseExt('ayudas') ],
$page_constraint ),
'defaults' => [
'controller' => Controller\AyudasController::class,
'action' => 'index'
]
],
'may_terminate' => true,
'child_routes' => [
'h2layudasslash' => Router2ls::SlashUri(Controller\AyudasController::class, 'index'),
]
],
// ... siguen otras declaraciones que no son útiles para
// ilustrar la solución
];
Como se puede ver se declara use Zend\Router\Http\Segment;
para hacer uso del tipo de ruta segment que facilita declarar urls discretas (por secciones entre separadores de directorios con rutas anidadas). Y, se declara la clase abstracta que va a ofrecer los métodos que facilitan declarar rutas con las condiciones deseadas.
Cada ruta se declara como un array de la forma:
NombreDeMaquinaDeLaRuta => settings, Dónde settings es a su vez un array en el que se destacan varias claves importantes:
- 'type' Presenta el tipo de ruta que se quiere definir.
- 'options' Es un array en el que se declaran ruta, restricciones de formato de la misma y en un subarray el controlador y la acción.
- 'route' una cadena de texto con la ruta explícita o una cadena con lugares de reemplazo que serán especificados en
'constraints'
- 'constraints' una guía de formato admitido en los lugares de reemplazo
- 'defaults' un array que presenta el controlador y la acción (procedimiento) que prepararán la respuesta para servir la vista asociada a la ruta.
- 'child_routes' un array de arrays con las mismas características que define las rutas hijas (cada segmento que va a ser reconocido como ruta)
Veamos ahora el mecanismo de definición de la ruta asignando:
'route' => '/:ayudas[/p:pagina][/:letra[/p:alfapagina]]'
// este es un formato para ofrecer listas muy grandes con paginación
// alfabética y numerada simultáneas.
La ruta debe comenzar por /
y debe contener la cadena de reemplazo, que se especifique mediante una expresión regular en constraints para :ayudas
. Puede o no estar seguida por /p
y el valor que determine la expresión regular que se asigne a :pagina
o por el grupo opcional similar /
seguido de :letra
y opcionalmente seguido de /p
y :alfapagina
.
Como se puede ver en el código (arriba) las expresiones regulares para las posiciones de reemplazo se establecen en la clase Router2ls
Declaración de una ruta case-insensitiva
'constraints' => array_merge(
[ 'ayudas' => Router2ls::freeCaseExt('ayudas') ], //nueva sintaxis de definición de arrays
$page_constraint ),
La asignación 'ayudas' => Router2ls::freeCaseExt('ayudas')
invoca un método que genera una expresión regular para que sean admitidas todas las posibles escrituras de la palabra ayuda, de modo que /ayuda, /aYuDA, etc., sean interpretadas como la misma ruta. Y $page_constraint
es un array de uso común, que define de modo estandarizado las expresiones regulares para rutas que necesiten contar con paginación automática. ej /Ayudas/E/p45 pide la página 45 de las ayudas con título que inicia por E, mientras que /Ayudas/p45 pide la página 45 del listado general de ayudas.
$page_constraint = Router2ls::PaginateConstraints();
Nótese que Router2ls::PaginateConstraints();
invoca un método estático de una clase abstracta; al igual que Router2ls::freeCaseExt('ayudas')
.
No voy a mostrar toda la clase. Sólo los métodos que resuelven la pregunta anotada:
<?php
/**
* @Filename: /module/Biblio2ls/src/Library/Router2ls.php
* Ofrece un juego de funciones "tipográficas" dispuestas para simplificar
* la declaración de rutas válidas para zend en los archivos de configuración
* de módulos.
*
* @author Luis Guillermo Quevedo
*/
namespace Biblio2ls\Library;
/**
* Biblioteca de funciones tipográficas para definición de rutas
*/
abstract class Router2ls {
const NORMAL_WORD_CONSTRAINT = '[a-zA-Z0-9\(][a-zA-Z0-9_\.\(\)-]*';
/**
* Devuelve un array de expresiones regulares para las acciones
* típicas de edición asociadas a la vista de un contenido, de modo
* que se puedan establecer como extensión de la ruta que lo muestra
*/
public static function editActionsConstraint($add='add', $edit='edit', $del='delete'){
$v1 = ($add) ? $add : 'add';
$v2 = ($edit) ? $edit : 'edit';
$v3 = ($del) ? $del : 'delete';
return self::freeCaseExt($v1).'|'.self::freeCaseExt($v2).'|'.self::freeCaseExt($v3);
}
/**
* Devuelve una expresión regular para la palabra recibida como
* parámetro de entrada de modo que se admitan todas sus posibles
* escrituras
* @param string $toCase palabra a convertir
* @return string regexp
*/
public static function freeCaseExt($toCase){
$len = strlen($toCase);
$salida = '';
if($len < 1){ return $salida; }
for ($i=0; $i<$len; $i++){
$s = strtolower(substr($toCase, $i, 1));
$salida .= '['.$s.strtoupper($s).']';
}
return $salida;
}
/**
* Igual que la anterior pero actuando sobre un array de palabras
* válidas y las devuelve separadas por el operador or |
*/
public static function freeCaseArrayWords($array){
$variants = [];
foreach($array as $word){
$variants[] = self::freeCaseExt($word);
}
return implode('|', $variants);
}
/**
* Crea un array de definiciones de rutas para establecer nueve
* niveles de profundidad bajo cualquier ruta que se esté definiendo
* de modo que la ruta admita hasta nueve parámetros opcionales
* separados por DIRECTORY_SEPARATOR sin generar errores de página
* o controlador o vista no encontrados
*/
public static function multiLevelRouteDef($base, $controllerClass, $actionName, $ruteprefix){
$basevariants = (is_array($base)) ? self::freeCaseArrayWords($base) : self::freeCaseExt($base);
$routedef = [
'type' => \Zend\Router\Http\Segment::class,
'options' => [
'route' => '/:caso[/:casoa][/:casob][/:casoc][/:casod][/:casoe][/:casof][/:casog][/:casoh][/:casoi]',
'constraints' => [
'caso' => $basevariants,
'casoa' => self::NORMAL_WORD_CONSTRAINT,
'casob' => self::NORMAL_WORD_CONSTRAINT,
'casoc' => self::NORMAL_WORD_CONSTRAINT,
'casod' => self::NORMAL_WORD_CONSTRAINT,
'casoe' => self::NORMAL_WORD_CONSTRAINT,
'casof' => self::NORMAL_WORD_CONSTRAINT,
'casog' => self::NORMAL_WORD_CONSTRAINT,
'casoh' => self::NORMAL_WORD_CONSTRAINT,
'casoi' => self::NORMAL_WORD_CONSTRAINT,
],
'defaults' => [ 'controller' => $controllerClass, 'action' => $actionName ]
],
'may_terminate' => TRUE,
'child_routes' => [ $ruteprefix.'slash' => \Biblio2ls\Library\Router2ls::SlashUri($controllerClass, $actionName),]
];
return $routedef;
}
/**
* Devuelve un array de expresiones regulares para establecer filtros de
* paginación para rutas a listados paginables alfabéticamente.
* @return array
*/
public static function PaginateConstraints(){
return [
'pagina' => '[1-9][0-9]*',
'letra' => '[a-zA-Z\*]',
'alfapagina' => '[1-9][0-9]*',
];
}
/**
* Devuelve el array de definición para crear una ruta children '/' bajo una
* ruta particular. Se debe pasar el alias que identifica al controller en config
* y la accion de modo que sea calcado el llamado.
* @param string $controller
* @param string $action
* @return array
*/
public static function SlashUri($controller, $action){
return ['type' => \Zend\Router\Http\Literal::class, 'options' => ['route' => '/', 'defaults' => ['controller' => $controller, 'action' => $action ]]];
}
// Siguen otros métodos que no son pertinentes aquí
}
Definición de una ruta multinivel
Como se puede observar la clase Router2ls
tiene un método preparado para colgar rutas multinivel (con 10 niveles de profundidad) al configurar cualquier módulo. Ilustraré como usarla bajo la ruta /ayudas
para que sean admitidas todas las cadenas de la forma
/ayudas/objeto[/:param1][/:...][/:param9]
Esto es /ayudas/objeto con cualquier escritura y hasta nueve parámetros opcionales:
<?php
// en el subarray child_routes se agrega un hijo adicional:
'child_routes' => [
'h2layudasslash' => Router2ls::SlashUri(Controller\AyudasController::class, 'index'),
'ayudaobjetos' => Router2ls::multiLevelRouteDef(
'objeto',
Controller\AyudasController::class, 'objetos',
'ayudaobjetos'
),
Obviamente, en la carpeta src/Controller del módulo debe existir una clase AyudasController
que exitende la clase Zend\Mvc\Controller\AbstractActionController
y contiene al menos dos métodos públicos indexAction() y objetosAction() y sus vistas asociadas.
Espero sea de utilidad.