Routage et création d'URL ¶

Formats d'URL
Routage
Création d'URL
Utilisation des URL élégantes
Normalisation d'URL
Considérations de performance

Lorsqu'une application Yii commence à traiter une URL objet d'une requête, sa première étape consiste à analyser cette URL pour la résoudre en une route. La route est ensuite utilisée pour instancier l'action de contrôleur correspondante pour la prise en charge de la requête. Ce processus est appelé routage.

Le processus inverse du routage, qui consiste à créer une URL à partir d'une route et des paramètres associés de la requête,
est appelé création d'URL. Lorsque l'URL créée est ensuite requise, le processus de routage est capable de la résoudre en la route originale avec les paramètres de requête.

L'élément central en charge du routage et de la création d'URL est le gestionnaire d'URL, qui est enregistré en tant que composant d'application sous le nom urlManager. Le gestionnaire d'URL fournit la méthode parseRequest() pour analyser une requête entrante et la résoudre en une route et les paramètres de requête associés, et la méthode createUrl() pour créer une URL en partant d'une route avec ses paramètres de requête associés.

En configurant le composant urlManager dans la configuration de l'application, vous pouvez laisser votre application reconnaître les formats d'URL arbitraires sans modifier le code existant de votre application. Par exemple, vous pouvez utiliser le code suivant pour créer une URL pour l'action post/view :

use yii\helpers\Url;

// Url::to() appelle UrlManager::createUrl() pour créer une URL
$url = Url::to(['post/view', 'id' => 100]);

Selon la configuration de urlManager, l'URL créée peut ressembler à l'une des URL suivantes (ou autre formats). Et si l'URL est requise plus tard, elle sera toujours analysée pour revenir à la route originale et aux valeurs des paramètres de la requête.

/index.php?r=post%2Fview&id=100
/index.php/post/100
/posts/100

Formats d'URL ¶

Le gestionnaire d'URL prend en charge deux formats d'URL :

le format d'URL par défaut,
le format d'URL élégantes.

Le format d'URL par défaut utilise un paramètre de requête nommé r qui représente la route et les paramètres de requête normaux associés à la route. Par exemple, l'URL /index.php?r=post/view&id=100 represente la route post/view et le paramètre de requête id dont la valeur est 100. Le format d'URL par défaut ne requiert aucune configuration du [[yii\web\UrlManager|gestionnaire d'URL] et fonctionne dans toutes les configurations de serveur Web.

Le format d'URL élégantes utilise le chemin additionnel qui suit le nom du script d'entrée pour représenter la route et les paramètres de requête associés. Par exemple, le chemin additionnel dans l'URL /index.php/post/100 est /post/100 qui, avec une règle d'URL appropriée, peut représenter la route post/view et le paramètre des requête id avec une valeur de 100 . Pour utiliser le format d'URL élégantes, vous devez définir un jeu de règles d'URL en cohérence avec les exigences réelles sur la présentation d'une URL.

Vous pouvez passer d'un format d'URL à l'autre en inversant la propriété enablePrettyUrl du gestionnaire d'URL sans changer quoi que ce soit au code de votre application.

Routage ¶

Le routage se fait en deux étapes :

La requête entrante est analysée et résolue en une route et les paramètres de requête associés.
L'action de contrôleur correspondant à la route analysée est créée pour prendre la requête en charge.

Lors de l'utilisation du format d'URL par défaut, la résolution d'une requête en route est aussi simple que d'obtenir le paramètre nommé r de la méthode GET.

Lors de l'utilisation du format d'URL élégantes, le [[yii\web\UrlManager|gestionnaire d'URL] examine les règles d'URL enregistrées pour trouver une règle qui correspond et résoudre la requête en une route. Si une telle règle n'est pas trouvée, une exception yii\web\NotFoundHttpException est levée.

Une fois que la requête est résolue en une route, il est temps de créer l'action de contrôleur identifiée par la route. La route est éclatée en de multiples parties par des barres obliques de division. Par exemple, site/index est éclatée en site et index. Chacune des parties est considérée comme un identifiant qui peut faire référence à un module, un contrôleur ou une action. En partant de la première partie dans la route, l'application entreprend les étapes suivantes pour créer un module (s'il en existe un), un contrôleur et une action :

Définit l'application comme étant le module courant.
Vérifie si la table de mise en correspondance des contrôleurs du module courant contient l'identifiant courant. Si c'est le cas, un objet controller est créé en respectant la configuration du contrôleur trouvé dans la table de mise en correspondance, et on passe à l'étape 5 pour prendre en compte le reste de la route.
Vérifie si l'identifiant fait référence à un module listé dans la propriété yii\base\Module::modules du module courant. Si c'est le cas, un module est créé en respectant la configuration trouvée dans la liste des modules et on passe à l'étape 2 pour prendre en compte le reste de la route dans le contexte du nouveau module.
Traite l'identifiant comme un identifiant de contrôleur, crée un objet controller et passe à l'étape suivante avec le reste de la route.
Le contrôleur recherche l'identifiant courant dans sa table de mise en correspondance des actions. S'il le trouve, il crée une action respectant la configuration trouvée dans la table de mise en correspondance. Autrement, le contrôleur essaye de créer une action en ligne dont le nom de méthode correspond à l' identifiant d'action courant.

Si une erreur se produit dans l'une des étapes décrites ci-dessus, une exception yii\web\NotFoundHttpException est levée, indiquant l'échec du processus de routage.

Route par défaut ¶

Quand une requête est analysée et résolue en une route vide, la route dite route par défaut est utilisée à sa place. Par défaut, la route par défaut est site/index, qui fait référence à l'action index du contrôleur site. Vous pouvez la personnaliser en configurant la propriété defaultRoute de l'application dans la configuration de l'application comme indiqué ci-dessous :

[
    // ...
    'defaultRoute' => 'main/index',
];

De façon similaire à la route par défaut de l'application, il existe aussi une route par défaut pour les modules. Ainsi s'il existe un module user (utilisateur) et que la requête est résolue en la route user, la propriété defaultRoute du module est utilisée pour déterminer le contrôleur. Par défaut, le nom du contrôleur est default. Si aucune action n'est spécifiée dans la propriété defaultRoute, la propriété defaultAction du contrôleur est utilisée pour déterminer l'action. Dans cet exemple, la route complète serait user/default/index.

La route `attrape-tout` ¶

Parfois, vous désirez mettre votre application Web en mode maintenance temporairement et afficher la même page d'information pour toutes les requêtes. Il y a plusieurs moyens de faire cela. L'une des manières les plus simples est de configurer la propriété yii\web\Application::$catchAll dans la configuration de l'application comme indiqué ci-dessous :

[
    // ...
    'catchAll' => ['site/offline'],
];

Avec la configuration ci-dessus, l'action site/offline est utilisée pour prendre toutes les requêtes entrantes en charge.

La propriété catchAll accepte un tableau dont le premier élément spécifie une route et le reste des éléments des couples clé-valeur pour les paramètres liés à l'action.

Info: le [panneau de débogage] ](https://github.com/yiisoft/yii2-debug/blob/master/docs/guide/README.md) de l'environnement de développement ne fonctionne pas lorsque cette propriété est activée.

Création d'URL ¶

Yii fournit une méthode d'aide yii\helpers\Url::to() pour créer différentes sortes d'URL à partir de routes données et de leurs paramètres de requête associés. Par exemple :

use yii\helpers\Url;

// crée une URL d'une route: /index.php?r=post%2Findex
echo Url::to(['post/index']);

// crée une URL d'une route avec paramètres : /index.php?r=post%2Fview&id=100
echo Url::to(['post/view', 'id' => 100]);

// crée une  URL avec ancre : /index.php?r=post%2Fview&id=100#content
echo Url::to(['post/view', 'id' => 100, '#' => 'content']);

// crée une URL absolue : http://www.example.com/index.php?r=post%2Findex
echo Url::to(['post/index'], true);

// crée une URL absolue en utilisant le schéma https : https://www.example.com/index.php?r=post%2Findex
echo Url::to(['post/index'], 'https');

Notez que dans l'exemple ci-dessus, nous supposons que le format d'URL est le format par défaut. Si le format d'URL élégantes est activé, les URL créées sont différentes et respectent les règles d'URL en cours d'utilisation.

La route passée à la méthode yii\helpers\Url::to() est sensible au contexte. Elle peut être soit relative, soit absolue et normalisée en respect des règles suivantes :

Si la route est une chaîne vide, la yii\web\Controller::route couramment requise est utilisée ;
Si la route ne contient aucune barre oblique de division, elle est considérée comme un identifiant d'action du contrôleur courant et est préfixée par la valeur de l'identifiant yii\web\Controller::uniqueId du contrôleur courant ;
Si la route n'a pas de barre oblique de division en tête, elle est considérée comme une route relative au module courant et préfixée par la valeur de l'identifiant yii\base\Module::uniqueId du module courant.

À partir de la version 2.0.2, vous pouvez spécifier une route en terme d'alias. Si c'est le cas, l'alias est d'abord converti en la route réelle qui est ensuite transformée en route absolue dans le respect des règles précédentes.

Par exemple, en supposant que le module courant est admin et que le contrôleur courant est post,

use yii\helpers\Url;

// route couramment requise : /index.php?r=admin%2Fpost%2Findex
echo Url::to(['']);

// une route relative avec un identifiant d'action seulement : /index.php?r=admin%2Fpost%2Findex
echo Url::to(['index']);

// une route relative : /index.php?r=admin%2Fpost%2Findex
echo Url::to(['post/index']);

// une route absoulue : /index.php?r=post%2Findex
echo Url::to(['/post/index']);

// /index.php?r=post%2Findex     suppose que l'alias "@posts" est défini comme  "/post/index"
echo Url::to(['@posts']);

La méthode yii\helpers\Url::to() est mise en œuvre en appelant les méthodes createUrl() et createAbsoluteUrl() du gestionnaire d'URL. Dans les quelques sous-sections suivantes, nous expliquons comment configurer le gestionnaire d'URL pour personnaliser le format des URL créées.

La méthode yii\helpers\Url::to() prend aussi en charge la création d'URL qui n'ont pas de relation avec des routes particulières. Au lieu de passer un tableau comme premier paramètre, vous devez, dans ce cas, passer une chaîne de caractères. Par exemple :

use yii\helpers\Url;

// URL couramment requise : /index.php?r=admin%2Fpost%2Findex
echo Url::to();

// un alias d'URL: http://example.com
Yii::setAlias('@example', 'http://example.com/');
echo Url::to('@example');

// une URL absolue : http://example.com/images/logo.gif
echo Url::to('/images/logo.gif', true);

En plus de la méthode to(), la classe d'aide yii\helpers\Url fournit aussi plusieurs méthode pratiques de création d'URL. Par exemple :

use yii\helpers\Url;

// URL de page d'accueil: /index.php?r=site%2Findex
echo Url::home();

// URL de base, utile si l'application est déployée dans un sous-dossier du dossier Web racine
echo Url::base();

// l'URL canonique de l'URL couramment requise 
// voir https://en.wikipedia.org/wiki/Canonical_link_element
echo Url::canonical();

// mémorise l'URL couramment requise et la retrouve dans les requêtes subséquentes
Url::remember();
echo Url::previous();

Utilisation des URL élégantes ¶

Pour utiliser les URL élégantes, configurez le composant urlManager dans la configuration de l'application comme indiqué ci-dessous :

[
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'enableStrictParsing' => false,
            'rules' => [
                // ...
            ],
        ],
    ],
]

La propriété enablePrettyUrl est obligatoire car elle active/désactive le format d'URL élégantes. Le reste des propriétés est facultatif. Néanmoins, leur configuration montrée plus haut est couramment utilisée.

showScriptName: cette propriété détermine si le script d'entrée doit être inclus dans l'URL créée. Par exemple, au lieu de créer une URL /index.php/post/100, en définissant cette propriété à false, l'URL /post/100 est générée.
enableStrictParsing: cette propriété détermine si l'analyse stricte est activée . Si c'est le cas, l'URL entrante doit correspondre à au moins une des règles afin d'être traitée comme une requête valide, sinon une exception yii\web\NotFoundHttpException est levée. Si l'analyse stricte est désactivée, lorsqu'aucune
règle ne correspond à l'URL requise, la partie chemin de l'URL est considérée comme étant la route requise.
rules: cette propriété contient une liste de règles spécifiant comme analyser et créer des URL. C'est la propriété principale avec laquelle vous devez travailler afin de créer des URL dont le format satisfait les exigences particulières de votre application.

Note: afin de cacher le nom du script d'entrée dans l'URL créée, en plus de définir la propriété showScriptName à false, vous pouvez aussi configurer votre serveur Web de manière à ce qu'il puisse identifier correctement quel script PHP doit être exécuté lorsqu'une URL requise n'en précise aucun explicitement. Si vous utilisez un serveur Apache ou nginx, vous pouvez vous reporter à la configuration recommandée décrite dans la section Installation.

Règles d'URL ¶

Une règle d'URL est une classe mettant en œuvre l'interface yii\web\UrlRuleInterface, généralement une instance de la classe yii\web\UrlRule. Chaque règle d'URL consiste en un motif utilisé pour être mis en correspondance avec la partie chemin de l'URL, une route, et quelques paramètres de requête. Une règle d'URL peut être utilisée pour analyser une requête si son motif correspond à l'URL requise. Une règle d'URL peut être utilisée pour créer une URL si sa route et le nom de ses paramètres de requête correspondent à ceux qui sont fournis.

Quand le format d'URL élégantes est activé, le gestionnaire d'URL utilise les règles d'URL déclarées dans sa propriété rules pour analyser les requêtes entrantes et créer des URL. En particulier, pour analyser une requête entrante, le gestionnaire d'URL examine les règles dans l'ordre de leur déclaration et cherche la première règle qui correspond à l'URL requise. La règle correspondante est ensuite utilisée pour analyser l'URL et la résoudre en une route et ses paramètres de requête associés. De façon similaire, pour créer une URL, le gestionnaire d'URL cherche la première règle qui correspond à la route donnée et aux paramètres et l'utilise pour créer l'URL.

Vous pouvez configurer la propriété yii\web\UrlManager::$rules sous forme de tableau dont les clés sont les motifs et les valeurs, les routes correspondantes. Chacune des paires motif-route construit une règle d'URL. Par exemple, la configuration des règles suivante déclare deux règles d'URL. La première correspond à l'URL posts et la met en correspondance avec la route post/index. La seconde correspond à une URL qui correspond à l'expression régulière post/(\d+) et la met en correspondance avec la route post/view et le paramètre nommé id.

[
    'posts' => 'post/index', 
    'post/<id:\d+>' => 'post/view',
]

Info: le motif dans une règle est utilisé pour correspondre à la partie chemin d'une URL.
Par exemple, la partie chemin de /index.php/post/100?source=ad est post/100 (les barres obliques de division de début et de fin sont ignorées) et correspond au motif post/(\d+).

En plus de déclarer des règles d'URL sous forme de paires motif-route, vous pouvez aussi les déclarer sous forme de tableaux de configuration. Chacun des tableaux de configuration est utilisé pour configurer un simple objet règle d'URL. C'est souvent nécessaire lorsque vous voulez configurer d'autres propriétés d'une règle d'URL. Par exemple :

'rules' => [
    // ...autres règles d'URL...
    [
        'pattern' => 'posts',
        'route' => 'post/index',
        'suffix' => '.json',
    ],
]

Par défaut, si vous ne spécifiez pas l'option class pour une configuration de règle, elle prend la valeur par défaut yii\web\UrlRule qui est la valeur par défaut définie dans yii\web\UrlManager::$ruleConfig.

Paramètres nommés ¶

Une règle d'URL peut être associée à quelques paramètres de requête nommés qui sont spécifiés dans le motif et respectent le format <ParamName:RegExp>, dans lequel ParamName spécifie le nom du paramètre et RegExp est une expression régulière facultative utilisée pour établir la correspondance avec une valeur de paramètre. Si RegExp n'est pas spécifié, cela signifie que la valeur du paramètre doit être une chaîne de caractères sans aucune barre oblique de division.

Note: vous pouvez seulement spécifier des expressions régulières pour les paramètres. La partie restante du motif est considérée être du texte simple.

Lorsqu'une règle est utilisée pour analyser une URL, elle remplit les paramètres associés avec les valeurs des parties de l'URL qui leur correspondent, et ces paramètres sont rendus disponibles dans $_GET et plus tard dans le composant d'application request. Lorsque la règle est utilisée pour créer une URL, elle prend les valeurs des paramètres fournis et les insère à l'endroit où ces paramètres sont déclarés.

Prenons quelques exemples pour illustrer comment les paramètres nommés fonctionnent. Supposons que nous ayons déclaré les règles d'URL suivantes :

[
    'posts/<year:\d{4}>/<category>' => 'post/index',
    'posts' => 'post/index',
    'post/<id:\d+>' => 'post/view',
]

Lorsque les règles sont utilisées pour analyser des URL :

/index.php/posts est analysée et résolue en la route post/index en utilisant la deuxième règle ;
/index.php/posts/2014/php est analysée et résolue en la route post/index, le paramètre year dont la valeur est 2014 et le paramètre category dont la valeur est php en utilisant la première règle ;
/index.php/post/100 est analysée et résolue en la route post/view et le paramètre id dont la valeur est 100 en utilisant la troisième règle ;
/index.php/posts/php provoque la levée d'une exception yii\web\NotFoundHttpException quand la propriété yii\web\UrlManager::$enableStrictParsing est définie à true, parce qu'elle ne correspond à aucun des motifs. Si yii\web\UrlManager::$enableStrictParsing est définie à false (la valeur par défaut), la partie chemin posts/php est retournée en tant que route. Cela provoque l'exécution de l'action correspondante si elle existe, ou lève une exception yii\web\NotFoundHttpException autrement.

Et quand les règles sont utilisées pour créer des URL :

Url::to(['post/index']) crée /index.php/posts en utilisant la deuxième règle ;
Url::to(['post/index', 'year' => 2014, 'category' => 'php']) crée /index.php/posts/2014/php en utilisant la première règle ;
Url::to(['post/view', 'id' => 100]) crée /index.php/post/100 en utilisant la troisième règle ;
Url::to(['post/view', 'id' => 100, 'source' => 'ad']) crée /index.php/post/100?source=ad en utilisant la troisième règle. Comme le paramètre source n'est pas spécifié dans la règle, il est ajouté en tant que paramètre de requête à l'URL créée.
Url::to(['post/index', 'category' => 'php']) crée /index.php/post/index?category=php en utilisant aucune des règles. Notez que, aucune des règles n'étant utilisée, l'URL est créée en ajoutant simplement la route en tant que partie chemin et tous les paramètres en tant que partie de la chaîne de requête.

Paramétrage des routes ¶

Vous pouvez inclure les noms des paramètres dans la route d'une règle d'URL. Cela permet à une règle d'URL d'être utilisée pour correspondre à de multiples routes. Par exemple, les règles suivantes incluent les paramètres controller et action dans les routes.

'rules' => [
    '<controller:(post|comment)>/create' => '<controller>/create',
    '<controller:(post|comment)>/<id:\d+>/<action:(update|delete)>' => '<controller>/<action>',
    '<controller:(post|comment)>/<id:\d+>' => '<controller>/view',
    '<controller:(post|comment)>s' => '<controller>/index',
]

Pour analyser l'URL /index.php/comment/100/update, la deuxième règle s'applique et définit le paramètre controller
comme étant comment et le paramètre action comme étant create. La route <controller>/<action> est par conséquent résolue comme comment/update.

De façon similaire, pour créer une URL à partir de la route comment/index, la dernière règle s'applique, ce qui donne l'URL /index.php/comments.

Info: en paramétrant les routes, il est possible de réduire grandement le nombre de règles d'URL, ce qui peut accroître significativement la performance du gestionnaire d'URL.

Valeur par défaut des paramètres ¶

Par défaut, tous les paramètres déclarés dans une règle sont requis. Si une URL requise ne contient pas un paramètre particulier, ou si une URL est créée sans un paramètre particulier, la règle ne s'applique pas. Pour rendre certains paramètres facultatifs, vous pouvez configurer la propriété defaults de la règle. Les paramètres listés dans cette propriété sont facultatifs et prennent les valeurs spécifiées lorsqu'elles ne sont pas fournies.

Dans la déclaration suivante d'une règle, les paramètres page et tag sont tous les deux facultatifs et prennent la valeur 1 et vide, respectivement quand ils ne sont pas fournis.

[
    // ...autres règles...
    [
        'pattern' => 'posts/<page:\d+>/<tag>',
        'route' => 'post/index',
        'defaults' => ['page' => 1, 'tag' => ''],
    ],
]

La règle ci-dessus peut être utilisée pour analyser ou créer l'une quelconque des URL suivantes :

/index.php/posts: page est 1, tag est ''.
/index.php/posts/2: page est 2, tag est ''.
/index.php/posts/2/news: page est 2, tag est 'news'.
/index.php/posts/news: page est 1, tag est 'news'.

Sans les paramètres facultatifs, vous devriez créer quatre règles pour arriver au même résultat.

Note: si pattern (motif) ne contient que des paramètres facultatifs et des barres obliques de division, le premier paramètre peut être omis seulement si tous les autres paramètres le sont.

Règles avec des noms de serveur ¶

Il est possible d'inclure des noms de serveur Web dans le motif d'une règle d'URL. Cela est principalement utilisé lorsque votre application doit se comporter différemment selon le nom du serveur Web. Par exemple, les règles suivantes analysent et résolvent l'URL http://admin.example.com/login en la route admin/user/login et http://www.example.com/login en la route site/login.

[
    'http://admin.example.com/login' => 'admin/user/login',
    'http://www.example.com/login' => 'site/login',
]

Vous pouvez aussi inclure des paramètres dans les noms de serveurs pour en extraire de l'information dynamique. Par exemple, la règle suivante analyse et résout l'URL http://en.example.com/posts en la route post/index et le paramètre language=en.

[
    'http://<language:\w+>.example.com/posts' => 'post/index',
]

Depuis la version 2.0.11, vous pouvez également utiliser des motifs relatifs au protocole qui marchent à la fois pour http et https. La syntaxe est la même que ci-dessus mais en sautant la partie http, p. ex. '//www.example.com/login' => 'site/login'.

Note: les règles avec des noms de serveur ne doivent pas comprendre le sous-dossier du script d'entrée dans leur motif. Par exemple, si l'application est sous http://www.example.com/sandbox/blog, alors vous devez utiliser le motif http://www.example.com/posts au lieu de http://www.example.com/sandbox/blog/posts. Cela permet à votre application d'être déployée sous n'importe quel dossier sans avoir à changer son code. Yii détecte automatiquement l'URL de base de l'application.

Suffixes d'URL ¶

Vous désirez peut-être ajouter des suffixes aux URL pour des raisons variées. Par exemple, vous pouvez ajouter .html aux URL de manière à ce qu'elles ressemblent à des URL de pages HTML statiques. Vous pouvez aussi y ajouter .json pour indiquer le type de contenu attendu pour la réponse. Vous pouvez faire cela en configurant la propriété yii\web\UrlManager::$suffix dans la configuration de l'application comme ceci :

[
    // ...
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            // ...
            'suffix' => '.html',
            'rules' => [
                // ...
            ],
        ],
    ],
]

La configuration ci-dessus permet au gestionnaire d'URL de reconnaître les URL requises et aussi de créer des URL avec le suffixe .html.

Tip: vous pouvez définir / en tant que suffixe des URL de manière à ce que tous les URL se terminent par la barre oblique de division.

Note: lorsque vous configurez un suffixe d'URL, si une URL requise ne contient pas ce suffixe, elle est considérée comme une URL non reconnue. Cela est une pratique recommandée pour l'optimisation des moteurs de recherche (SE0 – Search Engine Optimization).

Parfois vous désirez utiliser des suffixes différents pour différentes URL. Cela peut être fait en configurant la propriété suffix des règles d'URL individuelles. Lorsqu'une URL a cette propriété définie, elle écrase la valeur définie au niveau du gestionnaire d'URL. Par exemple, la configuration suivante contient une règle d'URL personnalisée qui utilise .json en tant que suffixe à la place du suffixe défini globalement .html.

[
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            // ...
            'suffix' => '.html',
            'rules' => [
                // ...
                [
                    'pattern' => 'posts',
                    'route' => 'post/index',
                    'suffix' => '.json',
                ],
            ],
        ],
    ],
]

Méthodes HTTP ¶

En mettant en œuvre des API pleinement REST, il est couramment nécessaire que la même URL puisse être résolue en différentes routes selon la méthode HTTP utilisée par la requête. Cela peut être fait facilement en préfixant les motifs des règles avec les méthodes HTTP prises en charge. Si une règle prend en charge plusieurs méthodes HTTP, il faut séparer les noms de méthode par une virgule. Par exemple, les règles suivantes ont le même motif post/<id:\d+> mais des méthodes HTTP différentes. Une requête de PUT post/100 est résolue en la route post/update, tandis que la requête de GET post/100 en la route post/view.

'rules' => [
    'PUT,POST post/<id:\d+>' => 'post/update',
    'DELETE post/<id:\d+>' => 'post/delete',
    'post/<id:\d+>' => 'post/view',
]

Note: si une règle d'URL contient des méthodes HTTP dans son motif, la règle n'est utilisée qu'à des fins d'analyse sauf si GET fait partie des verbes spécifiés. Elle est ignorée quand le gestionnaire d'URL est sollicité pour créer une URL.

Tip: pour simplifier le routage des API pleinement REST, Yii fournit la classe spéciale de règle d'URL yii\rest\UrlRule qui est très efficace et prend en charge quelques fonctionnalités originales comme la pluralisation automatique des identifiants de contrôleur. Pour plus de détails, reportez-vous à la section Routage dans le chapitre API pleinement REST.

Ajout dynamique de règles ¶

Des règles d'URL peuvent être ajoutées dynamiquement au gestionnaire d'URL. Cela est souvent nécessaire pour les modules distribuables qui veulent gérer leurs propres règles d'URL. Pour que les règles ajoutées dynamiquement prennent effet dans de processus de routage, vous devez les ajouter dans l'étape d'amorçage. Pour les modules, cela signifie qu'ils doivent implémenter l'interface yii\base\BootstrapInterface et ajouter les règles dans leur méthode bootstrap() comme l'exemple suivant le montre :

public function bootstrap($app)
{
    $app->getUrlManager()->addRules([
        // rule declarations here
    ], false);
}

Notez que vous devez également lister ces modules dans la propriété yii\web\Application::bootstrap() afin qu'ils puissent participer au processus d'amorçage.

Création des classes règles ¶

En dépit du fait que la classe par défaut yii\web\UrlRule est suffisamment flexible pour la majorité des projets, il y a des situations dans lesquelles vous devez créer votre propres classes de règle. Par exemple, dans un site Web de vendeur de voitures, vous désirerez peut-être prendre en charge des formats d'URL du type /Manufacturer/Model, où Manufacturer et Model doivent correspondre à quelques données stockées dans une base de données. La classe de règle par défaut ne fonctionne pas dans ce cas car elle s'appuie sur des motifs déclarés de manière statique.

Vous pouvez créer les classes de règle d'URL suivantes pour résoudre ce problème :

<?php

namespace app\components;

use yii\web\UrlRuleInterface;
use yii\base\BaseObject;

class CarUrlRule extends BaseObject implements UrlRuleInterface
{
    public function createUrl($manager, $route, $params)
    {
        if ($route === 'car/index') {
            if (isset($params['manufacturer'], $params['model'])) {
                return $params['manufacturer'] . '/' . $params['model'];
            } elseif (isset($params['manufacturer'])) {
                return $params['manufacturer'];
            }
        }
        return false;  // this rule does not apply
    }

    public function parseRequest($manager, $request)
    {
        $pathInfo = $request->getPathInfo();
        if (preg_match('%^(\w+)(/(\w+))?$%', $pathInfo, $matches)) {
            // vérifie  $matches[1] et $matches[3] pour voir si
            // elles correspondent à un  manufacturer et à un model dans la base de données
            // si oui, définit $params['manufacturer'] et/ou $params['model']
            // et retourne  ['car/index', $params]
        }
        return false;  // cette règle ne s'applique pas
    }
}

Et utilisez la nouvelle classe de règle dans la configuration de yii\web\UrlManager::$rules :

[
    // ...other rules...
    
    [
        'class' => 'app\components\CarUrlRule', 
        // ...configure d'autres propriétés...
    ],
]

Normalisation d'URL ¶

Depuis la version 2.0.10, le gestionnaire d'URL peut être configuré pour utiliser le normalisateur d'URL pour prendre en compte les variations de la même URL, p. ex. avec et sans la barre oblique de division de fin.

Parce que, techniquement, http://example.com/path et http://example.com/path/ sont des URL différentes, servir le même contenu pour chacune d'elles peut dégrader le classement SEO. Par défaut, le normalisateur fusionne les barres obliques de division consécutives, ajoute ou retire des barres de division de fin selon que le suffixe comporte une barre de division de fin ou pas, et redirige vers la version normalisée de l'URL en utilisant la redirection permanente. Le normalisateur peut être configuré globalement pour le gestionnaire d'URL ou individuellement pour chacune des règles — par défaut, chacune des règles utilise le normalisateur du gestionnaire d'URL. Vous pouvez définir UrlRule::$normalizer à false pour désactiver la normalisation pour une règle d'URL particulière.

Ce qui suit est un exemple de configuration pour le normalisateur d'URL:

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    'enableStrictParsing' => true,
    'suffix' => '.html',
    'normalizer' => [
        'class' => 'yii\web\UrlNormalizer',
        // utilise la redirection temporaire au lieu de la redirection permanente pour le débogage
        'action' => UrlNormalizer::ACTION_REDIRECT_TEMPORARY,
    ],
    'rules' => [
        // ...autres règles...
        [
            'pattern' => 'posts',
            'route' => 'post/index',
            'suffix' => '/',
            'normalizer' => false, // désactive le normalisateur pour cette règle
        ],
        [
            'pattern' => 'tags',
            'route' => 'tag/index',
            'normalizer' => [
                // ne fusionne pas les barres obliques de division consécutives pour cette règle
                'collapseSlashes' => false,
            ],
        ],
    ],
]

Note: par défaut UrlManager::$normalizer est désactivé. Vous devez le configure explicitement pour activer la normalisation d'URL.

Considérations de performance ¶

Lors du développement d'une application Web complexe, il est important d'optimiser les règles d'URL afin que l'analyse des requêtes et la création d'URL prennent moins de temps.

En utilisant les routes paramétrées, vous pouvez réduire le nombre de règles d'URL, ce qui accroît significativement la performance.

Lors de l'analyse d'URL ou de la création d'URL, le gestionnaire d'URL examine les règles d'URL dans l'ordre de leur déclaration. En conséquence, vous devez envisager d'ajuster cet ordre afin que les règles les plus spécifiques et/ou utilisées couramment soient placées avant les règles les moins utilisées.

Si quelques règles d'URL partagent le même préfixe dans leur motif ou dans leur route, vous pouvez envisager d'utiliser yii\web\GroupUrlRule pour qu'elles puissent être examinées plus efficacement par le gestionnaire d'URL en tant que groupe. Cela est souvent le cas quand votre application est composée de modules, chacun ayant son propre jeu de règles d'URL avec l'identifiant de module comme préfixe commun.

Routage et création d'URL ¶

Formats d'URL ¶

Routage ¶

Route par défaut ¶

La route attrape-tout ¶

Création d'URL ¶

Utilisation des URL élégantes ¶

Règles d'URL ¶

Paramètres nommés ¶

Paramétrage des routes ¶

Valeur par défaut des paramètres ¶

Règles avec des noms de serveur ¶

Suffixes d'URL ¶

Méthodes HTTP ¶

Ajout dynamique de règles ¶

Création des classes règles ¶

Normalisation d'URL ¶

Considérations de performance ¶

La route `attrape-tout` ¶