Format Drush output for easy wins!

Drush, the brilliant command-line tool for Drupal, is capable of giving you its output in several ways. Its global --format parameter can be set to a type that you can use in useful ways. Most recently, I found this incredibly useful when I had made some configuration changes through Drupal's admin pages, and needed to then script those changes to automatically apply to hundreds of sites on a platform we manage.

I simply asked Drush for the value of the configuration I had set, formatted as the PHP code to set those values. Then I could drop that into our PHP automatic update script. Here are two examples - one getting just a single property of a block placement, and another for the whole settings object for a module.

# Get the visibility conditions of my block.
drush config:get block.block.myblock visibility --format=var_export
# Get the whole settings singleton for my module.
drush config:get mymodule.settings --format=var_export

The var_export format provides the output using PHP's traditional array syntax, instead of the default YAML (which matches the format of config export files). Here's an example of the output for another type of configuration, an action:

array (
  'uuid' => 'faaaea7f-d377-4b9c-bbfb-bd1b9c562050',
  'langcode' => 'en',
  'status' => true,
  'dependencies' =>
  array (
    'module' =>
    array (
      0 => 'mymodule',
    ),
  ),
  '_core' =>
  array (
    'default_config_hash' => 'vvt7bzrXEwxrTfY--axzCfSRPzggH0o4hahUY9Kh0z0',
  ),
  'id' => 'mymodule_foo_action',
  'label' => 'An example action',
  'type' => 'webform',
  'plugin' => 'mymodule_foo_action',
  'configuration' =>
  array (
  ),
)

Then I could just copy the output and paste it into a post-update hook. My IDE makes it easier to prettify the code to match Drupal's coding standards and switch to PHP's newer short array syntax. I also removed all the bits that I could leave to be dynamic; like the uuid, _core, and empty configuration properties in the action example above. I can then either use the entity storage for my type of entity to save the configuration, or just use the Configuration Factory service more directly:

$data = // (Paste & adapt the output from drush for this variable.)
// Example of using the config factory.
$config = \Drupal::configFactory()->getEditable('block.block.myblock');
// Using `setData()` will replace the entire config array. We could instead 
// use `set()` for individual properties.
$config->setData($data)->save();
// Alternatively use the entity type storage and specific methods, when
// available. Create new entities with `$storage->create($settings)->save()`.
$storage = \Drupal::entityTypeManager()->getStorage('block');
$storage->load('myblock')->set('settings', $data['settings'])->save();

We tend to automate Drupal core's configuration management on most of our projects - but not always. Even where we don't, there is usually some config that we exclude from the automated management - usually to allow clients to make changes in the admin UI without needing to access the codebase. So this is a handy trick to have available when you just need to script some changes outside of config management.

Under the hood, the consolidation/output-formatters library is what provides output formatters. If you run drush help version you can get a list of other standard formatters, which includes:

yaml

The key-value format usually used for configuration exports.

csv

Comma-separated values; ideal for simple lists

php

The format that PHP's internal serialize() method produces.

var_dump

Probably my new favourite; as produces coloured syntax highlighting in the terminal output! It is powered by Symfony's VarDumper component. I have found this particularly useful recently when debugging the output from a remote API endpoint, to help me visually parse clumps of output.

As a bonus, this can be useful for quickly loading up an entity to inspect its field values:

...which feels rather like a good case for a custom drush command, just taking an entity type and ID as arguments ;-)

What other handy uses of specifying an output format can you come up with? Let me know!