refactor: deprecate BaseCommand and GeneratorTrait

Author: paulbalandan

system/CLI/BaseCommand.php

@@ -29,6 +29,8 @@
  * @property string                $name
  * @property array<string, string> $options
  * @property string                $usage
+ *
+ * @deprecated 4.8.0 Extend `AbstractCommand` instead.
  */
 abstract class BaseCommand
 {

system/CLI/Commands.php

@@ -102,6 +102,14 @@ public function runLegacy(string $command, array $params): int
             return EXIT_ERROR;
         }
 
+        @trigger_error(sprintf(
+            'Since v4.8.0, "%s" is deprecated. Command "%s" (%s) should extend "%s" instead.',
+            BaseCommand::class,
+            $command,
+            $this->commands[$command]['class'],
+            AbstractCommand::class,
+        ), E_USER_DEPRECATED);
+
         Events::trigger('pre_command');
 
         $exitCode = $this->getCommand($command, legacy: true)->run($params);

system/CLI/GeneratorTrait.php

@@ -19,6 +19,8 @@
 /**
  * GeneratorTrait contains a collection of methods
  * to build the commands that generates a file.
+ *
+ * @deprecated 4.8.0 Extend `AbstractGeneratorCommand` instead.
  */
 trait GeneratorTrait
 {

tests/system/CLI/BaseCommandTest.php

@@ -41,6 +41,13 @@ protected function resetCli(): void
         CLI::reset();
     }
 
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+
+        service('superglobals')->setServer('CODEIGNITER_SCREAM_DEPRECATIONS', '1');
+    }
+
     public function testRunCommand(): void
     {
         $command = new AppInfo(single_service('logger'), single_service('commands'));
@@ -54,6 +61,8 @@ public function testRunCommand(): void
 
     public function testCallingOtherCommands(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         $command = new AppInfo(single_service('logger'), single_service('commands'));
 
         $this->assertSame(0, $command->helpMe());

tests/system/CLI/CommandsTest.php

@@ -63,6 +63,8 @@ protected function resetAll(): void
     {
         $this->resetServices();
 
+        service('superglobals')->setServer('CODEIGNITER_SCREAM_DEPRECATIONS', '1');
+
         CLI::reset();
     }
 
@@ -220,6 +222,8 @@ public function testRunOnAbstractLegacyCommandCannotBeRun(): void
 
     public function testRunOnKnownLegacyCommand(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         $commands = new Commands();
 
         $this->assertSame(EXIT_SUCCESS, $commands->runLegacy('app:info', []));
@@ -242,12 +246,20 @@ public function testRunOnKnownModernCommand(): void
         );
     }
 
-    public function testRunOnLegacyCommandReturningNullIsDeprecated(): void
+    public function testRunOnLegacyCommandIsDeprecated(): void
     {
         $this->expectException(ErrorException::class);
-        $this->expectExceptionMessage('Since v4.8.0, commands must return an integer exit code. Last command "null:return" exited with null. Defaulting to EXIT_SUCCESS.');
+        $this->expectExceptionMessage('Since v4.8.0, "CodeIgniter\\CLI\\BaseCommand" is deprecated. Command "app:info" (Tests\\Support\\Commands\\Legacy\\AppInfo) should extend "CodeIgniter\\CLI\\AbstractCommand" instead.');
 
-        (new Commands())->runLegacy('null:return', []);
+        (new Commands())->runLegacy('app:info', []);
+    }
+
+    public function testRunOnLegacyCommandReturningNullIsDeprecated(): void
+    {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
+        $this->assertSame(EXIT_SUCCESS, (new Commands())->runLegacy('null:return', []));
+        $this->assertLogContains('warning', '[DEPRECATED] Since v4.8.0, commands must return an integer exit code. Last command "null:return" exited with null. Defaulting to EXIT_SUCCESS.');
     }
 
     public function testRunMethodIsDeprecatedInFavorOfRunLegacy(): void
@@ -503,6 +515,8 @@ public function testAliasClashingWithAnotherAliasFailsHard(): void
 
     public function testDestructiveCommandIsNotRisky(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         $this->expectException(RuntimeException::class);
 
         command('app:destructive');
@@ -699,6 +713,8 @@ public function testGetCommandAlternativesThrowsDeprecationWhenCommandsArrayIsPa
 
     public function testDiscoveredLegacyCommandsCanBeOverridden(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         $this->injectFixtureLocator([
             AppInfoOverride::class => $this->loadOverrideFixture('AppInfo.php'),
             AppInfo::class         => SUPPORTPATH . 'Commands/Legacy/AppInfo.php',

tests/system/CLI/ConsoleTest.php

@@ -53,6 +53,8 @@ protected function tearDown(): void
     {
         parent::tearDown();
 
+        service('superglobals')->setServer('CODEIGNITER_SCREAM_DEPRECATIONS', '1');
+
         CLI::reset();
     }
 
@@ -144,6 +146,8 @@ public function testBadCommand(): void
 
     public function testUnknownCommandRunsConfirmedSuggestion(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         $this->initializeConsole('app:inf', '--no-header');
         $io = $this->useInputs('y');
 
@@ -346,6 +350,8 @@ public function testHelpArgumentAndHelpOptionCombined(): void
 
     public function testRunRoutesDiscoveredLegacyCommandThroughRunLegacy(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         // `app:info` is a legacy BaseCommand fixture. Console must take the
         // legacy branch of run() and delegate to Commands::runLegacy().
         $this->initializeConsole('app:info');

tests/system/Commands/ConfigurableSortImportsTest.php

@@ -25,6 +25,20 @@ final class ConfigurableSortImportsTest extends CIUnitTestCase
 {
     use StreamFilterTrait;
 
+    public static function setUpBeforeClass(): void
+    {
+        parent::setUpBeforeClass();
+
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+    }
+
+    public static function tearDownAfterClass(): void
+    {
+        parent::tearDownAfterClass();
+
+        service('superglobals')->setServer('CODEIGNITER_SCREAM_DEPRECATIONS', '1');
+    }
+
     public function testPublishLanguageWithoutOptions(): void
     {
         command('publish:language');

tests/system/Commands/Generators/GeneratorsTest.php

@@ -25,6 +25,13 @@ final class GeneratorsTest extends CIUnitTestCase
 {
     use StreamFilterTrait;
 
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+
+        service('superglobals')->setServer('CODEIGNITER_SCREAM_DEPRECATIONS', '1');
+    }
+
     public function testGenerateFileCreated(): void
     {
         command('make:seeder categories');
@@ -98,6 +105,8 @@ public function testGenerateFileInSubfolders(): void
 
     public function testSuffixingHasNoEffect(): void
     {
+        service('superglobals')->unsetServer('CODEIGNITER_SCREAM_DEPRECATIONS');
+
         command('make:foo bar --suffix');
         $file1 = APPPATH . 'Commands/Bar.php';
         $file2 = APPPATH . 'Commands/BarCommand.php';

user_guide_src/source/changelogs/v4.8.0.rst

@@ -431,6 +431,8 @@ Deprecations
 - **CLI:** Returning a non-integer exit code from a command is now deprecated and will trigger a deprecation notice. Command methods should return an integer exit code (e.g., ``0`` for success, non-zero for errors) to ensure proper behavior across all platforms.
 - **CLI:** ``Commands::run()`` is now deprecated in favor of ``Commands::runLegacy()`` for legacy ``BaseCommand`` commands, and ``Commands::runCommand()`` for modern ``AbstractCommand`` commands.
 - **CLI:** The ``$commands`` parameter of ``Commands::verifyCommand()`` and the ``$collection`` parameter of ``Commands::getCommandAlternatives()`` are no longer used. Passing a non-empty array for either will trigger a deprecation notice.
+- **CLI:** ``BaseCommand`` is now deprecated in favor of ``AbstractCommand``. Running a command that extends it triggers a deprecation notice. See :doc:`../cli/cli_modern_commands`.
+- **CLI:** ``GeneratorTrait`` is now deprecated in favor of ``AbstractGeneratorCommand``. See :doc:`../cli/cli_modern_generators`.
 - **CLI:** The ``CLI.generator.viewName.cell`` language string is deprecated. It was never displayed, since ``make:cell`` only prompts for the class name.
 - **HTTP:** The ``CLIRequest::parseCommand()`` method is now deprecated and will be removed in a future release. The ``CLIRequest`` class now uses the new ``CommandLineParser`` class to handle command-line argument parsing.
 - **HTTP:** ``URI::setSilent()`` is now hard deprecated. This method was only previously marked as deprecated. It will now trigger a deprecation notice when used.

user_guide_src/source/cli/cli_commands.rst

@@ -8,6 +8,12 @@ need to have routes defined for, making them perfect for building tools that dev
 their jobs simpler, whether by handling migrations or database seeding, checking cronjob status, or even
 building out custom code generators for your company.
 
+.. deprecated:: 4.8.0
+
+    ``BaseCommand`` is deprecated, and running a command that extends it triggers a
+    deprecation notice. Write new commands against ``AbstractCommand`` instead.
+    See :doc:`cli_modern_commands`.
+
 .. contents::
     :local:
     :depth: 2