Deprecate Annotated Commands in favor of native Symfony Console commands

.circleci/config.yml

@@ -14,6 +14,7 @@ defaults: &defaults
     PHP_EXTENSIONS_DISABLE: xdebug
     PHP_XDEBUG_MODE: off
 
+#No longer used
 requires: &requires
   requires:
     - check_mergable
@@ -173,7 +174,8 @@ workflows:
 #      - test_80_drupal92_security:
 #          <<: *requires
       - test:
-          <<: *requires
+          # Not used, for now.
+          #          <<: *requires
           <<: *poststeps
           matrix:
             parameters:

composer.json

@@ -39,7 +39,7 @@
     "consolidation/annotated-command": "^4.9.2",
     "consolidation/config": "^2.1.2 || ^3",
     "consolidation/filter-via-dot-access-data": "^2.0.2",
-    "consolidation/output-formatters": "^4.3.2",
+    "consolidation/output-formatters": "dev-use-command-directly-of as 4.x-dev",
     "consolidation/robo": "^4.0.6 || ^5",
     "consolidation/site-alias": "^4",
     "consolidation/site-process": "^5.2.0",
@@ -88,7 +88,8 @@
   "config": {
     "allow-plugins": {
       "composer/installers": true,
-      "cweagans/composer-patches": true
+      "cweagans/composer-patches": true,
+      "symfony/runtime": true
     },
     "optimize-autoloader": true,
     "preferred-install": "dist",

docs/commands.md

@@ -2,8 +2,8 @@
 
 !!! tip
 
-      1. Drush 13 expects commandfiles to use the [AutowireTrait](https://github.com/drush-ops/drush/blob/13.x/src/Commands/AutowireTrait.php) to inject Drupal and Drush dependencies. Prior versions used a [drush.services.yml file](https://www.drush.org/11.x/dependency-injection/#services-files) which is now deprecated and will be removed in Drush 14.
-      1. Drush 12 expects all commandfiles in the `<module-name>/src/Drush/<Commands|Generators>` directory. The `Drush` subdirectory is a new requirement.
+      1. Drush 13+ expects commandfiles to use the [AutowireTrait](https://github.com/drush-ops/drush/blob/13.x/src/Commands/AutowireTrait.php) to inject Drupal and Drush dependencies. Prior versions used a [drush.services.yml file](https://www.drush.org/11.x/dependency-injection/#services-files) which is now deprecated and will be removed in Drush 14.
+      1. Drush 12+ expects all commandfiles in the `<module-name>/src/Drush/<Commands|Generators|Listeners>` directory. The `Drush` subdirectory is a new requirement.
 
 Creating a new Drush command is easy. Follow the steps below.
 
@@ -14,67 +14,38 @@ Creating a new Drush command is easy. Follow the steps below.
 5. You may [inject dependencies](dependency-injection.md) into a command instance.
 6. Write PHPUnit tests based on [Drush Test Traits](https://github.com/drush-ops/drush/blob/13.x/docs/contribute/unish.md#drush-test-traits).
 
-## Attributes or Annotations
-The following are both valid ways to declare a command:
-
-=== "PHP8 Attributes"
-
-    ```php
-    use Drush\Attributes as CLI;
-
-    /**
-     * Retrieve and display xkcd cartoons (attribute variant).
-     */
-    #[CLI\Command(name: 'xkcd:fetch-attributes', aliases: ['xkcd-attributes'])]
-    #[CLI\Argument(name: 'search', description: 'Optional argument to retrieve the cartoons matching an index, keyword, or "random".')]
-    #[CLI\Option(name: 'image-viewer', description: 'Command to use to view images (e.g. xv, firefox).', suggestedValues: ['open', 'xv', 'firefox'])]
-    #[CLI\Option(name: 'google-custom-search-api-key', description: 'Google Custom Search API Key')]
-    #[CLI\Usage(name: 'drush xkcd', description: 'Retrieve and display the latest cartoon')]
-    #[CLI\Usage(name: 'drush xkcd sandwich', description: 'Retrieve and display cartoons about sandwiches.')]
-    public function fetch($search = null, $options = ['image-viewer' => 'open', 'google-custom-search-api-key' => 'AIza']) {
-        $this->doFetch($search, $options);
-    }
-    ```
-
-=== "Annotations"
-
-    ```php
-    /**
-     * @command xkcd:fetch
-     * @param $search Optional argument to retrieve the cartoons matching an index number, keyword, or "random".
-     * @option image-viewer Command to use to view images (e.g. xv, firefox).
-     * @option google-custom-search-api-key Google Custom Search API Key.
-     * @usage drush xkcd
-     *   Retrieve and display the latest cartoon.
-     * @usage drush xkcd sandwich
-     *   Retrieve and display cartoons about sandwiches.
-     * @aliases xkcd
-    */
-    public function fetch($search = null, $options = ['image-viewer' => 'open', 'google-custom-search-api-key' => 'AIza']) {
-        $this->doFetch($search, $options);
-    }
-    ```
+## Symfony Console Commands
 
-- A commandfile that will only be used on PHP8+ should [use PHP Attributes](https://github.com/drush-ops/drush/pull/4821) instead of Annotations.
-- [See Attributes provided by Drush core](https://www.drush.org/api/Drush/Attributes.html). Custom code can supply additional Attribute classes, which may then be added to any command. For example see [InteractConfigName](https://github.com/drush-ops/drush/blob/13.x/src/Attributes/InteractConfigName.php) which is used by [ConfigCommands](https://github.com/drush-ops/drush/blob/8b77c9abe6639de42a198c7e69565f09dcf5f22d/src/Commands/config/ConfigCommands.php#L98).
+Drush 14+ deprecates old-style Annotated Commands in favor of pure [Symfony Console commands](https://symfony.com/doc/current/console.html). This implies:
+
+- Each command lives in its own class file
+- The command class extends `Symfony\Component\Console\Command\Command` directly. The base class `DrushCommands` is deprecated.
+- The command class should use Console's #[AsCommand] Attribute to declare its name, aliases, and hidden status. The old #[Command] Attribute is deprecated.
+- Options and Arguments moved from Attributes to a configure() method on the command class
+- The main logic of the command moved to an execute() method on the command class.
+- User interaction now happens in an interact() method on the command class.
+- Drush and Drupal services may still be autowired. This is how you access the logger. Build own $io as needed.
+- Commands that wish to offer multiple _output formats_ (yes please!) should (Example: _TwigUnusedCommand_,
+  _SqlDumpCommand_):
+    - inject `FormatterManager` in __construct()
+    - `use FormatterTrait`
+    - call `$this->configureFormatter()` in `configure()` in order to automatically add the needed options.
+    - `execute()` is boilerplate. By convention, do your work in a `doExecute()` method instead.
+- [See Optionsets provided by Drush core](https://github.com/drush-ops/drush/blob/13.x/src/Commands/OptionsSets.php). Custom code can supply additional Optionset methods, which any command may choose to use.
 
 ## Altering Command Info
-Drush command info (annotations/attributes) can be altered from other modules. This is done by creating and registering _command info alterers_. Alterers are classes that are able to intercept and manipulate an existing command annotation.
 
-In the module that wants to alter a command info, add a class that:
+Drush command info can be altered from other modules. This is done by creating and registering a command definition listener. Listeners are dispatched once after non-bootstrap commands are instantiated and once again after bootstrap commands are instantiated.
 
-1. The class namespace, relative to base namespace, should be `Drupal\<module-name>\Drush\CommandInfoAlterers` and the class file should be located under the `src/Drush/CommandInfoAlterers` directory.
-1. The filename must have a name like FooCommandInfoAlterer.php. The prefix `Foo` can be whatever string you want. The file must end in `CommandInfoAlterer.php`.
-1. The class must implement the `\Consolidation\AnnotatedCommand\CommandInfoAltererInterface`.
-1. Implement the alteration logic in the `alterCommandInfo()` method.
-1. Along with the alter code, it's strongly recommended to log a debug message explaining what exactly was altered. This makes things easier on others who may need to debug the interaction of the alter code with other modules. Also it's a good practice to inject the the logger in the class constructor.
-
-For an example, see [WootCommandInfoAlterer](https://github.com/drush-ops/drush/blob/13.x/sut/modules/unish/woot/src/Drush/CommandInfoAlterers/WootCommandInfoAlterer.php) provided by the testing 'woot' module.
+In the module that wants to alter a command info, add a class that:
 
-## Symfony Console Commands
+1. The class namespace, relative to base namespace, should be `Drupal\<module-name>\Drush\Listeners` and the class file should be located under the `src/Drush/Listeners` directory.
+1. The filename must have a name like FooListener.php. The prefix `Foo` can be whatever string you want. The file must end in `Listener.php`.
+1. The class should implement the `#[AsListener]` PHP Attribute.
+1. Implement the alteration logic via a `__invoke(ConsoleDefinitionsEvent $event)` method.
+1. Along with the alter code, it's strongly recommended to log a debug message explaining what exactly was altered. This makes things easier on others who may need to debug the interaction of the alter code with other modules. Also it's a good practice to inject the logger in the class constructor.
 
-Drush lists and runs Symfony Console commands, in addition to more typical annotated commands.
-See [GreetCommands](https://github.com/drush-ops/drush/blob/13.x/sut/modules/unish/woot/src/Drush/Commands/GreetCommands.php) as an example. Note that these commands must conform to the usual class name and class namespace requirements. You might need to extend the Console class if you can't rename and move it.
+For an example, see [WootDefinitionListener](https://github.com/drush-ops/drush/blob/13.x/sut/modules/unish/woot/src/Drush/Liseners/WootDefinitionListener.php) provided by the testing 'woot' module.
 
 ## Auto-discovered commands (PSR4)
 

src-symfony-compatibility/v6/Style/DrushStyle.php

@@ -37,8 +37,7 @@ public function confirm(string $question, bool $default = true, string $yes = 'Y
         return confirm($question, $default, $yes, $no, $required, $validate, $hint);
     }
 
-    #[Deprecated('Use select() or multiselect() instead.')]
-    public function choice(string $question, array $choices, mixed $default = null, bool $multiSelect = false, int $scroll = 10, ?\Closure $validate = null, string $hint = '', bool|string $required = true): mixed
+    public function choice(string $question, array $choices, mixed $default = null, bool $multiSelect = false, int $scroll = 15, ?\Closure $validate = null, string $hint = '', bool|string $required = true): mixed
     {
         if ($multiSelect) {
             // For backward compat. Deprecated.

src/Application.php

@@ -11,6 +11,7 @@
 use Drush\Boot\DrupalBootLevels;
 use Drush\Command\RemoteCommandProxy;
 use Drush\Config\ConfigAwareTrait;
+use Drush\Event\ConsoleDefinitionsEvent;
 use Drush\Runtime\RedispatchHook;
 use Drush\Runtime\ServiceManager;
 use Drush\Runtime\TildeExpansionHook;
@@ -309,6 +310,8 @@ public function configureAndRegisterCommands(InputInterface $input, OutputInterf
         // any of the configuration steps we do here.
         $this->configureIO($input, $output);
 
+        $this->addListeners($commandfileSearchpath);
+
         // Directly add the yaml-cli commands.
         $this->addCommands($this->serviceManager->instantiateYamlCliCommands());
 
@@ -327,6 +330,9 @@ public function configureAndRegisterCommands(InputInterface $input, OutputInterf
         // Note that Robo::register can accept either Annotated Command
         // command handlers or Symfony Console Command objects.
         Robo::register($this, $commandInstances);
+
+        // Dispatch our custom event. It also fires later in \Drush\Boot\DrupalBoot8::bootstrapDrupalFull.
+        Drush::getContainer()->get('eventDispatcher')->dispatch(new ConsoleDefinitionsEvent($this), ConsoleDefinitionsEvent::class);
     }
 
     /**
@@ -338,4 +344,34 @@ public function renderThrowable(\Throwable $e, OutputInterface $output): void
 
         $this->doRenderThrowable($e, $output);
     }
+
+    // Discover event listeners, and add those that do not require bootstrap.
+    protected function addListeners($commandfileSearchpath): void
+    {
+        $listenerClasses = $this->serviceManager->discoverListeners($commandfileSearchpath, '\Drush');
+        $listenerClasses = $this->serviceManager->filterListeners($listenerClasses);
+        $this->serviceManager->addListeners($listenerClasses, Drush::getContainer());
+    }
+
+    /**
+     * Remove a command. Initially used by WootDefinitionListener and its test.
+     *
+     * An alternative would be console.excluded https://github.com/search?q=repo%3AHuttopia%2Fconsole-bundle%20console.excluded&type=code
+     */
+    public function remove(string $id): void
+    {
+        $rf = new \ReflectionProperty(\Symfony\Component\Console\Application::class, 'commands');
+        $rf->setAccessible(true);
+        $commands = $rf->getValue($this);
+        unset($commands[$id]);
+        $rf->setValue($this, $commands);
+    }
+
+    /**
+     * A base URL for help.
+     */
+    public function getDocsBaseUrl(): string
+    {
+        return 'https://www.drush.org/latest';
+    }
 }

src/Attributes/DefaultFields.php

@@ -5,7 +5,9 @@
 namespace Drush\Attributes;
 
 use Attribute;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Call \Drush\Formatters\FormatterTrait::configureFormatter during configure()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class DefaultFields extends \Consolidation\AnnotatedCommand\Attributes\DefaultFields
 {

src/Attributes/DefaultTableFields.php

@@ -5,7 +5,9 @@
 namespace Drush\Attributes;
 
 use Attribute;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Call \Drush\Formatters\FormatterTrait::configureFormatter during configure()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class DefaultTableFields extends \Consolidation\AnnotatedCommand\Attributes\DefaultTableFields
 {

src/Attributes/FieldLabels.php

@@ -5,7 +5,9 @@
 namespace Drush\Attributes;
 
 use Attribute;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Call \Drush\Formatters\FormatterTrait::configureFormatter during configure()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class FieldLabels extends \Consolidation\AnnotatedCommand\Attributes\FieldLabels
 {

src/Attributes/FilterDefaultField.php

@@ -6,7 +6,7 @@
 
 use Attribute;
 
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
 class FilterDefaultField extends \Consolidation\AnnotatedCommand\Attributes\FilterDefaultField
 {
 }

src/Attributes/Format.php

@@ -7,7 +7,6 @@
 use Attribute;
 use Consolidation\AnnotatedCommand\Parser\CommandInfo;
 use Consolidation\OutputFormatters\Options\FormatterOptions;
-use Drush\Boot\Kernels;
 use JetBrains\PhpStorm\ExpectedValues;
 
 #[Attribute(Attribute::TARGET_METHOD)]

src/Attributes/OptionsetSql.php

@@ -7,8 +7,10 @@
 use Attribute;
 use Consolidation\AnnotatedCommand\Parser\CommandInfo;
 use Drush\Commands\DrushCommands;
+use JetBrains\PhpStorm\Deprecated;
 
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Deprecated(replacement: 'Directly add options by calling \Drush\Commands\OptionSets::sql during configure()')]
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
 class OptionsetSql
 {
     public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)

src/Attributes/OptionsetTableSelection.php

@@ -7,7 +7,9 @@
 use Attribute;
 use Consolidation\AnnotatedCommand\Parser\CommandInfo;
 use Drush\Commands\DrushCommands;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Call \Drush\Commands\OptionSets::tableSelection during configure()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class OptionsetTableSelection
 {
@@ -18,7 +20,6 @@ public static function handle(\ReflectionAttribute $attribute, CommandInfo $comm
         $commandInfo->addOption('tables-key', 'A key in the $tables array.', [], DrushCommands::REQ);
         $commandInfo->addOption('skip-tables-list', 'A comma-separated list of tables to exclude completely.', [], DrushCommands::REQ);
         $commandInfo->addOption('structure-tables-list', 'A comma-separated list of tables to include for structure, but not data.', [], DrushCommands::REQ);
-        $commandInfo->addOption('skip-tables-list', 'A comma-separated list of tables to exclude completely.', [], DrushCommands::REQ);
         $commandInfo->addOption('tables-list', 'A comma-separated list of tables to transfer.', [], DrushCommands::REQ);
     }
 }

src/Attributes/Topics.php

@@ -6,7 +6,7 @@
 
 use Attribute;
 
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
 class Topics extends \Consolidation\AnnotatedCommand\Attributes\Topics
 {
 }

src/Attributes/ValidateEntityLoad.php

@@ -8,7 +8,9 @@
 use Consolidation\AnnotatedCommand\CommandData;
 use Consolidation\AnnotatedCommand\CommandError;
 use Drush\Utils\StringUtils;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Copy \Drush\Commands\core\ImageFlushCommand::validateEntityLoad into command and call during execute()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class ValidateEntityLoad extends ValidatorBase implements ValidatorInterface
 {

src/Attributes/ValidateFileExists.php

@@ -7,7 +7,9 @@
 use Attribute;
 use Consolidation\AnnotatedCommand\CommandData;
 use Consolidation\AnnotatedCommand\CommandError;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Copy \Drush\Commands\core\ImageDeriveCommand::validateFileExists into command and call during execute()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class ValidateFileExists extends ValidatorBase implements ValidatorInterface
 {

src/Attributes/ValidateModulesEnabled.php

@@ -7,7 +7,9 @@
 use Attribute;
 use Consolidation\AnnotatedCommand\CommandData;
 use Consolidation\AnnotatedCommand\CommandError;
+use JetBrains\PhpStorm\Deprecated;
 
+#[Deprecated(replacement: 'Copy \Drush\Commands\core\ImageFlushCommand::validateModulesEnabled into command and call during execute()')]
 #[Attribute(Attribute::TARGET_METHOD)]
 class ValidateModulesEnabled extends ValidatorBase implements ValidatorInterface
 {

src/Boot/DrupalBoot8.php

@@ -13,11 +13,10 @@
 use Drush\Config\ConfigLocator;
 use Drush\Drupal\DrushLoggerServiceProvider;
 use Drush\Drush;
+use Drush\Event\ConsoleDefinitionsEvent;
 use Drush\Runtime\LegacyServiceFinder;
 use Drush\Runtime\LegacyServiceInstantiator;
 use Drush\Runtime\ServiceManager;
-use Psr\Log\LoggerAwareInterface;
-use Psr\Log\LoggerInterface;
 use Robo\Robo;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -215,12 +214,20 @@ public function bootstrapDrupalFull(BootstrapManager $manager): void
         // Directly add the Drupal core bootstrapped commands.
         Drush::getApplication()->addCommands($this->serviceManager->instantiateDrupalCoreBootstrappedCommands());
 
+        $this->addBootstrapListeners();
+
         $this->addDrupalModuleDrushCommands($manager);
 
+        // Dispatch our custom event. It also fires earlier in \Drush\Application::configureAndRegisterCommands.
+        Drush::getContainer()->get('eventDispatcher')->dispatch(new ConsoleDefinitionsEvent(Drush::getApplication()), ConsoleDefinitionsEvent::class);
+
         // Set a default account to make sure the correct timezone is set
         $this->kernel->getContainer()->get('current_user')->setAccount(new AnonymousUserSession());
     }
 
+    /**
+     * Adds module supplied commands, as well as Drush Console commands that require bootstrap.
+     */
     public function addDrupalModuleDrushCommands(BootstrapManager $manager): void
     {
         $application = Drush::getApplication();
@@ -323,4 +330,17 @@ public function bootstrapDrupalSite(BootstrapManager $manager)
     {
         $this->bootstrapDoDrupalSite($manager);
     }
+
+    // Add the Listeners that require bootstrap.
+    public function addBootstrapListeners(): void
+    {
+        $listenersInThisModule = [];
+        $moduleHandler = \Drupal::moduleHandler();
+        foreach ($moduleHandler->getModuleList() as $moduleId => $extension) {
+            $path = DRUPAL_ROOT . '/' . $extension->getPath() . '/src/Drush';
+            $listenersInThisModule = array_merge($listenersInThisModule, $this->serviceManager->discoverListeners([$path], "\Drupal\\$moduleId\Drush"));
+        }
+        $classes = $this->serviceManager->bootstrapListenerClasses();
+        $this->serviceManager->addListeners(array_merge($listenersInThisModule, $classes), Drush::getContainer(), \Drupal::getContainer());
+    }
 }

src/Commands/AutowireTrait.php

@@ -21,8 +21,6 @@ trait AutowireTrait
      *
      * @param ContainerInterface $container
      *   The service container this instance should use.
-     *
-     * @return static
      */
     public static function create(ContainerInterface $container)
     {