5.10. Générer des URL à partir d'une route

La tâche principale de toute classe de route est de déterminer si une route donnée correspond à la requête HTTP, et, lors de la correspondance, de renvoyer l'ensemble des paramètres par lesquels un contrôleur et une action peuvent être déterminés. Une autre tâche permise par la classe de route permet de générer une URL à partir de paramètres. Cette fonctionnalité peut être utilisée dans les méthodes d'action de votre contrôleur pour générer des URL, par exemple, pour rediriger un utilisateur vers une autre page. Elle peut également être utilisé dans les vues pour générer des liens hypertexte.

5.10.1. Générer des URLs dans les vues

Vos pages contiennent généralement des hyperliens vers d'autres pages. Ces liens peuvent pointer vers une page interne à votre site ou vers une page sur un autre site. Un lien hypertexte est représenté par la balise HTML <a> ayant un attribut href spécifiant l'URL de la page de destination. Ci-dessous, un exemple de lien hypertexte pointant vers une page externe est présenté :

<a href="http://example.com/path/to/page">Un lien vers une page d'un autre site</a>

Lorsque vous générez un lien hypertexte vers une ressource interne à votre site, vous utilisez généralement une URL relative (sans nom d'hôte) :

<a href="/path/to/internal/page">Un lien vers une page interne</a>

Pour générer des URL dans vos vues (fichiers .phtml), vous pouvez utiliser la classe d'aide de vue Url, qui prend le nom de la route en argument d'entrée:

<!-- Un lien vers la page d'accueil -->
<a href="<?= $this->url('home'); ?>">Accueil</a>

<!-- Un lien vers la page A Propos -->
<a href="<?= $this->url('about'); ?>">A Propos</a>

Dans les lignes ci-dessus, nous générons deux URL relatives. A la ligne 2, nous appelons l'aide de vue Url et transmettons le nom de la route "home" comme paramètre. A la ligne 5, nous passons le nom de la route "about" comme argument pour l'aide de vue Url.

Dans l'exemple ci-dessus, l'aide de vue Url utilise en interne l'objet RouteMatch et appelle la route Literal pour assembler l'URL en fonction du nom de la route.

Une fois que la classe PhpRenderer exécute le code de la vue, le balisage HTML de sortie sera le suivant :

<!-- Le lien vers la page d'accueil -->
<a href="/">Home page</a>

<!-- Le lien vers la page A propos -->
<a href="/about">About page</a>

5.10.1.1. Passer des paramètres

Si une route utilise des paramètres variables, vous devez les passer à l'aide de vue Url en tant que deuxième argument :

<!-- Un lien vers la page A propos -->
<a href="<?= $this->url('application', ['action' => 'about']); ?>" >
  A propos 
</a>

<!-- Un lien vers l'image de code-barre -->
<a href="<?= $this->url('application', ['action' => 'barcode',
  'type' => 'code39', 'text' => 'HELLO-WORLD']); ?>" >
  Barcode image </a>

Dans l'exemple ci-dessus, nous utilisons l'aide de vue Url pour générer les deux URL par nom de route et par paramètres. Nous passons le nom de la route "application" comme premier argument, et un tableau de paramètres comme deuxième argument.

A la ligne 2, nous passons le paramètre "action" pour indiquer à la classe de route Segment qu'elle doit remplacer le caractère générique correspondant dans la route par la chaîne "about".

Une fois que la classe PhpRenderer aura exécuté le code de la vue, le code HTML de sortie sera le suivant :

<!-- Un lien vers la page A propos -->
<a href="/application/about" > A propos </a>

<!-- Un lien vers l'image de code-barre -->
<a href="/application/barcode/code39/HELLO-WORLD" > Barcode image </a>

Comme autre exemple, essayons de générer une URL pour notre route Regex (celle qui sert nos pages "statiques") :

<!-- Un lien vers la page Introduction -->
<a href="<?= $this->url('doc', ['page'=>'introduction']); ?>">
 Introduction </a>			  

Cela générera le code HTML suivant :

<!-- Un lien vers la page Introduction -->
<a href="/doc/introduction.html"> Introduction </a>

5.10.1.2. Générer des URLs absolues

Si vous avez besoin de générer une URL absolue (avec le schéma et le nom d'hôte), vous pouvez spécifier un troisième paramètre à l'aide de vue Url. Le troisième paramètre doit être un tableau contenant une ou plusieurs options. Pour assembler l'URL absolue, transmettez l'option force_canonical, comme dans l'exemple ci-dessous :

<!-- Un lien vers la page d'Accueil -->
<a href="<?= $this->url('home', [], ['force_canonical' => true]); ?>" > 
  Accueil </a>
  
<!-- Un lien vers la page A Propos -->
<a href="<?php echo $this->url('application', ['action' => 'about'],
  ['force_canonical' => true]); ?>" > A Propos </a>

A la ligne 2 de l'exemple ci-dessus, nous transmettons le nom de la route "home" comme premier argument, un tableau vide comme deuxième argument et un tableau contenant l'option force_canonical comme troisième argument. Dans les lignes 6-7, nous passons également l'option force_canonical comme troisième argument pour générer l'URL de la page À propos.

Le code HTML résultant du code ci-dessus sera le suivant :

<!-- Un lien vers la page d'Accueil -->
<a href="http://localhost/" > Accueil </a>
  
<!-- Un lien vers la page A Propos -->
<a href="http://localhost/application/index/about" > A Propos </a>

5.10.1.3. Spécifier des paramêtres de requête

Si vous souhaitez que votre URL contienne un parametre de requête, vous pouvez spécifier l'option query dans le troisième argument de l'aide de vue Url. Par exemple, supposons que vous ayez l'action "search" dans un contrôleur (et une route mappée à cette action), et que vous souhaitiez passer un paramêtre de recherche et un nombre de résultats par page. L'URL de cette action serait la suivante: "http://localhost/search?q=topic&count=10". Pour générer cette URL, vous utilisez le code suivant :

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

Dans le code ci-dessus, nous avons spécifié l'option query, qui est le tableau contenant les paires nom => valeur des paramètres de la requête.

5.10.2. Générer des URLs depuis les contrôleurs

Vous pouvez générer des URL dans les méthodes d'action de votre contrôleur à l'aide du plug-in de contrôleur Url. Pour générer une URL, vous appelez la méthode fromRoute() du plugin Url, comme dans l'exemple ci-dessous :

// Un exemple de méthode d'action
public function someAction() 
{
    // Génére une URL qui pointe vers la page d'accueil ('/')
    $url1 = $this->url()->fromRoute('home');
  
    // Génére une URL absolue pointant vers la page À propos
    // ('http://localhost/application/about')
    $url2 = $this->url()->fromRoute('application', 
              ['action'=>'about'], ['force_canonical'=>true]);
}

Les arguments pris par le plugin Url et leur signification sont identiques à ceux de l'aide de vue Url. Ainsi, vous pouvez générer des URL absolues ou relatives de la même manière que dans vos vues.

5.10.3. Encodage d'URL

Lorsque vous générez des URL avec l'aide de vue Url ou avec le plugin de contrôleur Url, vous devez vous souvenir que les URL ne peuvent contenir que des caractères «sécurisés» du jeu de caractères ASCII. Ainsi, si vous passez un paramètre contenant des caractères dangereux, ces caractères seront remplacés par un pourcentage suivi de deux chiffres.

Par exemple, essayons de générer une URL pour notre route Regex et passons le paramètre "page" avec la valeur "/chapter1/introduction".

<!-- Un lien vers la page Introduction -->
<a href="<?= $this->url('doc', ['page'=>'chapter1/introduction']); ?>">
  Introduction </a>			  

Nous pourrions supposer qu'il génère une URL comme "/doc/chapter1/introduction.html". Mais comme le caractère slash ('/') est dangereux, il sera remplacé par les caractères "%2F" pour des raisons de sécurité et nous aurons le code HTML suivant :

<!-- Un lien vers la page Introduction -->
<a href="/doc/chapter1%2Fintroduction.html"> Introduction </a>

Malheureusement, ce lien hypertexte est inutilisable car il ne correspondra pas à notre route Regex.