refactor: rename -h option of routes command as --handler (#10113)

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

@@ -56,7 +56,7 @@ private function getCleanRoutes(): RouteCollection
 
     public function testRoutesCommand(): void
     {
-        Services::injectMock('routes', null);
+        Services::resetSingle('routes');
 
         command('routes');
 
@@ -92,11 +92,43 @@ public function testRoutesCommand(): void
 
     public function testRoutesCommandSortByHandler(): void
     {
-        Services::injectMock('routes', null);
+        Services::resetSingle('routes');
+
+        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::resetSingle('routes');
 
         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 |
             +---------+---------+---------------+----------------------------------------+----------------+---------------+
@@ -119,7 +151,7 @@ public function testRoutesCommandSortByHandler(): void
 
     public function testRoutesCommandHostHostname(): void
     {
-        Services::injectMock('routes', null);
+        Services::resetSingle('routes');
 
         command('routes --host blog.example.com');
 
@@ -148,7 +180,7 @@ public function testRoutesCommandHostHostname(): void
 
     public function testRoutesCommandHostSubdomain(): void
     {
-        Services::injectMock('routes', null);
+        Services::resetSingle('routes');
 
         command('routes --host sub.example.com');
 
@@ -181,8 +213,7 @@ public function testRoutesCommandAutoRouteImproved(): void
 
         $routes->setAutoRoute(true);
         config('Feature')->autoRoutesImproved = true;
-        $namespace                            = 'Tests\Support\Controllers';
-        $routes->setDefaultNamespace($namespace);
+        $routes->setDefaultNamespace('Tests\Support\Controllers');
 
         command('routes');
 
@@ -214,7 +245,8 @@ public function testRoutesCommandRouteLegacy(): void
         $routes = $this->getCleanRoutes();
         $routes->loadRoutes();
 
-        $featureConfig                     = config(Feature::class);
+        $featureConfig = config(Feature::class);
+
         $featureConfig->autoRoutesImproved = false;
         $routes->setAutoRoute(true);
 

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
 ************

utils/phpstan-baseline/argument.type.neon

@@ -1,4 +1,4 @@
-# total 82 errors
+# total 78 errors
 
 parameters:
     ignoreErrors:
@@ -47,11 +47,6 @@ parameters:
             count: 1
             path: ../../tests/system/CodeIgniterTest.php
 
-        -
-            message: '#^Parameter \#2 \$mock of static method CodeIgniter\\Config\\BaseService\:\:injectMock\(\) expects object, null given\.$#'
-            count: 4
-            path: ../../tests/system/Commands/Utilities/RoutesTest.php
-
         -
             message: '#^Parameter \#1 \$expected of method PHPUnit\\Framework\\Assert\:\:assertInstanceOf\(\) expects class\-string\<Config\\TestRegistrar\>, string given\.$#'
             count: 1

utils/phpstan-baseline/loader.neon

@@ -1,4 +1,4 @@
-# total 2059 errors
+# total 2055 errors
 
 includes:
     - argument.type.neon