5.4. Configuration du routage

En général, vous ne créez pas la pile de routage (ou l'arborescence) vous-même, mais vous fournissez les instructions à ZF3 sur la façon de procéder.

La configuration de routage pour un module est stockée dans le fichier de configuration module.config.php :

<?php
use Zend\Router\Http\TreeRouteStack;

return [
    //...
    'router' => [
        'router_class' => TreeRouteStack::class,
        'routes' => [	
            // Déclarez vos règles de routage ici...
        ],
        'default_params' => [	
            // Spécifiez les paramètres par défaut pour toutes les routes ici	
        ]
    ],
];

Ci-dessus, à la ligne 6, nous avons la clé router, sous laquelle il y a la sous-clé routes (ligne 8) contenant les règles de routage.

Vous pouvez spécifier la classe de route de niveau supérieur à utiliser (TreeRouteStack ou SimpleRouteStack) avec le paramètre router_class (ligne 7). Si ce paramètre n'est pas présent, TreeRouteStack est utilisé par défaut.

Vous pouvez utiliser la clé facultative default_params (ligne 11) pour définir les valeurs par défaut des paramètres pour toutes les routes à la fois. Toutefois, vous n'utilisez généralement pas cette clé et définissez les valeurs par défaut pour chaque route.

Nous allons voir comment sont extraits les paramètres de l'itinéraire plus loin dans ce chapitre.

5.4.1. Configuration des routes simples

Un itinéraire basique a un name, type et des options :

• Le name est utilisé pour identifier de manière unique l'itinéraire.
• Le type définit le nom complet du type de route (classe PHP qui implémente l'algorithme de correspondance).
• Les options sont un tableau qui inclut la route qui doit être comparée à la partie URL et plusieurs paramètres appelés defaults (les valeurs par défaut).

La configuration de chaque route de la sous-clé routes peut avoir le format suivant :

'<route_name>' => [
    'type' => '<route_type_class>',
    'priority' => <priority>,
    'options' => [
        'route' => '<route>',
        'defaults' => [
            //...
        ],
    ],  
]

Ci-dessus, l'espace <route_name> correspond au nom de la route. Un nom de route doit être écrit en minuscules comme "home" ou "about". La clé type spécifie le nom complet de la classe de route.

La clé optionnelle priority permet de définir la priorité (qui doit être un nombre entier) de la route dans la liste priorisée (les routes de priorité supérieure seront visitées en premier). Si vous omettez la clé de priorité, les routes seront visitées dans l'ordre ⁴.

Les routes ayant la même priorité seront visitées dans l'ordre LIFO. Ainsi, pour de meilleures performances, vous devez déclarer les routes qui correspondent le plus souvent à la fin et les routes les moins communes doivent être déclarées en premier.

La clé options définit le tableau des options de routage. Nous discuterons des options dans les sections suivantes de ce chapitre.

5.4.2. Configuration pour les routes imbriqués

Pour organiser les itinéraires dans un sous-arbre, vous ajoutez la clé child_routes à la définition de la route et ajoutez vos routes enfants sous cette clé, comme ci-dessous :

'<route_name>' => [
    'type' => '<route_type_class>',
    'priority' => <priority>,
    'options' => [
        //...
    ],
    'child_routes' => [
        // Ajouter des routes enfants ici.
        // ...
    ]	
],

Si vous devez organiser les routes dans une chaîne (sous-arbre dégénéré), vous ajoutez la clé chain_routes à votre configuration :

'<route_name>' => [
    'type' => '<route_type_class>',
    'priority' => <priority>,
    'options' => [
        //...
    ],
    'chain_routes' => [
        // Ajouter des routes chaînées ici
        // ...
    ]	
],

En regardant les deux exemples ci-dessus, vous ne verrez pas l'utilisation explicite des types de routes Part et Chain car (pour plus de commodité) ils sont utilisés automatiquement par ZF3 lorsqu'il rencontre les clés child_routes et chain_routes dans la configuration de votre routage.

5.4.3. Configuration du routage par défaut dans l'application Zend Skeleton

Maintenant que vous savez comment configurer les routes et les organiser dans des structures composées, regardons un exemple concret. Dans l'application Zend Skeleton, la configuration de routage ressemble à ci-dessous :

<?php
use Zend\Router\Http\Literal;
use Zend\Router\Http\Segment;

return [
    'router' => [
        'routes' => [
            'home' => [
                'type' => Literal::class,
                'options' => [
                    'route'    => '/',
                    'defaults' => [
                        'controller' => Controller\IndexController::class,
                        'action'     => 'index',
                    ],
                ],
            ],
            'application' => [
                'type'    => Segment::class,
                'options' => [
                    'route'    => '/application[/:action]',
                    'defaults' => [
                        'controller'    => Controller\IndexController::class,
                        'action'        => 'index',
                    ],
                ],
            ],
        ],
    ],
    
  //...
];

Dans la configuration présentée ci-dessus, nous avons deux règles de routage listées successivement : d'abord nous avons la route "home" (ligne 8) et ensuite nous avons la route "application" (ligne 18).

La route "home" mappe le chemin URL vide à l'action "index" du contrôleur IndexController. Par exemple, entrez "http://localhost/" dans votre navigateur pour afficher la page d'accueil de votre site. Cette route est de type "Littéral".

La route "application" (de type "Segment") mappe des URL ressemblant à "http://localhost/application", "http://localhost/application/about", "http://localhost/application/news", tec. sur l'action correspondante du contrôleur IndexController. Le nom de l'action réelle est déterminé par le paramètre "action". La valeur par défaut de ce paramètre est "index". Cela signifie que si vous ne spécifiez aucune action, la requête sera envoyée à l'action "index".

Cette configuration correspond à la pile de route arborescente illustrée à la figure 5.5 :

Figure 5.5. Pile d'itinéraire par défaut dans l'application skeleton

Dans les sections suivantes, nous vous fournirons des exemples d'utilisation des différents types de routes dans votre application.