refactor: rename -h option of routes command as --handler

Author: paulbalandan

system/Commands/Utilities/Routes.php

@@ -73,17 +73,26 @@ class Routes extends BaseCommand
      * @var array<string, string>
      */
     protected $options = [
-        '-h'     => 'Sort by Handler.',
-        '--host' => 'Specify hostname in request URI.',
+        '--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('h', $params);
-        $host          = $params['host'] ?? null;
+        $sortByHandler = array_key_exists('handler', $params);
+
+        if (! $sortByHandler && array_key_exists('h', $params)) {
+            // 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::newLine();
+
+            $sortByHandler = true;
+        }
+
+        $host = $params['host'] ?? null;
 
         // Set HTTP_HOST
         if ($host !== null) {

tests/system/Commands/Utilities/RoutesTest.php

@@ -94,9 +94,41 @@ public function testRoutesCommandSortByHandler(): void
     {
         Services::injectMock('routes', null);
 
+        command('routes --handler');
+
+        $expected = <<<'EOL'
+            +---------+---------+---------------+----------------------------------------+----------------+---------------+
+            | Method  | Route   | Name          | Handler ↓                              | Before Filters | After Filters |
+            +---------+---------+---------------+----------------------------------------+----------------+---------------+
+            | GET     | closure | »             | (Closure)                              |                |               |
+            | GET     | /       | »             | \App\Controllers\Home::index           |                |               |
+            | GET     | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | HEAD    | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | POST    | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | PATCH   | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | PUT     | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | DELETE  | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | OPTIONS | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | TRACE   | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | CONNECT | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            | CLI     | testing | testing-index | \App\Controllers\TestController::index |                |               |
+            +---------+---------+---------------+----------------------------------------+----------------+---------------+
+            EOL;
+        $this->assertStringContainsString($expected, $this->getBuffer());
+    }
+
+    /**
+     * @todo To remove this test and the backward compatibility for -h in v4.8.0.
+     */
+    public function testRoutesCommandSortByHandlerUsingShortcutForBc(): void
+    {
+        Services::injectMock('routes', null);
+
         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.
+
             +---------+---------+---------------+----------------------------------------+----------------+---------------+
             | Method  | Route   | Name          | Handler ↓                              | Before Filters | After Filters |
             +---------+---------+---------------+----------------------------------------+----------------+---------------+

user_guide_src/source/changelogs/v4.7.3.rst

@@ -24,6 +24,10 @@ 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``.
+    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.
+
 ************
 Deprecations
 ************