refactor: commands - move the null exit code deprecation earlier (#10112)

paulbalandan · web-flow · commit 427fac0661c5 · 2026-04-13T21:01:03.000+08:00
* refactor: commands - move the null exit code deprecation earlier

* add fixes

* code review fixes
diff --git a/system/Boot.php b/system/Boot.php
@@ -428,17 +428,6 @@ protected static function initializeConsole(): Console
 
     protected static function runCommand(Console $console): int
     {
-        $exitCode = $console->initialize()->run();
-
-        if (! is_int($exitCode)) {
-            @trigger_error(sprintf(
-                'Since v4.8.0, commands must return an integer exit code. Last command "%s" exited with %s. Defaulting to EXIT_SUCCESS.',
-                $console->getCommand(),
-                get_debug_type($exitCode),
-            ), E_USER_DEPRECATED);
-            $exitCode = EXIT_SUCCESS;
-        }
-
-        return $exitCode;
+        return $console->initialize()->run();
     }
 }
diff --git a/system/CLI/BaseCommand.php b/system/CLI/BaseCommand.php
@@ -101,7 +101,7 @@ public function __construct(LoggerInterface $logger, Commands $commands)
      *
      * @param array<int|string, string|null> $params
      *
-     * @return int|void
+     * @return int|null
      */
     abstract public function run(array $params);
 
@@ -110,7 +110,7 @@ abstract public function run(array $params);
      *
      * @param array<int|string, string|null> $params
      *
-     * @return int|void
+     * @return int|null
      *
      * @throws ReflectionException
      */
diff --git a/system/CLI/Commands.php b/system/CLI/Commands.php
@@ -69,11 +69,20 @@ public function run(string $command, array $params)
 
         Events::trigger('pre_command');
 
-        $exit = $class->run($params);
+        $exitCode = $class->run($params);
 
         Events::trigger('post_command');
 
-        return $exit;
+        if (! is_int($exitCode)) {
+            @trigger_error(sprintf(
+                'Since v4.8.0, commands must return an integer exit code. Last command "%s" exited with %s. Defaulting to EXIT_SUCCESS.',
+                $command,
+                get_debug_type($exitCode),
+            ), E_USER_DEPRECATED);
+            $exitCode = EXIT_SUCCESS;
+        }
+
+        return $exitCode;
     }
 
     /**
diff --git a/system/CLI/Console.php b/system/CLI/Console.php
@@ -39,7 +39,7 @@ class Console
      *
      * @param list<string> $tokens
      *
-     * @return int|null Exit code or null for legacy commands that don't return an exit code.
+     * @return int Exit code
      */
     public function run(array $tokens = [])
     {
diff --git a/system/Commands/Cache/InfoCache.php b/system/Commands/Cache/InfoCache.php
@@ -63,7 +63,7 @@ public function run(array $params)
         if ($config->handler !== 'file') {
             CLI::error('This command only supports the file cache handler.');
 
-            return;
+            return EXIT_ERROR;
         }
 
         $cache  = CacheFactory::getHandler($config);
@@ -87,5 +87,7 @@ public function run(array $params)
         ];
 
         CLI::table($tbody, $thead);
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Database/CreateDatabase.php b/system/Commands/Database/CreateDatabase.php
@@ -115,7 +115,7 @@ public function run(array $params)
                         CLI::error("Database \"{$dbName}\" already exists.", 'light_gray', 'red');
                         CLI::newLine();
 
-                        return;
+                        return EXIT_ERROR;
                     }
 
                     unset($dbName);
@@ -130,22 +130,26 @@ public function run(array $params)
                     CLI::error('Database creation failed.', 'light_gray', 'red');
                     CLI::newLine();
 
-                    return;
+                    return EXIT_ERROR;
                     // @codeCoverageIgnoreEnd
                 }
             } elseif (! Database::forge()->createDatabase($name)) {
                 // @codeCoverageIgnoreStart
                 CLI::error('Database creation failed.', 'light_gray', 'red');
                 CLI::newLine();
 
-                return;
+                return EXIT_ERROR;
                 // @codeCoverageIgnoreEnd
             }
 
             CLI::write("Database \"{$name}\" successfully created.", 'green');
             CLI::newLine();
+
+            return EXIT_SUCCESS;
         } catch (Throwable $e) {
             $this->showError($e);
+
+            return EXIT_ERROR;
         } finally {
             Factories::reset('config');
             Database::connect(null, false);
diff --git a/system/Commands/Database/Migrate.php b/system/Commands/Database/Migrate.php
@@ -99,9 +99,12 @@ public function run(array $params)
 
             CLI::write(lang('Migrations.migrated'), 'green');
 
+            return EXIT_SUCCESS;
             // @codeCoverageIgnoreStart
         } catch (Throwable $e) {
             $this->showError($e);
+
+            return EXIT_ERROR;
             // @codeCoverageIgnoreEnd
         }
     }
diff --git a/system/Commands/Database/MigrateRefresh.php b/system/Commands/Database/MigrateRefresh.php
@@ -79,16 +79,15 @@ public function run(array $params)
             $force = array_key_exists('f', $params) || CLI::getOption('f');
 
             if (! $force && CLI::prompt(lang('Migrations.refreshConfirm'), ['y', 'n']) === 'n') {
-                return;
+                return EXIT_ERROR;
             }
 
             $params['f'] = null;
             // @codeCoverageIgnoreEnd
         }
 
-        $this->withSignalsBlocked(function () use ($params): void {
-            $this->call('migrate:rollback', $params);
-            $this->call('migrate', $params);
-        });
+        return $this->withSignalsBlocked(
+            fn (): int => $this->call('migrate:rollback', $params) | $this->call('migrate', $params),
+        );
     }
 }
diff --git a/system/Commands/Database/MigrateRollback.php b/system/Commands/Database/MigrateRollback.php
@@ -77,7 +77,7 @@ public function run(array $params)
             $force = array_key_exists('f', $params) || CLI::getOption('f');
 
             if (! $force && CLI::prompt(lang('Migrations.rollBackConfirm'), ['y', 'n']) === 'n') {
-                return null;
+                return EXIT_ERROR;
             }
             // @codeCoverageIgnoreEnd
         }
@@ -101,12 +101,20 @@ public function run(array $params)
 
             CLI::write(lang('Migrations.rollingBack') . ' ' . $batch, 'yellow');
 
-            $this->withSignalsBlocked(static function () use ($runner, $batch): void {
+            $exit = $this->withSignalsBlocked(static function () use ($runner, $batch): int {
                 if (! $runner->regress($batch)) {
                     CLI::error(lang('Migrations.generalFault'), 'light_gray', 'red'); // @codeCoverageIgnore
+
+                    return EXIT_ERROR;
                 }
+
+                return EXIT_SUCCESS;
             });
 
+            if ($exit !== EXIT_SUCCESS) {
+                return $exit;
+            }
+
             $messages = $runner->getCliMessages();
 
             foreach ($messages as $message) {
@@ -115,12 +123,13 @@ public function run(array $params)
 
             CLI::write('Done rolling back migrations.', 'green');
 
+            return EXIT_SUCCESS;
             // @codeCoverageIgnoreStart
         } catch (Throwable $e) {
             $this->showError($e);
+
+            return EXIT_ERROR;
             // @codeCoverageIgnoreEnd
         }
-
-        return null;
     }
 }
diff --git a/system/Commands/Database/MigrateStatus.php b/system/Commands/Database/MigrateStatus.php
@@ -150,7 +150,7 @@ public function run(array $params)
             CLI::error(lang('Migrations.noneFound'), 'light_gray', 'red');
             CLI::newLine();
 
-            return;
+            return EXIT_ERROR;
             // @codeCoverageIgnoreEnd
         }
 
@@ -164,5 +164,7 @@ public function run(array $params)
         ];
 
         CLI::table($status, $headers);
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Database/Seed.php b/system/Commands/Database/Seed.php
@@ -77,8 +77,12 @@ public function run(array $params)
 
         try {
             $seeder->call($seedName);
+
+            return EXIT_SUCCESS;
         } catch (Throwable $e) {
             $this->showError($e);
+
+            return EXIT_ERROR;
         }
     }
 }
diff --git a/system/Commands/Encryption/GenerateKey.php b/system/Commands/Encryption/GenerateKey.php
@@ -89,14 +89,14 @@ public function run(array $params)
             CLI::write($encodedKey, 'yellow');
             CLI::newLine();
 
-            return;
+            return EXIT_SUCCESS;
         }
 
         if (! $this->setNewEncryptionKey($encodedKey, $params)) {
             CLI::write('Error in setting new encryption key to .env file.', 'light_gray', 'red');
             CLI::newLine();
 
-            return;
+            return EXIT_ERROR;
         }
 
         // force DotEnv to reload the new env vars
@@ -107,6 +107,8 @@ public function run(array $params)
 
         CLI::write('Application\'s new encryption key was successfully set.', 'green');
         CLI::newLine();
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/CellGenerator.php b/system/Commands/Generators/CellGenerator.php
@@ -102,6 +102,6 @@ public function run(array $params)
 
         $this->generateView($namespace . $viewName, $params);
 
-        return 0;
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Generators/CommandGenerator.php b/system/Commands/Generators/CommandGenerator.php
@@ -86,6 +86,8 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.command';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/ConfigGenerator.php b/system/Commands/Generators/ConfigGenerator.php
@@ -82,6 +82,8 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.config';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/ControllerGenerator.php b/system/Commands/Generators/ControllerGenerator.php
@@ -88,6 +88,8 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.controller';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/EntityGenerator.php b/system/Commands/Generators/EntityGenerator.php
@@ -82,5 +82,7 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.entity';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Generators/FilterGenerator.php b/system/Commands/Generators/FilterGenerator.php
@@ -82,5 +82,7 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.filter';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Generators/MigrationGenerator.php b/system/Commands/Generators/MigrationGenerator.php
@@ -93,6 +93,8 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.migration';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/ModelGenerator.php b/system/Commands/Generators/ModelGenerator.php
@@ -86,6 +86,8 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.model';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/ScaffoldGenerator.php b/system/Commands/Generators/ScaffoldGenerator.php
@@ -115,9 +115,13 @@ public function run(array $params)
         $class = $params[0] ?? CLI::getSegment(2);
 
         // Call those commands!
-        $this->call('make:controller', array_merge([$class], $controllerOpts, $options));
-        $this->call('make:model', array_merge([$class], $modelOpts, $options));
-        $this->call('make:migration', array_merge([$class], $options));
-        $this->call('make:seeder', array_merge([$class], $options));
+        $exit1 = $this->call('make:controller', array_merge([$class], $controllerOpts, $options));
+        $exit2 = $this->call('make:model', array_merge([$class], $modelOpts, $options));
+        $exit3 = $this->call('make:migration', array_merge([$class], $options));
+        $exit4 = $this->call('make:seeder', array_merge([$class], $options));
+
+        assert(is_int($exit1) && is_int($exit2) && is_int($exit3) && is_int($exit4));
+
+        return $exit1 | $exit2 | $exit3 | $exit4;
     }
 }
diff --git a/system/Commands/Generators/SeederGenerator.php b/system/Commands/Generators/SeederGenerator.php
@@ -82,5 +82,7 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.seeder';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Generators/TestGenerator.php b/system/Commands/Generators/TestGenerator.php
@@ -89,6 +89,8 @@ public function run(array $params)
         $autoload->addNamespace('Tests', ROOTPATH . 'tests');
 
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/TransformerGenerator.php b/system/Commands/Generators/TransformerGenerator.php
@@ -82,6 +82,8 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.transformer';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 
     /**
diff --git a/system/Commands/Generators/ValidationGenerator.php b/system/Commands/Generators/ValidationGenerator.php
@@ -82,5 +82,7 @@ public function run(array $params)
 
         $this->classNameLang = 'CLI.generator.className.validation';
         $this->generateClass($params);
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Generators/Views/command.tpl.php b/system/Commands/Generators/Views/command.tpl.php
@@ -68,9 +68,11 @@ public function run(array $params)
         $this->directory = 'Commands';
         $this->template  = 'command.tpl.php';
 
-        $this->execute($params);
+        $this->generateClass($params);
 <?php else: ?>
-        //
+        // your command logic here
 <?php endif ?>
+
+        return EXIT_SUCCESS;
     }
 }
diff --git a/system/Commands/Help.php b/system/Commands/Help.php
diff --git a/system/Commands/Server/Serve.php b/system/Commands/Server/Serve.php
diff --git a/system/Commands/Utilities/Environment.php b/system/Commands/Utilities/Environment.php
diff --git a/system/Commands/Utilities/Namespaces.php b/system/Commands/Utilities/Namespaces.php
diff --git a/system/Commands/Utilities/Publish.php b/system/Commands/Utilities/Publish.php
diff --git a/system/Commands/Utilities/Routes.php b/system/Commands/Utilities/Routes.php
diff --git a/tests/_support/Commands/AppInfo.php b/tests/_support/Commands/AppInfo.php
diff --git a/tests/_support/Commands/InvalidCommand.php b/tests/_support/Commands/InvalidCommand.php
diff --git a/tests/_support/Commands/LanguageCommand.php b/tests/_support/Commands/LanguageCommand.php
diff --git a/tests/_support/Commands/Unsuffixable.php b/tests/_support/Commands/Unsuffixable.php

Original file line number	Diff line number	Diff line change
`@@ -428,17 +428,6 @@ protected static function initializeConsole(): Console`
`428`	`428`
`429`	`429`	`protected static function runCommand(Console $console): int`
`430`	`430`	`{`
`431`		`- $exitCode = $console->initialize()->run();`
`432`		`-`
`433`		`- if (! is_int($exitCode)) {`
`434`		`- @trigger_error(sprintf(`
`435`		`- 'Since v4.8.0, commands must return an integer exit code. Last command "%s" exited with %s. Defaulting to EXIT_SUCCESS.',`
`436`		`- $console->getCommand(),`
`437`		`- get_debug_type($exitCode),`
`438`		`- ), E_USER_DEPRECATED);`
`439`		`- $exitCode = EXIT_SUCCESS;`
`440`		`- }`
`441`		`-`
`442`		`- return $exitCode;`
	`431`	`+ return $console->initialize()->run();`
`443`	`432`	`}`
`444`	`433`	`}`
Original file line number	Diff line number	Diff line change
`@@ -101,7 +101,7 @@ public function __construct(LoggerInterface $logger, Commands $commands)`
`101`	`101`	`*`
`102`	`102`	`* @param array<int\|string, string\|null> $params`
`103`	`103`	`*`
`104`		`- * @return int\|void`
	`104`	`+ * @return int\|null`
`105`	`105`	`*/`
`106`	`106`	`abstract public function run(array $params);`
`107`	`107`
`@@ -110,7 +110,7 @@ abstract public function run(array $params);`
`110`	`110`	`*`
`111`	`111`	`* @param array<int\|string, string\|null> $params`
`112`	`112`	`*`
`113`		`- * @return int\|void`
	`113`	`+ * @return int\|null`
`114`	`114`	`*`
`115`	`115`	`* @throws ReflectionException`
`116`	`116`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@ class Console`
`39`	`39`	`*`
`40`	`40`	`* @param list<string> $tokens`
`41`	`41`	`*`
`42`		`- * @return int\|null Exit code or null for legacy commands that don't return an exit code.`
	`42`	`+ * @return int Exit code`
`43`	`43`	`*/`
`44`	`44`	`public function run(array $tokens = [])`
`45`	`45`	`{`
Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ public function run(array $params)`
`63`	`63`	`if ($config->handler !== 'file') {`
`64`	`64`	`CLI::error('This command only supports the file cache handler.');`
`65`	`65`
`66`		`- return;`
	`66`	`+ return EXIT_ERROR;`
`67`	`67`	`}`
`68`	`68`
`69`	`69`	`$cache = CacheFactory::getHandler($config);`
`@@ -87,5 +87,7 @@ public function run(array $params)`
`87`	`87`	`];`
`88`	`88`
`89`	`89`	`CLI::table($tbody, $thead);`
	`90`	`+`
	`91`	`+ return EXIT_SUCCESS;`
`90`	`92`	`}`
`91`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -99,9 +99,12 @@ public function run(array $params)`
`99`	`99`
`100`	`100`	`CLI::write(lang('Migrations.migrated'), 'green');`
`101`	`101`
	`102`	`+ return EXIT_SUCCESS;`
`102`	`103`	`// @codeCoverageIgnoreStart`
`103`	`104`	`} catch (Throwable $e) {`
`104`	`105`	`$this->showError($e);`
	`106`	`+`
	`107`	`+ return EXIT_ERROR;`
`105`	`108`	`// @codeCoverageIgnoreEnd`
`106`	`109`	`}`
`107`	`110`	`}`
Original file line number	Diff line number	Diff line change
`@@ -79,16 +79,15 @@ public function run(array $params)`
`79`	`79`	`$force = array_key_exists('f', $params) \|\| CLI::getOption('f');`
`80`	`80`
`81`	`81`	`if (! $force && CLI::prompt(lang('Migrations.refreshConfirm'), ['y', 'n']) === 'n') {`
`82`		`- return;`
	`82`	`+ return EXIT_ERROR;`
`83`	`83`	`}`
`84`	`84`
`85`	`85`	`$params['f'] = null;`
`86`	`86`	`// @codeCoverageIgnoreEnd`
`87`	`87`	`}`
`88`	`88`
`89`		`- $this->withSignalsBlocked(function () use ($params): void {`
`90`		`- $this->call('migrate:rollback', $params);`
`91`		`- $this->call('migrate', $params);`
`92`		`- });`
	`89`	`+ return $this->withSignalsBlocked(`
	`90`	`+ fn (): int => $this->call('migrate:rollback', $params) \| $this->call('migrate', $params),`
	`91`	`+ );`
`93`	`92`	`}`
`94`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -150,7 +150,7 @@ public function run(array $params)`
`150`	`150`	`CLI::error(lang('Migrations.noneFound'), 'light_gray', 'red');`
`151`	`151`	`CLI::newLine();`
`152`	`152`
`153`		`- return;`
	`153`	`+ return EXIT_ERROR;`
`154`	`154`	`// @codeCoverageIgnoreEnd`
`155`	`155`	`}`
`156`	`156`
`@@ -164,5 +164,7 @@ public function run(array $params)`
`164`	`164`	`];`
`165`	`165`
`166`	`166`	`CLI::table($status, $headers);`
	`167`	`+`
	`168`	`+ return EXIT_SUCCESS;`
`167`	`169`	`}`
`168`	`170`	`}`