refactor: further rename --handler to --sort-by-handler for routes (#10125)

Author: paulbalandan

system/Commands/Utilities/Routes.php

@@ -73,20 +73,21 @@ class Routes extends BaseCommand
      * @var array<string, string>
      */
     protected $options = [
-        '--handler' => 'Sort by Handler.',
-        '--host'    => 'Specify hostname in request URI.',
+        '--sort-by-handler' => 'Sort by handler.',
+        '--host'            => 'Specify hostname in request URI.',
     ];
 
     /**
      * Displays the help for the spark cli script itself.
      */
     public function run(array $params)
     {
-        $sortByHandler = array_key_exists('handler', $params);
+        $sortByHandler = array_key_exists('sort-by-handler', $params);
 
         if (! $sortByHandler && array_key_exists('h', $params)) {
+            // @todo to remove support in v4.8.0
             // Support -h as a shortcut but print a warning that it is not the intended use of -h.
-            CLI::write('Warning: -h will be used as shortcut for --help in v4.8.0. Please use --handler to sort by handler.', 'yellow');
+            CLI::write('Warning: -h will be used as shortcut for --help in v4.8.0. Please use --sort-by-handler to sort by handler.', 'yellow');
             CLI::newLine();
 
             $sortByHandler = true;

tests/system/Commands/Utilities/RoutesTest.php

@@ -94,7 +94,7 @@ public function testRoutesCommandSortByHandler(): void
     {
         Services::resetSingle('routes');
 
-        command('routes --handler');
+        command('routes --sort-by-handler');
 
         $expected = <<<'EOL'
             +---------+---------+---------------+----------------------------------------+----------------+---------------+
@@ -127,7 +127,7 @@ public function testRoutesCommandSortByHandlerUsingShortcutForBc(): void
         command('routes -h');
 
         $expected = <<<'EOL'
-            Warning: -h will be used as shortcut for --help in v4.8.0. Please use --handler to sort by handler.
+            Warning: -h will be used as shortcut for --help in v4.8.0. Please use --sort-by-handler to sort by handler.
 
             +---------+---------+---------------+----------------------------------------+----------------+---------------+
             | Method  | Route   | Name          | Handler ↓                              | Before Filters | After Filters |
@@ -146,7 +146,10 @@ public function testRoutesCommandSortByHandlerUsingShortcutForBc(): void
             | CLI     | testing | testing-index | \App\Controllers\TestController::index |                |               |
             +---------+---------+---------------+----------------------------------------+----------------+---------------+
             EOL;
-        $this->assertStringContainsString($expected, $this->getBuffer());
+        $this->assertStringContainsString(
+            $expected,
+            (string) preg_replace('/\e\[[^m]+m/u', '', $this->getBuffer()),
+        );
     }
 
     public function testRoutesCommandHostHostname(): void

user_guide_src/source/changelogs/v4.7.3.rst

@@ -24,9 +24,9 @@ Message Changes
 Changes
 *******
 
-- **Commands:** The ``-h`` option for the ``routes`` command is renamed to ``--handler`` to avoid conflict with the common use of ``-h`` as a shortcut for ``--help``.
+- **Commands:** The ``-h`` option for the ``routes`` command is renamed to ``--sort-by-handler`` to avoid conflict with the common use of ``-h`` as a shortcut for ``--help``.
     The old ``-h`` option will continue to work until v4.8.0, at which point it will be removed and repurposed as a shortcut for ``--help``.
-    A warning message is displayed when using the old ``-h`` option to encourage users to switch to the new ``--handler`` option.
+    A warning message is displayed when using the old ``-h`` option to encourage users to switch to the new ``--sort-by-handler`` option.
 
 ************
 Deprecations

user_guide_src/source/incoming/routing.rst

@@ -1001,11 +1001,11 @@ Sort by Handler
 
 .. versionadded:: 4.3.0
 
-You can sort the routes by *Handler*:
+You can sort the routes by *handler*:
 
 .. code-block:: console
 
-    php spark routes -h
+    php spark routes --sort-by-handler
 
 .. _routing-spark-routes-specify-host:
 
@@ -1060,4 +1060,3 @@ Additionally, if we use ``addRedirect()`` we can also expect the ``redirect`` ke
 To access the values of these parameters, we can call ``Router::getMatchedRouteOptions()``. Here is an example of the returned array:
 
 .. literalinclude:: routing/074.php
-