Use Autowire in commandfiles (#5889)

Author: weitzman

composer.json

@@ -64,7 +64,7 @@
     "squizlabs/php_codesniffer": "^3.7"
   },
   "conflict": {
-    "drupal/core": "< 10.0",
+    "drupal/core": "< 10.1",
     "drupal/migrate_run": "*",
     "drupal/migrate_tools": "<= 5"
   },

composer.lock

@@ -43,7 +43,7 @@ Bootstrapping is done from a Symfony Console command hook. The different bootstr
 
 none
 -----------------------
-Only run Drush _preflight_, without considering Drupal at all. Any code that operates on the Drush installation, and not specifically any Drupal directory, should bootstrap to this phase.
+Only run Drush _preflight_, without considering Drupal at all. Any code that operates on the Drush installation, and not specifically any Drupal directory, should bootstrap to this phase. This Attribute and value may also be used on a command _class_ when it wants to load before Drupal bootstrap is started. Commands that ship inside Drupal modules always bootstrap to full, regardless of _none_ value.
 
 root
 ------------------------------
@@ -68,4 +68,3 @@ Fully initialize Drupal. This is analogous to the DRUPAL\_BOOTSTRAP\_FULL bootst
 max
 ---------------------
 This is not an actual bootstrap phase. Commands that use the "max" bootstrap level will cause Drush to bootstrap as far as possible, and then run the command regardless of the bootstrap phase that was reached. This is useful for Drush commands that work without a bootstrapped site, but that provide additional information or capabilities in the presence of a bootstrapped site. For example, [`drush status`](commands/core_status.md) will show progressively more information the farther the site bootstraps.
-

docs/bootstrap.md

@@ -2,7 +2,7 @@
 
 !!! tip
 
-      1. Drush 12 expects commandfiles to use a [create() method](dependency-injection.md#create-method) 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 13.
+      1. Drush 13 expects commandfiles to use [Autowire](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 13.
       1. Drush 12 expects all commandfiles in the `<module-name>/src/Drush/<Commands|Generators>` directory. The `Drush` subdirectory is a new requirement.
 
 Creating a new Drush command is easy. Follow the steps below.
@@ -11,7 +11,7 @@ Creating a new Drush command is easy. Follow the steps below.
 2. Drush will prompt for the machine name of the module that should _own_ the file. The module selected must already exist and be enabled. Use `drush generate module` to create a new module.
 3. Drush will then report that it created a commandfile. Edit as needed.
 4. Use the classes for the core Drush commands at [/src/Commands](https://github.com/drush-ops/drush/tree/12.x/src/Commands) as inspiration and documentation.
-5. See the [dependency injection docs](dependency-injection.md) for interfaces you can implement to gain access to Drush config, Drush site aliases, etc. Also note the [create() method](dependency-injection.md#create-method) for injecting Drupal or Drush dependencies.
+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/12.x/docs/contribute/unish.md#drush-test-traits).
 
 ## Attributes or Annotations

docs/commands.md

@@ -3,15 +3,22 @@ Dependency Injection
 
 Drush command files obtain references to the resources they need through a technique called _dependency injection_. When using this programing paradigm, a class by convention will never use the `new` operator to instantiate dependencies. Instead, it will store the other objects it needs in  class variables, and provide a way for other code to assign an object to that variable.
 
-create() method
+!!! tip
+
+    Drush 11 and prior required [dependency injection via a drush.services.yml file](https://www.drush.org/11.x/dependency-injection/#services-files). This approach is deprecated in Drush 12+ and removed in Drush 13.
+
+Autowire
 ------------------
-:octicons-tag-24: 11.6+
+:octicons-tag-24: 13
+Command files may inject Drush and Drupal services by adding the [AutowireTrait](https://github.com/drush-ops/drush/blob/13.x/src/Commands/AutowireTrait.php) to the class (example: [PmCommands](https://github.com/drush-ops/drush/blob/13.x/src/Commands/pm/PmCommands.php)). This enables your [Constructor parameter type hints determine the the injected service](https://www.drupal.org/node/3396179). When a type hint is insufficient, an [#[Autowire] Attribute](https://www.drupal.org/node/3396179) on the constructor property (with _service:_ named argument) directs AutoWireTrait to the right service (example: [LoginCommands](https://github.com/drush-ops/drush/blob/13.x/src/Commands/core/LoginCommands.php)). This Attribute is currently _required_ when injecting Drush services (not required for Drupal services). 
 
-!!! tip
+If your command is not found by Drush, add the `-vvv` option for debug info about any service instantiation errors. If Autowire is still insufficient, a commandfile may implement its own `create()` method (see below).
 
-    Drush 11 and prior required [dependency injection via a drush.services.yml file](https://www.drush.org/11.x/dependency-injection/#services-files). This approach is deprecated in Drush 12+ and will be removed in Drush 13.
+create() method
+------------------
+:octicons-tag-24: 11.6+
 
-Drush command files can inject services by adding a create() method to the commandfile. See [creating commands](commands.md) for instructions on how to use the Drupal Code Generator to create a simple command file starter. A create() method and a constructor will look something like this:
+Command files not using Autowire may inject services by adding a create() method to the commandfile. A create() method and a constructor will look something like this:
 ```php
 class WootStaticFactoryCommands extends DrushCommands
 {
@@ -22,33 +29,27 @@ class WootStaticFactoryCommands extends DrushCommands
         $this->configFactory = $configFactory;
     }
 
-    public static function create(ContainerInterface $container, DrushContainer $drush): self
+    public static function create(ContainerInterface $container): self
     {
         return new static($container->get('config.factory'));
     }
 ```
-See the [Drupal Documentation](https://www.drupal.org/docs/drupal-apis/services-and-dependency-injection/services-and-dependency-injection-in-drupal-8#s-injecting-dependencies-into-controllers-forms-and-blocks) for details on how to inject Drupal services into your command file. Drush's approach mimics Drupal's blocks, forms, and controllers.
-
-Note that if you do not need to pull any services from the Drush container, then you may
-omit the second parameter to the `create()` method.
+See the [Drupal Documentation](https://www.drupal.org/docs/drupal-apis/services-and-dependency-injection/services-and-dependency-injection-in-drupal-8#s-injecting-dependencies-into-controllers-forms-and-blocks) for details on how to inject Drupal services into your command file. This approach mimics Drupal's blocks, forms, and controllers.
 
 createEarly() method
 ------------------
 :octicons-tag-24: 12.0+
-Drush commands that need to be instantiated prior to bootstrap may do so by
-utilizing the `createEarly()` static factory. This method looks and functions
-exacty like the `create()` static factory, except it is only passed the Drush
-container. The Drupal container is not available to command handlers that use
-`createEarly()`.
+!!! tip
+
+    Drush 12 supported a createEarly() method. This is deprecated and instead put a `#[CLI\Bootstrap(DrupalBootLevels::NONE)]` Attribute on the command class and inject dependencies via the usual `__construct` with [AutowireTrait](https://github.com/drush-ops/drush/blob/13.x/src/Commands/AutowireTrait.php). Note also that Drush commands packaged with Drupal modules are not discovered
+    until after Drupal bootstraps, and therefore cannot use `createEarly()`. This
+    mechanism is only usable by PSR-4 discovered commands packaged with Composer
+    projects that are *not* Drupal modules.
 
-Note also that Drush commands packaged with Drupal modules are not discovered
-until after Drupal bootstraps, and therefore cannot use `createEarly()`. This
-mechanism is only usable by PSR-4 discovered commands packaged with Composer
-projects that are *not* Drupal modules.
 
 Inflection
 -----------------
 A command class may implement the following interfaces. When doing so, implement the corresponding trait to satisfy the interface.
 
 - [CustomEventAwareInterface](https://github.com/consolidation/annotated-command/blob/4.x/src/Events/CustomEventAwareInterface.php): Allows command files to [define and fire custom events](hooks.md) that other command files can hook. Example: [CacheCommands](https://github.com/drush-ops/drush/blob/13.x/src/Commands/core/CacheCommands.php)
-- [StdinAwareInterface](https://github.com/consolidation/annotated-command/blob/4.x/src/Input/StdinAwareInterface.php): Read from standard input. This class contains facilities to redirect stdin to instead read from a file, e.g. in response to an option or argument value. Example: [CacheCommands](https://github.com/drush-ops/drush/blob/13.x/src/Commands/core/CacheCommands.php)
+- [StdinAwareInterface](https://github.com/consolidation/annotated-command/blob/4.x/src/Input/StdinAwareInterface.php): Read from standard input. This class contains facilities to redirect stdin to instead read from a file, e.g. in response to an option or argument value. Example: [CacheCommands](https://github.com/drush-ops/drush/blob/13.x/src/Commands/core/CacheCommands.php)

docs/dependency-injection.md

@@ -2,7 +2,7 @@
 
 !!! tip
 
-    Drush 11 and prior required generators to define a [drush.services.yml file](https://www.drush.org/11.x/dependency-injection/#services-files). This is no longer used with Drush 12+ generators. See [create() method](dependency-injection.md#create-method) for injecting dependencies.
+    Drush 11 and prior required generators to define a [drush.services.yml file](https://www.drush.org/11.x/dependency-injection/#services-files). This is no longer used with Drush 12+ generators. See [docs](dependency-injection.md) for injecting dependencies.
 
 Generators jump start your coding by building all the boring boilerplate code for you. After running the [generate command](commands/generate.md), you have a guide for where to insert your custom logic.
 
@@ -17,7 +17,7 @@ Creating a new Drush generator is easy. Follow the steps below.
 2. Drush will prompt for the machine name of the module that should _own_ the files. The module selected must already exist and be enabled. Use `drush generate module` to create a new module.
 3. Drush will then report that it created a generator (PHP class and twig file). Edit as needed.
 4. Similar to [ExampleGenerator](https://github.com/drush-ops/drush/tree/12.x/sut/modules/unish/woot/src/Drush/Generators), implement your custom logic in the generate() method.
-5. See the [dependency injection docs](dependency-injection.md) for interfaces you can implement to gain access to Drush config, Drush site aliases, etc. Also note the [create() method](dependency-injection.md#create-method) for injecting Drupal or Drush dependencies.
+5. You may [inject dependencies](dependency-injection.md) from Drupal or Drush.
 
 ## Auto-discovered Generators (PSR4)
 

docs/generators.md

@@ -9,7 +9,7 @@ All commandfiles may implement methods that are called by Drush at various times
 
 Drush commands can define custom events that other command files can hook. You can find examples in [CacheCommands](https://github.com/drush-ops/drush/blob/12.x/src/Commands/core/CacheCommands.php) and [SanitizeCommands](https://github.com/drush-ops/drush/blob/12.x/src/Drupal/Commands/sql/SanitizeCommands.php)
 
-First, the command must implement CustomEventAwareInterface and use CustomEventAwareTrait, as described in the [dependency injection](dependency-injection.md) documentation.
+First, the command must implement CustomEventAwareInterface and use CustomEventAwareTrait, as described in the [dependency injection](dependency-injection.md#inflection) documentation.
 
 Then, the command may ask the provided hook manager to return a list of handlers with a certain attribute. In the example below, the `my-event` label is used:
 ```php

docs/hooks.md

@@ -31,7 +31,7 @@ Drupal Compatibility
     <td> Drush 13 </td>
     <td> 8.3+ </td>
     <td> TBD </td>
-    <td></td> <td></td> <td></td> <td><b>✓</b></td> <td><b>✅</b></td>
+    <td></td> <td></td> <td></td> <td><b>✓ 10.2+</b></td> <td><b>✅</b></td>
   </tr>
   <tr>
     <td> Drush 12 </td>

docs/install.md

@@ -4,8 +4,12 @@ Site Alias Manager
 The [Site Alias Manager (SAM)](https://github.com/consolidation/site-alias/blob/4.0.1/src/SiteAliasManager.php) service is used to retrieve information about one or all of the site aliases for the current installation.
 
 - An informative example is the [browse command](https://github.com/drush-ops/drush/blob/12.x/src/Commands/core/BrowseCommands.php)
-- A commandfile gets access to the SAM by implementing the SiteAliasManagerAwareInterface and *use*ing the SiteAliasManagerAwareTrait trait. Then you gain access via `$this->siteAliasManager()`.
-- If an alias was used for the current request, it is available via `$this->siteAliasManager()->getself()`.
+- A commandfile gets access to the SAM as follows:
+```php
+#[Autowire(service: DependencyInjection::SITE_ALIAS_MANAGER)]
+private readonly SiteAliasManagerInterface $siteAliasManager
+```
+- If an alias was used for the current request, it is available via `$this->siteAliasManager->getself()`.
 - The SAM generally deals in [SiteAlias](https://github.com/consolidation/site-alias/blob/main/src/SiteAlias.php) objects. That is how any given site alias is represented. See its methods for determining things like whether the alias points to a local host or remote host.
 - [Site alias docs](site-aliases.md).
 - [Dynamically alter site aliases](https://raw.githubusercontent.com/drush-ops/drush/11.x/examples/Commands/SiteAliasAlterCommands.php).

docs/site-alias-manager.md

@@ -6,29 +6,26 @@
 use Consolidation\AnnotatedCommand\Hooks\HookManager;
 use Consolidation\SiteAlias\SiteAliasManagerInterface;
 use Drush\Attributes as CLI;
-use League\Container\Container as DrushContainer;
+use Drush\Boot\DrupalBootLevels;
+use Drush\Runtime\DependencyInjection;
 use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
 
 /**
  * Load this example by using the --include option - e.g. `drush --include=/path/to/drush/examples`
  */
+#[CLI\Bootstrap(DrupalBootLevels::NONE)]
 class SiteAliasAlterCommands extends DrushCommands
 {
+    use AutowireTrait;
+
     public function __construct(
+        #[Autowire(service: DependencyInjection::SITE_ALIAS_MANAGER)]
         private readonly SiteAliasManagerInterface $siteAliasManager
     ) {
         parent::__construct();
     }
 
-    public static function createEarly(DrushContainer $drush_container): self
-    {
-        $commandHandler = new static(
-            $drush_container->get('site.alias.manager'),
-        );
-
-        return $commandHandler;
-    }
-
     /**
      * A few example alterations to site aliases.
      */

examples/Commands/SiteAliasAlterCommands.php

@@ -12,8 +12,8 @@
 use Drush\Command\RemoteCommandProxy;
 use Drush\Config\ConfigAwareTrait;
 use Drush\Runtime\RedispatchHook;
-use Drush\Runtime\TildeExpansionHook;
 use Drush\Runtime\ServiceManager;
+use Drush\Runtime\TildeExpansionHook;
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerAwareTrait;
 use Robo\Contract\ConfigAwareInterface;

src/Application.php

@@ -9,7 +9,7 @@
 use Drush\Boot\DrupalBootLevels;
 use JetBrains\PhpStorm\ExpectedValues;
 
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 class Bootstrap
 {
     /**

src/Attributes/Bootstrap.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Drush\Commands;
+
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\DependencyInjection\Exception\AutowiringFailedException;
+
+/**
+ * A copy of \Drupal\Core\DependencyInjection\AutowireTrait with first params' type hint changed.
+ *
+ * Defines a trait for automatically wiring dependencies from the container.
+ *
+ * This trait uses reflection and may cause performance issues with classes
+ * that will be instantiated multiple times.
+ */
+trait AutowireTrait
+{
+  /**
+   * Instantiates a new instance of the implementing class using autowiring.
+   *
+   * @param \Psr\Container\ContainerInterface $container
+   *   The service container this instance should use.
+   *
+   * @return static
+   */
+    public static function create(\Psr\Container\ContainerInterface $container)
+    {
+        $args = [];
+
+        if (method_exists(static::class, '__construct')) {
+            $constructor = new \ReflectionMethod(static::class, '__construct');
+            foreach ($constructor->getParameters() as $parameter) {
+                $service = ltrim((string) $parameter->getType(), '?');
+                foreach ($parameter->getAttributes(Autowire::class) as $attribute) {
+                    $service = (string) $attribute->newInstance()->value;
+                }
+
+                if (!$container->has($service)) {
+                    throw new AutowiringFailedException($service, sprintf('Cannot autowire service "%s": argument "$%s" of method "%s::_construct()", you should configure its value explicitly.', $service, $parameter->getName(), static::class));
+                }
+
+                $args[] = $container->get($service);
+            }
+        }
+
+        return new static(...$args);
+    }
+}

src/Commands/AutowireTrait.php

@@ -24,7 +24,6 @@
 use Robo\Contract\ConfigAwareInterface;
 use Robo\Contract\IOAwareInterface;
 use Symfony\Component\Console\Input\InputOption;
-use Symfony\Component\Console\Style\SymfonyStyle;
 use Symfony\Component\Filesystem\Path;
 
 abstract class DrushCommands implements IOAwareInterface, LoggerAwareInterface, ConfigAwareInterface, ProcessManagerAwareInterface