Merge pull request #7015 from kenjis/feat-spark-route-sort-by-handler

feat: `spark routes` option to sort by handler

Author: kenjis

system/Commands/Utilities/Routes.php

@@ -66,15 +66,19 @@ class Routes extends BaseCommand
     /**
      * the Command's Options
      *
-     * @var array
+     * @var array<string, string>
      */
-    protected $options = [];
+    protected $options = [
+        '-h' => 'Sort by Handler.',
+    ];
 
     /**
      * Displays the help for the spark cli script itself.
      */
     public function run(array $params)
     {
+        $sortByHandler = array_key_exists('h', $params);
+
         $collection = Services::routes()->loadRoutes();
         $methods    = [
             'get',
@@ -157,11 +161,16 @@ public function run(array $params)
             'Method',
             'Route',
             'Name',
-            'Handler',
+            $sortByHandler ? 'Handler ↓' : 'Handler',
             'Before Filters',
             'After Filters',
         ];
 
+        // Sort by Handler.
+        if ($sortByHandler) {
+            usort($tbody, static fn ($handler1, $handler2) => strcmp($handler1[3], $handler2[3]));
+        }
+
         CLI::table($tbody, $thead);
     }
 }

tests/system/Commands/RoutesTest.php

@@ -77,6 +77,32 @@ public function testRoutesCommand()
         $this->assertStringContainsString($expected, $this->getBuffer());
     }
 
+    public function testRoutesCommandSortByHandler()
+    {
+        $this->getCleanRoutes();
+
+        command('routes -h');
+
+        $expected = <<<'EOL'
+            +---------+---------+---------------+----------------------------------------+----------------+---------------+
+            | Method  | Route   | Name          | Handler ↓                              | Before Filters | After Filters |
+            +---------+---------+---------------+----------------------------------------+----------------+---------------+
+            | GET     | closure | »             | (Closure)                              |                | toolbar       |
+            | GET     | /       | »             | \App\Controllers\Home::index           |                | toolbar       |
+            | GET     | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | HEAD    | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | POST    | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | PUT     | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | DELETE  | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | OPTIONS | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | TRACE   | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | CONNECT | testing | testing-index | \App\Controllers\TestController::index |                | toolbar       |
+            | CLI     | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            +---------+---------+---------------+----------------------------------------+----------------+---------------+
+            EOL;
+        $this->assertStringContainsString($expected, $this->getBuffer());
+    }
+
     public function testRoutesCommandAutoRouteImproved()
     {
         $routes = $this->getCleanRoutes();

user_guide_src/source/changelogs/v4.3.0.rst

@@ -208,6 +208,9 @@ Commands
 - Added ``spark filter:check`` command to check the filters for a route. See :ref:`Controller Filters <spark-filter-check>` for the details.
 - Added ``spark make:cell`` command to create a new Cell file and its view. See :ref:`generating-cell-via-command` for the details.
 - Now ``spark routes`` command shows route names. See :ref:`URI Routing <routing-spark-routes>`.
+- Now ``spark routes`` command can sort the output by Handler.
+  See :ref:`routing-spark-routes-sort-by-handler`.
+
 - Help information for a spark command can now be accessed using the ``--help`` option (e.g. ``php spark serve --help``)
 - Added methods ``CLI::promptByMultipleKeys()`` to support multiple value in input, unlike ``promptByKey()``. See :ref:`prompt-by-multiple-keys` for details.
 - HTTP/3 is now considered a valid protocol.

user_guide_src/source/incoming/routing.rst

@@ -804,6 +804,9 @@ Since v4.3.0, the *Name* column shows the route name. ``»`` indicates the name
 
 .. important:: The system is not perfect. If you use Custom Placeholders, *Filters* might not be correct. If you want to check filters for a route, you can use :ref:`spark filter:check <spark-filter-check>` command.
 
+Auto Routing (Improved)
+-----------------------
+
 When you use Auto Routing (Improved), the output is like the following:
 
 .. code-block:: none
@@ -818,6 +821,9 @@ The *Method* will be like ``GET(auto)``.
 
 ``/..`` in the *Route* column indicates one segment. ``[/..]`` indicates it is optional.
 
+Auto Routing (Legacy)
+---------------------
+
 When you use Auto Routing (Legacy), the output is like the following:
 
 .. code-block:: none
@@ -833,3 +839,14 @@ The *Method* will be ``auto``.
 ``[/...]`` in the *Route* column indicates any number of segments.
 
 .. note:: When auto-routing is enabled, if you have the route ``home``, it can be also accessd by ``Home``, or maybe by ``hOme``, ``hoMe``, ``HOME``, etc. But the command shows only ``home``.
+
+.. _routing-spark-routes-sort-by-handler:
+
+Sort by Handler
+---------------
+
+.. versionadded:: 4.3.0
+
+You can sort the routes by *Handler*::
+
+    > php spark routes -h