yaffs.net Git - yaffs-website/blob - vendor/drush/drush/docs/commands.md

   1 Creating Custom Drush Commands
   2 ==============================
   3
   4 Creating a new Drush command or porting a legacy command is easy. Follow the steps below.
   5
   6 1. Run `drush generate drush-command-file`.
   7 1. Drush will prompt for the machine name of the module that should "own" the file.
   8     1. (optional) Drush will also prompt for the path to a legacy command file to port. See [tips on porting command to Drush 9](https://weitzman.github.io/blog/port-to-drush9)
   9     1. The module selected must already exist and be enabled. Use `drush generate module-standard` to create a new module.
  10 1. Drush will then report that it created a commandfile, a drush.services.yml file and a composer.json file. Edit those files as needed.
  11 1. Use the classes for the core Drush commands at [/src/Drupal/Commands](https://github.com/drush-ops/drush/tree/master/src/Drupal/Commands) as inspiration and documentation.
  12 1. See the [dependency injection docs](dependency-injection.md) for interfaces you can implement to gain access to Drush config, Drupal site aliases, etc.
  13 1. Once your two files are ready, run `drush cr` to get your command recognized by the Drupal container.
  14
  15 Specifying the Services File
  16 ================================
  17
  18 A module's composer.json file stipulates the filename where the Drush services (e.g. the Drush command files) are defined. The default services file is `drush.services.yml`, which is defined in the extra section of the composer.json file as follows:
  19 ```
  20   "extra": {
  21     "drush": {
  22       "services": {
  23         "drush.services.yml": "^9"
  24       }
  25     }
  26   }
  27 ```
  28 If for some reason you need to load different services for different versions of Drush, simply define multiple services files in the `services` section. The first one found will be used. For example:
  29 ```
  30   "extra": {
  31     "drush": {
  32       "services": {
  33         "drush-9-99.services.yml": "^9.99",
  34         "drush.services.yml": "^9"
  35       }
  36     }
  37   }
  38 ```
  39 In this example, the file `drush-9-99.services.yml` loads commandfile classes that require features only available in Drush 9.99 and later, and drush.services.yml loads an older commandfile implementation for earlier versions of Drush.
  40
  41 It is also possible to use [version ranges](https://getcomposer.org/doc/articles/versions.md#version-range) to exactly specify which version of Drush the services file should be used with (e.g. `"drush.services.yml": ">=9 <9.99"`).
  42
  43 In Drush 9, the default services file, `drush.services.yml`, will be used in instances where there is no `services` section in the Drush extras of the project's composer.json file. In Drush 10, however, the services section must exist, and must name the services file to be used. If a future Drush extension is written such that it only works with Drush 10 and later, then its entry would read `"drush.services.yml": "^10"`, and Drush 9 would not load the extension's commands. It is all the same recommended that Drush 9 extensions explicitly declare their services file with an appropriate version constraint.
  44
  45 Altering Drush Command Info
  46 ===========================
  47
  48 Drush command info (annotations) can be altered from other modules. This is done by creating and registering 'command info alterers'. Alterers are class services that are able to intercept and manipulate an existing command annotation.
  49
  50 In order to alter an existing command info, follow the next steps:
  51
  52 1. In the module that wants to alter a command info, add a service class that implements the `\Consolidation\AnnotatedCommand\CommandInfoAltererInterface`.
  53 1. In the module `drush.services.yml` declare a service pointing to this class and tag the service with the `drush.command_info_alterer` tag.
  54 1. In the class implement the alteration logic the `alterCommandInfo()` method.
  55 1. Along with the alter code, it's strongly recommended to log a debug message explaining what exactly was altered. This would allow the easy debugging. Also it's a good practice to inject the the logger in the class constructor.
  56
  57 For an example, see the alterer class provided by the testing 'woot' module: `tests/resources/modules/d8/woot/src/WootCommandInfoAlterer.php`.
  58
  59 Global Drush Commands
  60 ==============================
  61
  62 Commandfiles that don't ship inside Drupal modules are called 'global' commandfiles. See the [examples/Commands](/examples/Commands) folder for examples. In general, its better to use modules to carry your Drush commands. If you still prefer using a global commandfiles, please note:
  63
  64 1. The file's fully qualified namespace should be `\Drush\Commands`.
  65 1. The filename must be have a name like Commands/FooCommands.php
  66     1. The prefix `Foo` can be whatever string you want. The file must end in `Commands.php`
  67     1. The enclosing directory must be named `Commands`
  68 1. The directory above Commands must be one of:
  69     1.  A Folder listed in the 'include' option. include may be provided via config or via CLI.
  70     1.  ../drush, /drush or /sites/all/drush. These paths are relative to Drupal root.