5.7. Type de route Regex

Le type de routé à expression régulière (Regex) est utile si vous avez des URL qui peuvent être mises en correspondance avec une expression régulière.

Supposons par exemple que vous souhaitiez créer un système de documentation simple pour votre site Web. La documentation consisterait en des pages "statiques" mappées à des URL comme /doc/<page_name>.html.

Par le terme "page statique" nous nous référons à une page qui contient principalement du code HTML statique ainsi que plusieurs fragments PHP. Pour de telles pages, vous n'avez pas besoin de créer des actions de contrôleur séparées. Toutes les pages "statiques" peuvent être desservies par l'action d'un contrôleur unique.

Implémentons la route qui servira les pages "statiques" du site. Les pages "statiques" étant simples, vous n'aurez généralement pas besoin d'ajouter une méthode d'action par page. Toutes les pages seront traitées par l'action unique IndexController::docAction().

Tout d'abord, nous ajoutons la route Regex nommée "doc" au fichier module.config.php :

'doc' => [
    'type' => Regex::class,
    'options' => [
        'regex'    => '/doc(?<page>\/[a-zA-Z0-9_\-]+)\.html',
        'defaults' => [
            'controller' => Controller\IndexController::class,
            'action'     => 'doc',
        ],
        'spec'=>'/doc/%page%.html'
    ],
],

La ligne 2 définit le type Regex pour la route. A la ligne 4, nous avons l'expression régulière /doc(?<page>\/[a-zA-Z0-9_\-]+)\.html. Qui va correspondre à des URL comme "/doc/contents.html" ou "/docs/introduction.html". L'expression contient le nom de la "page" capturée⁶ qui sera retournée par le routeur avec les paramètres par défaut.

La ligne 9 contient l'option spec qui est utilisée pour générer des URL par route (nous discuterons de la génération d'URL par route plus loin dans ce chapitre).

N'oubliez pas d'ajouter la ligne suivante au début du fichier module.config.php :

use Zend\Router\Http\Regex;

Ensuite, ajoutez l'action suivante à la classe IndexController :

public function docAction() 
{
    $pageTemplate = 'application/index/doc'.
        $this->params()->fromRoute('page', 'documentation.phtml');        
  
    $filePath = __DIR__.'/../../view/'.$pageTemplate.'.phtml';
    if(!file_exists($filePath) || !is_readable($filePath)) {
        $this->getResponse()->setStatusCode(404);
        return;
    }
	
    $viewModel = new ViewModel([
            'page'=>$pageTemplate
        ]);
    $viewModel->setTemplate($pageTemplate);
	
    return $viewModel;
}

Aux lignes 3-4 ci-dessus, nous récupérons le paramètre page de la route (souvenez-vous du nom de "page" capturé par notre expression régulière) Et le déclarons en tant que variable $pageTemplate. Nous utiliserons la variable $pageTemplate pour déterminer le nom de la vue à transmettre au résolveur d'affichage. Ensuite, aux lignes 6-10, nous vérifions que le fichier est présent, et si ce n'est pas le cas, renvoyons le code d'état 404 "Not Found", ce qui forcera ZF3 à afficher la page d'erreur. À la ligne 12, nous créons le conteneur de variables ViewModel et à la ligne 15, nous définissons explicitement le nom de la vue pour le rendu.

Pour voir le système de documentation en action, créez deux fichiers de vue "statiques" : la page Table des matières (contents.phtml) et la page Introduction (introduction.phtml). Créez le sous-dossier doc dans le répertoire view/application/index du module Application et placez y la vue contents.phtml :

<h1>Table des matières</h1>

<ul>
    <li>
        <a href="<?= $this->url('doc', ['page'=>'introduction']); ?>">
            Introduction
        </a>
    </li>  
</ul>

Dans les lignes ci-dessus, nous fournissons le code HTML pour l'en-tête de la page "Table des matières" et une liste contenant un seul élément nommé "Introduction" pointant vers la page "statique" Introduction. L'URL du lien est générée avec l'aide de vue Url (pour plus de détails sur l'aide Url[Zend\View\Helper\Url], voir les autres sections de ce chapitre).

Ajoutez ensuite la page introduction.phtml dans le même dossier doc :

<h1>Introduction</h1>

<p>Quelques documents d'introduction</p>

Dans les lignes ci-dessus, nous définissons les balises HTML de la page Introduction.

Maintenant, si vous ouvrez lURL "http://localhost/doc/contents.html" dans votre navigateur, vous devriez voir un système de documentation simple et agréable que vous pouvez étendre et utiliser dans votre site (figure 5.8)

Figure 5.8. Page "Statique"

Cliquer sur le lien Introduction vous dirigera vers la page statique "Introduction". Vous pouvez ajouter d'autres pages au dossier doc pour les rendre automatiquement disponibles aux utilisateurs du site via notre route Regex.

L'inconvénient d'un tel système de documentation est qu'il ne fonctionnera pas avec des pages imbriquées dans des sous-répertoires du dossier doc. La raison de cette limitation réside dans la façon dont la route Regex assemble les URL. Vous ne pouvez pas générer d'URL contenant des caractères slash car ces caractères "non sécurisés" seront automatiquement codés en URL. Nous allons contourner ce problème avec notre route de type personnalisé que nous allons créer à la fin de ce chapitre.