diff --git a/fr/development/routing.rst b/fr/development/routing.rst index 6152cf7104..9cf29454d0 100644 --- a/fr/development/routing.rst +++ b/fr/development/routing.rst @@ -51,11 +51,19 @@ empêcher les visiteurs d'accéder à une URLs ressemblant à ``/articles/foobar``. Si vous le souhaitez, vous pouvez restreindre certains paramètres grâce à une expression régulière:: + $routes->connect( + '/articles/:id', + ['controller' => 'Articles', 'action' => 'view'], + ) + ->setPatterns(['id' => '\d+']) + ->setPass(['id']); + + // Avant 3.5, utilisez les tableaux d'options $routes->connect( '/articles/:id', ['controller' => 'Articles', 'action' => 'view'], ['id' => '\d+', 'pass' => ['id']] - ); + ) Dans l'exemple précédent, le caractère jocker ``*`` est remplacé par un placeholder ``:id``. Utiliser les placeholders nous permet de valider les @@ -129,6 +137,7 @@ scope et connecter certaines routes, nous allons utiliser la méthode use Cake\Routing\Route\DashedRoute; Router::scope('/', function ($routes) { + // Connecte la route de 'fallback' générique $routes->fallbacks(DashedRoute::class); }); @@ -140,7 +149,7 @@ règles d'expression régulière pour aider le router à faire correspondre les Le format basique pour une définition de route est:: $routes->connect( - 'URL template', + '/url/template', ['default' => 'defaultValue'], ['option' => 'matchingRegex'] ); @@ -198,17 +207,18 @@ site qui propose des produits pour différentes catégories de clients, vous pourriez considérer la création d'une route. Cela vous permet de vous lier à ``/government`` plutôt qu'à ``/pages/display/5``. -Une autre utilisation ordinaire pour le Router est de définir un "alias" pour -un controller. Disons qu'au lieu d'accéder à notre URL régulière à -``/users/some_action/5``, nous aimerions être capable de l'accéder avec -``/cooks/some_action/5``. La route suivante s'occupe de cela:: +Une utilisation classique du routing peut impliquer la création de segments +d'URL qui ne correspondent pas aux noms de vos controllers ou de vos models. +Imaginons qu'au lieu de vouloir accéder à une URL ``/users/some_action/5``, +vous souhaitiez y accéder via ``/cooks/une_action/5``. Pour ce faire, +vous devriez configurer la route suivante:: $routes->connect( '/cooks/:action/*', ['controller' => 'Users'] ); Cela dit au Router que toute URL commençant par ``/cooks/`` devrait être envoyée -au controller users. L'action appelée dépendra de la valeur du paramètre +au ``UsersController``. L'action appelée dépendra de la valeur du paramètre ``:action``. En utilisant :ref:`route-elements`, vous pouvez créer des routes variables, qui acceptent les entrées utilisateur ou les variables. La route ci-dessus utilise aussi l'étoile greedy. L'étoile greedy indique au @@ -221,6 +231,46 @@ Quand on génère les URLs, les routes sont aussi utilisées. Utiliser ``/cooks/some_action/5`` si la route ci-dessus est la première correspondante trouvée. +Les routes connectées jusque là fonctionneront avec n'importe quel verbe HTTP. +Si vous souhaitez construire une API REST, vous aurez probablement besoin de faire +correspondre des actions HTTP à des méthodes de controller différentes. +Le ``RouteBuilder`` met à disposition des méthodes qui rendent plus facile la +définition de routes pour des verbes HTTP spécifiques:: + + // Crée une route qui ne répondra qu'aux requêtes GET. + $routes->get( + '/cooks/:id', + ['controller' => 'Users', 'action' => 'view'], + 'users:view' + ); + + // Crée une route qui ne répondra qu'aux requêtes PUT + $routes->put( + '/cooks/:id', + ['controller' => 'Users', 'action' => 'update'], + 'users:update' + ); + +Les méthodes ci-dessus *mappent* la même URL à des actions différentes en fonction +du verbe HTTP utilisé. Les requêtes GET pointeront sur l'action 'view' tandis que les +requêtes PUT pointeront sur l'action 'update'. Ces méthodes sont disponibles pour les +verbes : + +* GET +* POST +* PUT +* PATCH +* DELETE +* OPTIONS +* HEAD + +Toutes ces méthodes retournent une instance de Route ce qui vous permet d'utiliser les +:ref:`setters fluides ` pour configurer plus précisément vos +routes. + +.. versionadded:: 3.5.0 + Les méthodes pour les verbes HTTP ont été ajoutées dans 3.5.0 + .. _route-elements: Les Eléments de Route @@ -237,6 +287,12 @@ correctement formée ou non. Si vous choisissez de ne pas fournir une expression régulière, toute expression non ``/`` sera traitée comme une partie du paramètre:: + $routes->connect( + '/:controller/:id', + ['action' => 'view'] + )->setPatterns(['id' => '[0-9]+']); + + // Avant 3.5, utilisez les options de tableau $routes->connect( '/:controller/:id', ['action' => 'view'], @@ -258,11 +314,19 @@ l'exemple ci-dessus peut être réécrit en:: use Cake\Routing\Route\DashedRoute; - $routes->connect( - '/:controller/:id', - ['action' => 'view'], - ['id' => '[0-9]+', 'routeClass' => DashedRoute::class] - ); + // Crée un builder avec une classe de Route différente. + $routes->scope('/', function ($routes) { + $routes->routeClass(DashedRoute::class); + $routes->connect('/:controller/:id', ['action' => 'view']) + ->setPatterns(['id' => '[0-9]+']); + + // Avant 3.5, utilisez le tableau d'options + $routes->connect( + '/:controller/:id', + ['action' => 'view'], + ['id' => '[0-9]+'] + ); + }); La classe spéciale ``DashedRoute`` va s'assurer que les paramètres ``:controller`` et ``:plugin`` sont correctement mis en minuscule et avec des @@ -292,23 +356,23 @@ comme ``/demo`` à la place de ``/home/demo``, vous pouvez faire ce qui suit:: Si vous souhaitez fournir une URL non sensible à la casse, vous pouvez utiliser les modificateurs en ligne d'expression régulière:: + // Avant 3.5, utilisez le tableau d'options à la place de setPatterns() $routes->connect( '/:userShortcut', ['controller' => 'Teachers', 'action' => 'profile', 1], - ['userShortcut' => '(?i:principal)'] - ); + )->setPatterns(['userShortcut' => '(?i:principal)']); Un exemple de plus, et vous serez un pro du routing:: + // Avant 3.5, utilisez le tableau d'options à la place de setPatterns() $routes->connect( '/:controller/:year/:month/:day', - ['action' => 'index'], - [ - 'year' => '[12][0-9]{3}', - 'month' => '0[1-9]|1[012]', - 'day' => '0[1-9]|[12][0-9]|3[01]' - ] - ); + ['action' => 'index'] + )->setPatterns([ + 'year' => '[12][0-9]{3}', + 'month' => '0[1-9]|1[012]', + 'day' => '0[1-9]|[12][0-9]|3[01]' + ]); C'est assez complexe, mais montre comme les routes peuvent vraiment devenir puissantes. L'URL fournie a quatre éléments de route. Le premier @@ -357,6 +421,44 @@ spécifiquement utiliser leur signification. * ``_name`` Nom de route. Si vous avez configuré les routes nommées, vous pouvez utiliser cette clé pour les spécifier. +.. _route-fluent-methods: + +Configurer les Options de Route +------------------------------- + +Il y a de nombreuses options de routes qui peuvent être définies pour chaque route. +Après avoir connecté une route, vous pouvez utiliser ses méthodes de construction +fluide pour la configurer. Ces méthodes remplacent la majorité des clés du paramètre +``$options`` de la méthode ``connect()``:: + + $routes->connect( + '/:lang/articles/:slug', + ['controller' => 'Articles', 'action' => 'view'], + ) + // Autorise les requêtes GET & POST. + ->setMethods(['GET', 'POST']) + + // Match seulement le sous-domaine 'blog' + ->setHost('blog.example.com') + + // Définit l'élément de la route qui devrait être converti en argument + ->setPass(['slug']) + + // Définit les patterns de correspondance pour les éléments de route + ->setPatterns([ + 'slug' => '[a-z0-9-_]+', + 'lang' => 'en|fr|es', + ]) + + // Autorise également l'extension JSON + ->setExtenions(['json']) + + // Définit 'lang' pour être un paramètre persistant + ->setPersist(['lang']); + +.. versionadded:: 3.5.0 + Les méthodes fluides ont été ajoutées dans 3.5.0 + Passer des Paramètres à l'Action -------------------------------- @@ -376,17 +478,17 @@ passé aux fonctions du controller:: Router::scope('/', function ($routes) { $routes->connect( '/blog/:id-:slug', // E.g. /blog/3-CakePHP_Rocks - ['controller' => 'Blogs', 'action' => 'view'], - [ - // Défini les éléments de route dans le template de route - // à passer en tant qu'arguments à la fonction. L'ordre est - // important car cela fera simplement correspondre ":id" avec - // articleId dans votre action. - 'pass' => ['id', 'slug'], - // Défini un modèle auquel `id` doit correspondre. - 'id' => '[0-9]+' - ] - ); + ['controller' => 'Blogs', 'action' => 'view'] + ) + ->setPatterns([ + // Défini les éléments de route dans le template de route + // à passer en tant qu'arguments à la fonction. L'ordre est + // important car cela fera simplement correspondre ":id" avec + // articleId dans votre action. + 'pass' => ['id', 'slug'], + // Define a pattern that `id` must match. + 'id' => '[0-9]+', + ]); }); Maintenant, grâce aux possibilités de routing inversé, vous pouvez passer @@ -429,8 +531,15 @@ utiliser:: ['_name' => 'login'] ); + // Nommage d'une route liée à un verbe spécifique (3.5.0+) + $routes->post( + '/logout', + ``['controller' => 'Users', 'action' => 'logout'], + 'logout' + ); + // Génère une URL en utilisant une route nommée. - $url = Router::url(['_name' => 'login']); + $url = Router::url(['_name' => 'logout']); // Génère une URL en utilisant une route nommée, // avec certains args query string @@ -452,7 +561,7 @@ scope:: Router::scope('/api', ['_namePrefix' => 'api:'], function ($routes) { // le nom de cette route sera `api:ping` - $routes->connect('/ping', ['controller' => 'Pings'], ['_name' => 'ping']); + $routes->get('/ping', ['controller' => 'Pings'], 'ping'); }); Router::plugin('Contacts', ['_namePrefix' => 'contacts:'], function ($routes) { @@ -469,7 +578,7 @@ elle fonctionne comme vous pouvez vous y attendre:: Router::plugin('Contacts', ['_namePrefix' => 'contacts:'], function ($routes) { $routes->scope('/api', ['_namePrefix' => 'api:'], function ($routes) { // Le nom de cette route sera `contacts:api:ping` - $routes->connect('/ping', ['controller' => 'Pings'], ['_name' => 'ping']); + $routes->get('/ping', ['controller' => 'Pings'], 'ping'); }); }); @@ -661,19 +770,36 @@ Matching des Méthodes HTTP Spécifiques -------------------------------------- Les routes peuvent "matcher" des méthodes HTTP spécifiques en utilisant -l'option ``_method``:: +les méthodes spécifiques:: Router::scope('/', function($routes) { - // Cette route ne sera "matcher" que sur les requêtes POST. - $routes->connect( + // Cette route matchera seulement les requêtes POST. + $routes->post( '/reviews/start', - ['controller' => 'Reviews', 'action' => 'start', '_method' => 'POST'] + ['controller' => 'Reviews', 'action' => 'start'] ); + + // Matcher plusieurs verbes + // Avant 3.5, utilisez $options['_method'] pour définir les méthodes + $routes->connect( + '/reviews/start', + [ + 'controller' => 'Reviews', + 'action' => 'start', + ] + )->setMethods(['POST', 'PUT']); }); Vous pouvez "matcher" plusieurs méthodes HTTP en fournissant un tableau. Puisque que l'option ``_method`` est une clé de routage, elle est utilisée à la -fois dans le parsing des URL et la génération des URL. +fois dans le parsing des URL et la génération des URL. Pour générer des URL pour +des routes spécifiques, vous devez utiliser la clé ``_method`` lors de la génération:: + + $url = Router::url([ + 'controller' => 'Reviews', + 'action' => 'start', + '_method' => 'POST', + ]); Matching de Noms de Domaine Spécifiques --------------------------------------- @@ -684,18 +810,17 @@ n'importe quelle sous-domaine:: Router::scope('/', function($routes) { // Cette route ne va "matcher" que sur le domaine http://images.example.com + // Avant 3.5, utilisez l'option _host $routes->connect( '/images/default-logo.png', - ['controller' => 'Images', 'action' => 'default'], - ['_host' => 'images.example.com'] - ); + ['controller' => 'Images', 'action' => 'default'] + )->setHost('images.example.com'); // Cette route matchera sur tous les sous-domaines http://*.example.com $routes->connect( '/images/old-log.png', - ['controller' => 'Images', 'action' => 'oldLogo'], - ['_host' => '*.example.com'] - ); + ['controller' => 'Images', 'action' => 'oldLogo'] + )->setHost('images.example.com'); }); L'option ``_host`` n'affecte que le parsing des URL depuis les requêtes et @@ -754,11 +879,8 @@ un scope comme ceci:: $routes->extensions(['json', 'xml', 'html']); $routes->connect( '/:title', - ['controller' => 'Pages', 'action' => 'view'], - [ - 'pass' => ['title'] - ] - ); + ['controller' => 'Pages', 'action' => 'view'] + )->setPass(['title']); }); Ensuite, pour créer des liens, utilisez simplement:: @@ -1146,6 +1268,7 @@ vous générez des URLs: * ``_host`` Définit l'hôte à utiliser pour le lien. Par défaut à l'hôte courant. * ``_port`` Définit le port si vous avez besoin de créer les liens sur des ports non-standards. +* ``_method`` Définit le verbe HTTP à utiliser pour cette URL. * ``_full`` Si à ``true``, la constante `FULL_BASE_URL` va être ajoutée devant les URLS générées. * ``_ssl`` Défini à ``true`` pour convertir l'URL générée à https, ou ``false`` @@ -1225,6 +1348,15 @@ d'une route en utilisant l'option ``routeClass``:: ['routeClass' => 'SlugRoute'] ); + // Ou en définissant la routeClass dans votre scope. + $routes->scope('/', function ($routes) { + $routes->routeClass('SlugRoute'); + $routes->connect( + '/:slug', + ['controller' => 'Articles', 'action' => 'view'] + ); + }); + Cette route créera une instance de ``SlugRoute`` et vous permettra d'implémenter une gestion des paramètres personnalisée. Vous pouvez utiliser les classes routes des plugins en utilisant la :term:`syntaxe de plugin` standard.