[fr] Follows #5019

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 <route-fluent-methods>` 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.