symfony · chalasr · Jun 11, 2025 · Jun 9, 2025
diff --git a/UPGRADE-7.4.md b/UPGRADE-7.4.md
@@ -8,6 +8,16 @@ Read more about this in the [Symfony documentation](https://symfony.com/doc/7.4/
 
 If you're upgrading from a version below 7.3, follow the [7.3 upgrade guide](UPGRADE-7.3.md) first.
 
+Console
+-------
+
+ * Deprecate `Symfony\Component\Console\Application::add()` in favor of `Symfony\Component\Console\Application::addCommand()`
+
+FrameworkBundle
+---------------
+
+ * Deprecate `Symfony\Bundle\FrameworkBundle\Console\Application::add()` in favor of `Symfony\Bundle\FrameworkBundle\Console\Application::addCommand()`
+
 HttpClient
 ----------
 

diff --git a/src/Symfony/Bridge/Twig/Tests/Command/DebugCommandTest.php b/src/Symfony/Bridge/Twig/Tests/Command/DebugCommandTest.php
@@ -304,7 +304,12 @@ public function testComplete(array $input, array $expectedSuggestions)
         $environment = new Environment($loader);
 
         $application = new Application();
-        $application->add(new DebugCommand($environment, $projectDir, [], null, null));
+        $command = new DebugCommand($environment, $projectDir, [], null, null);
+        if (method_exists($application, 'addCommand')) {
+            $application->addCommand($command);
+        } else {
+            $application->add($command);
+        }
 
         $tester = new CommandCompletionTester($application->find('debug:twig'));
         $suggestions = $tester->complete($input, 2);
@@ -339,7 +344,12 @@ private function createCommandTester(array $paths = [], array $bundleMetadata =
         }
 
         $application = new Application();
-        $application->add(new DebugCommand($environment, $projectDir, $bundleMetadata, $defaultPath, null));
+        $command = new DebugCommand($environment, $projectDir, $bundleMetadata, $defaultPath, null);
+        if (method_exists($application, 'addCommand')) {
+            $application->addCommand($command);
+        } else {
+            $application->add($command);
+        }
         $command = $application->find('debug:twig');
 
         return new CommandTester($command);

diff --git a/src/Symfony/Bridge/Twig/Tests/Command/LintCommandTest.php b/src/Symfony/Bridge/Twig/Tests/Command/LintCommandTest.php
@@ -179,7 +179,11 @@ private function createCommand(): Command
         $command = new LintCommand($environment);
 
         $application = new Application();
-        $application->add($command);
+        if (method_exists($application, 'addCommand')) {
+            $application->addCommand($command);
+        } else {
+            $application->add($command);
+        }
 
         return $application->find('lint:twig');
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md b/src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Deprecate `Symfony\Bundle\FrameworkBundle\Console\Application::add()` in favor of `Symfony\Bundle\FrameworkBundle\Console\Application::addCommand()`
+
 7.3
 ---
 

diff --git a/src/Symfony/Bundle/FrameworkBundle/Console/Application.php b/src/Symfony/Bundle/FrameworkBundle/Console/Application.php
@@ -159,11 +159,29 @@ public function getLongVersion(): string
         return parent::getLongVersion().\sprintf(' (env: <comment>%s</>, debug: <comment>%s</>)', $this->kernel->getEnvironment(), $this->kernel->isDebug() ? 'true' : 'false');
     }
 
+    /**
+     * @deprecated since Symfony 7.4, use Application::addCommand() instead
+     */
     public function add(Command $command): ?Command
+    {
+        trigger_deprecation('symfony/framework-bundle', '7.4', 'The "%s()" method is deprecated and will be removed in Symfony 8.0, use "%s::addCommand()" instead.', __METHOD__, self::class);
+
+        return $this->addCommand($command);
+    }
+
+    public function addCommand(callable|Command $command): ?Command
     {
         $this->registerCommands();
 
-        return parent::add($command);
+        if (!method_exists(BaseApplication::class, 'addCommand')) {
+            if (!$command instanceof Command) {
+                throw new \LogicException('Using callables as commands requires symfony/console 7.4 or higher.');
+            }
+
+            return parent::add($command);
+        }
+
+        return parent::addCommand($command);
     }
 
     protected function registerCommands(): void
@@ -197,7 +215,7 @@ protected function registerCommands(): void
             foreach ($container->getParameter('console.command.ids') as $id) {
                 if (!isset($lazyCommandIds[$id])) {
                     try {
-                        $this->add($container->get($id));
+                        $this->addCommand($container->get($id));
                     } catch (\Throwable $e) {
                         $this->registrationErrors[] = $e;
                     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/AboutCommand/AboutCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/AboutCommand/AboutCommandTest.php
@@ -82,7 +82,7 @@ public function testAboutWithUnreadableFiles()
     private function createCommandTester(TestAppKernel $kernel): CommandTester
     {
         $application = new Application($kernel);
-        $application->add(new AboutCommand());
+        $application->addCommand(new AboutCommand());
 
         return new CommandTester($application->find('about'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/CachePoolClearCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/CachePoolClearCommandTest.php
@@ -36,7 +36,7 @@ protected function setUp(): void
     public function testComplete(array $input, array $expectedSuggestions)
     {
         $application = new Application($this->getKernel());
-        $application->add(new CachePoolClearCommand(new Psr6CacheClearer(['foo' => $this->cachePool]), ['foo']));
+        $application->addCommand(new CachePoolClearCommand(new Psr6CacheClearer(['foo' => $this->cachePool]), ['foo']));
         $tester = new CommandCompletionTester($application->get('cache:pool:clear'));
 
         $suggestions = $tester->complete($input);

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/CachePoolDeleteCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/CachePoolDeleteCommandTest.php
@@ -90,7 +90,7 @@ public function testCommandDeleteFailed()
     public function testComplete(array $input, array $expectedSuggestions)
     {
         $application = new Application($this->getKernel());
-        $application->add(new CachePoolDeleteCommand(new Psr6CacheClearer(['foo' => $this->cachePool]), ['foo']));
+        $application->addCommand(new CachePoolDeleteCommand(new Psr6CacheClearer(['foo' => $this->cachePool]), ['foo']));
         $tester = new CommandCompletionTester($application->get('cache:pool:delete'));
 
         $suggestions = $tester->complete($input);
@@ -125,7 +125,7 @@ private function getKernel(): MockObject&KernelInterface
     private function getCommandTester(KernelInterface $kernel): CommandTester
     {
         $application = new Application($kernel);
-        $application->add(new CachePoolDeleteCommand(new Psr6CacheClearer(['foo' => $this->cachePool])));
+        $application->addCommand(new CachePoolDeleteCommand(new Psr6CacheClearer(['foo' => $this->cachePool])));
 
         return new CommandTester($application->find('cache:pool:delete'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/CachePruneCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/CachePruneCommandTest.php
@@ -77,7 +77,7 @@ private function getPruneableInterfaceMock(): MockObject&PruneableInterface
     private function getCommandTester(KernelInterface $kernel, RewindableGenerator $generator): CommandTester
     {
         $application = new Application($kernel);
-        $application->add(new CachePoolPruneCommand($generator));
+        $application->addCommand(new CachePoolPruneCommand($generator));
 
         return new CommandTester($application->find('cache:pool:prune'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/RouterMatchCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/RouterMatchCommandTest.php
@@ -46,8 +46,8 @@ public function testWithNotMatchPath()
     private function createCommandTester(): CommandTester
     {
         $application = new Application($this->getKernel());
-        $application->add(new RouterMatchCommand($this->getRouter()));
-        $application->add(new RouterDebugCommand($this->getRouter()));
+        $application->addCommand(new RouterMatchCommand($this->getRouter()));
+        $application->addCommand(new RouterDebugCommand($this->getRouter()));
 
         return new CommandTester($application->find('router:match'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/TranslationDebugCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/TranslationDebugCommandTest.php
@@ -223,7 +223,7 @@ function ($path, $catalogue) use ($loadedMessages) {
         $command = new TranslationDebugCommand($translator, $loader, $extractor, $this->translationDir.'/translations', $this->translationDir.'/templates', $transPaths, $codePaths, $enabledLocales);
 
         $application = new Application($kernel);
-        $application->add($command);
+        $application->addCommand($command);
 
         return $application->find('debug:translation');
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/TranslationExtractCommandCompletionTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/TranslationExtractCommandCompletionTest.php
@@ -132,7 +132,7 @@ function ($path, $catalogue) use ($loadedMessages) {
         $command = new TranslationExtractCommand($writer, $loader, $extractor, 'en', $this->translationDir.'/translations', $this->translationDir.'/templates', $transPaths, $codePaths, ['en', 'fr']);
 
         $application = new Application($kernel);
-        $application->add($command);
+        $application->addCommand($command);
 
         return new CommandCompletionTester($application->find('translation:extract'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/TranslationExtractCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/TranslationExtractCommandTest.php
@@ -304,7 +304,7 @@ function (MessageCatalogue $catalogue) use ($writerMessages) {
         $command = new TranslationExtractCommand($writer, $loader, $extractor, 'en', $this->translationDir.'/translations', $this->translationDir.'/templates', $transPaths, $codePaths);
 
         $application = new Application($kernel);
-        $application->add($command);
+        $application->addCommand($command);
 
         return new CommandTester($application->find('translation:extract'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/WorkflowDumpCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/WorkflowDumpCommandTest.php
@@ -25,7 +25,12 @@ class WorkflowDumpCommandTest extends TestCase
     public function testComplete(array $input, array $expectedSuggestions)
     {
         $application = new Application();
-        $application->add(new WorkflowDumpCommand(new ServiceLocator([])));
+        $command = new WorkflowDumpCommand(new ServiceLocator([]));
+        if (method_exists($application, 'addCommand')) {
+            $application->addCommand($command);
+        } else {
+            $application->add($command);
+        }
 
         $tester = new CommandCompletionTester($application->find('workflow:dump'));
         $suggestions = $tester->complete($input, 2);

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/XliffLintCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/XliffLintCommandTest.php
@@ -59,7 +59,12 @@ private function createCommandTester($application = null): CommandTester
     {
         if (!$application) {
             $application = new BaseApplication();
-            $application->add(new XliffLintCommand());
+            $command = new XliffLintCommand();
+            if (method_exists($application, 'addCommand')) {
+                $application->addCommand($command);
+            } else {
+                $application->add($command);
+            }
         }
 
         $command = $application->find('lint:xliff');

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Command/YamlLintCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Command/YamlLintCommandTest.php
@@ -107,7 +107,12 @@ private function createCommandTester($application = null): CommandTester
     {
         if (!$application) {
             $application = new BaseApplication();
-            $application->add(new YamlLintCommand());
+            $command = new YamlLintCommand();
+            if (method_exists($application, 'addCommand')) {
+                $application->addCommand($command);
+            } else {
+                $application->add($command);
+            }
         }
 
         $command = $application->find('lint:yaml');

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Console/ApplicationTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Console/ApplicationTest.php
@@ -119,7 +119,7 @@ public function testBundleCommandCanOverriddeAPreExistingCommandWithTheSameName(
 
         $application = new Application($kernel);
         $newCommand = new Command('example');
-        $application->add($newCommand);
+        $application->addCommand($newCommand);
 
         $this->assertSame($newCommand, $application->get('example'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/BundlePathsTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/BundlePathsTest.php
@@ -28,7 +28,7 @@ public function testBundlePublicDir()
         $fs = new Filesystem();
         $fs->remove($projectDir);
         $fs->mkdir($projectDir.'/public');
-        $command = (new Application($kernel))->add(new AssetsInstallCommand($fs, $projectDir));
+        $command = (new Application($kernel))->addCommand(new AssetsInstallCommand($fs, $projectDir));
         $exitCode = (new CommandTester($command))->execute(['target' => $projectDir.'/public']);
 
         $this->assertSame(0, $exitCode);

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/CachePoolClearCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/CachePoolClearCommandTest.php
@@ -146,7 +146,7 @@ public function testExcludedPool()
     private function createCommandTester(?array $poolNames = null)
     {
         $application = new Application(static::$kernel);
-        $application->add(new CachePoolClearCommand(static::getContainer()->get('cache.global_clearer'), $poolNames));
+        $application->addCommand(new CachePoolClearCommand(static::getContainer()->get('cache.global_clearer'), $poolNames));
 
         return new CommandTester($application->find('cache:pool:clear'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/CachePoolListCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/CachePoolListCommandTest.php
@@ -46,7 +46,7 @@ public function testEmptyList()
     private function createCommandTester(array $poolNames)
     {
         $application = new Application(static::$kernel);
-        $application->add(new CachePoolListCommand($poolNames));
+        $application->addCommand(new CachePoolListCommand($poolNames));
 
         return new CommandTester($application->find('cache:pool:list'));
     }

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/ConfigDebugCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/ConfigDebugCommandTest.php
@@ -241,7 +241,7 @@ public function testComplete(bool $debug, array $input, array $expectedSuggestio
     {
         $application = $this->createApplication($debug);
 
-        $application->add(new ConfigDebugCommand());
+        $application->addCommand(new ConfigDebugCommand());
         $tester = new CommandCompletionTester($application->get('debug:config'));
         $suggestions = $tester->complete($input);
 

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/ConfigDumpReferenceCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/ConfigDumpReferenceCommandTest.php
@@ -132,7 +132,7 @@ public function testComplete(bool $debug, array $input, array $expectedSuggestio
     {
         $application = $this->createApplication($debug);
 
-        $application->add(new ConfigDumpReferenceCommand());
+        $application->addCommand(new ConfigDumpReferenceCommand());
         $tester = new CommandCompletionTester($application->get('config:dump-reference'));
         $suggestions = $tester->complete($input);
         $this->assertSame($expectedSuggestions, $suggestions);

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/DebugAutowiringCommandTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Functional/DebugAutowiringCommandTest.php
@@ -122,7 +122,7 @@ public function testNotConfusedByClassAliases()
     public function testComplete(array $input, array $expectedSuggestions)
     {
         $kernel = static::bootKernel(['test_case' => 'ContainerDebug', 'root_config' => 'config.yml']);
-        $command = (new Application($kernel))->add(new DebugAutowiringCommand());
+        $command = (new Application($kernel))->addCommand(new DebugAutowiringCommand());
 
         $tester = new CommandCompletionTester($command);
 

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Console;
 
+use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Command\CompleteCommand;
 use Symfony\Component\Console\Command\DumpCompletionCommand;
@@ -28,6 +29,7 @@
 use Symfony\Component\Console\Event\ConsoleTerminateEvent;
 use Symfony\Component\Console\Exception\CommandNotFoundException;
 use Symfony\Component\Console\Exception\ExceptionInterface;
+use Symfony\Component\Console\Exception\InvalidArgumentException;
 use Symfony\Component\Console\Exception\LogicException;
 use Symfony\Component\Console\Exception\NamespaceNotFoundException;
 use Symfony\Component\Console\Exception\RuntimeException;
@@ -512,33 +514,58 @@
      */
     public function register(string $name): Command
     {
-        return $this->add(new Command($name));
+        return $this->addCommand(new Command($name));
     }
 
     /**
      * Adds an array of command objects.
      *
      * If a Command is not enabled it will not be added.
      *
-     * @param Command[] $commands An array of commands
+     * @param callable[]|Command[] $commands An array of commands
      */
     public function addCommands(array $commands): void
     {
         foreach ($commands as $command) {
-            $this->add($command);
+            $this->addCommand($command);
         }
     }
 
+    /**
+     * @deprecated since Symfony 7.4, use Application::addCommand() instead
+     */
+    public function add(Command $command): ?Command
+    {
+        trigger_deprecation('symfony/console', '7.4', 'The "%s()" method is deprecated and will be removed in Symfony 8.0, use "%s::addCommand()" instead.', __METHOD__, self::class);
+
+        return $this->addCommand($command);
+    }
+
     /**
      * Adds a command object.
      *
      * If a command with the same name already exists, it will be overridden.
      * If the command is not enabled it will not be added.
      */
-    public function add(Command $command): ?Command
+    public function addCommand(callable|Command $command): ?Command
     {
         $this->init();
 
+        if (!$command instanceof Command) {
+            if (!\is_object($command) || $command instanceof \Closure) {
+                throw new InvalidArgumentException(\sprintf('The command must be an instance of "%s" or an invokable object.', Command::class));
+            }
+
+            /** @var AsCommand $attribute */
+            $attribute = ((new \ReflectionObject($command))->getAttributes(AsCommand::class)[0] ?? null)?->newInstance()
+                ?? throw new LogicException(\sprintf('The command must use the "%s" attribute.', AsCommand::class));
+
+            $command = (new Command($attribute->name))
+                ->setDescription($attribute->description ?? '')
+                ->setHelp($attribute->help ?? '')
+                ->setCode($command);
+        }
+
         $command->setApplication($this);
 
         if (!$command->isEnabled()) {
@@ -604,7 +631,7 @@
     {
         $this->init();
 
-        return isset($this->commands[$name]) || ($this->commandLoader?->has($name) && $this->add($this->commandLoader->get($name)));
+        return isset($this->commands[$name]) || ($this->commandLoader?->has($name) && $this->addCommand($this->commandLoader->get($name)));
     }
 
     /**
@@ -1322,7 +1349,7 @@
         $this->initialized = true;
 
         foreach ($this->getDefaultCommands() as $command) {
-            $this->add($command);
+            $this->addCommand($command);
         }
     }
 }