Merge pull request #8312 from kenjis/docs-upgrade_routing

docs: improve upgrade_routing

Author: kenjis

user_guide_src/source/incoming/routing.rst

@@ -69,6 +69,8 @@ and the ``productLookupByID()`` method passing in the match as a variable to the
 
 .. literalinclude:: routing/009.php
 
+.. _routing-http-verb-routes:
+
 HTTP verb Routes
 ================
 
@@ -185,11 +187,20 @@ Placeholders Description
 .. note:: ``{locale}`` cannot be used as a placeholder or other part of the route, as it is reserved for use
     in :doc:`localization </outgoing/localization>`.
 
-Note that a single ``(:any)`` will match multiple segments in the URL if present. For example the route:
+.. _routing-placeholder-any:
+
+The Behavior of (:any)
+^^^^^^^^^^^^^^^^^^^^^^
+
+Note that a single ``(:any)`` will match multiple segments in the URL if present.
+
+For example the route:
 
 .. literalinclude:: routing/010.php
 
-will match **product/123**, **product/123/456**, **product/123/456/789** and so on. The implementation in the
+will match **product/123**, **product/123/456**, **product/123/456/789** and so on.
+
+The implementation in the
 Controller should take into account the maximum parameters:
 
 .. literalinclude:: routing/011.php

user_guide_src/source/installation/upgrade_routing.rst

@@ -17,18 +17,22 @@ What has been changed
 - In CI4 the Auto Routing is disabled by default.
 - In CI4 the new more secure :ref:`auto-routing-improved` is introduced.
 - In CI4 the routing is no longer configured by setting the routes as array.
+- The Wildcard ``(:any)`` In CI3 will be the Placeholder ``(:segment)`` in CI4. The ``(:any)`` in CI4 matches multiple segements. See :ref:`URI Routing <routing-placeholder-any>`.
 
 Upgrade Guide
 =============
 
 1. If you use the Auto Routing in the same way as CI3, you need to enable :ref:`auto-routing-legacy`.
-2. The placeholder ``(:any)`` in CI3 will be ``(:segment)`` in CI4.
-3. You have to change the syntax of each routing line and append it in **app/Config/Routes.php**. For example:
+2. You have to change the syntax of each routing line and append it in **app/Config/Routes.php**. For example:
 
     - ``$route['journals'] = 'blogs';`` to ``$routes->add('journals', 'Blogs::index');``. This would map to the ``index()`` method in the ``Blogs`` controller.
-    - ``$route['product/(:any)'] = 'catalog/product_lookup';`` to ``$routes->add('product/(:segment)', 'Catalog::productLookup');``
+    - ``$route['product/(:any)'] = 'catalog/product_lookup';`` to ``$routes->add('product/(:segment)', 'Catalog::productLookup');``. Don't forget to replace ``(:any)`` with ``(:segment)``.
     - ``$route['login/(.+)'] = 'auth/login/$1';`` to ``$routes->add('login/(.+)', 'Auth::login/$1');``
 
+    .. note:: For backward compatibility, ``$routes->add()`` is used here. But we
+        strongly recommend to use :ref:`routing-http-verb-routes` like
+        ``$routes->get()`` instead of ``$routes->add()`` for security.
+
 Code Example
 ============
 
@@ -43,3 +47,7 @@ CodeIgniter Version 4.x
 Path: **app/Config/Routes.php**:
 
 .. literalinclude:: upgrade_routing/001.php
+
+.. note:: For backward compatibility, ``$routes->add()`` is used here. But we
+    strongly recommend to use :ref:`routing-http-verb-routes` like
+    ``$routes->get()`` instead of ``$routes->add()`` for security.

user_guide_src/source/installation/upgrade_routing/001.php

@@ -1,16 +1,11 @@
 <?php
 
-namespace Config;
+use CodeIgniter\Router\RouteCollection;
 
-// ...
-
-/*
- * --------------------------------------------------------------------
- * Route Definitions
- * --------------------------------------------------------------------
+/**
+ * @var RouteCollection $routes
  */
-
-// ...
+$routes->get('/', 'Home::index');
 
 $routes->add('posts/index', 'Posts::index');
 $routes->add('teams/create', 'Teams::create');
@@ -21,5 +16,3 @@
 $routes->add('drivers/create', 'Drivers::create');
 $routes->add('drivers/update', 'Drivers::update');
 $routes->add('posts/(:segment)', 'Posts::view/$1');
-
-// ...