Getting acquainted with Drupal Console

What is the Drupal console?

This is a command line interface (CLI), designed to generate standard code, interaction and debugging Drupal.

The Drupal console makes use of the Symfony console and other third-party components that automatically generate most of the code needed for the Drupal 8 module. In addition to this, the console allows you to interact with your Drupal project.

Why should I read this?

Drupal 8 is much more technically advanced than its predecessors and mastering the complexity of some tasks might discourage anyone. Drupal console is a set of utilities, which allows to greatly simplify the life of the developer. Writing a module for Drupal 8 requires more template code and a lot of things you need to know to just start creating a new module. These tasks can be routine and boring and therefore lead to an increase in potential errors. Fortunately, a large amount of new code can be automatically generated using the Drupal console, without the possible risks and copy-paste errors and waste a heap of valuable time.

How does the Drupal console help?

Generating the code and files needed for Drupal 8.
Investigate and debug the system.
Interact with the installation of Drupal.
To study Drupal 8 (for this, the --learning key is used)

Where can I find the Drupal console project?

Receiving a project

You need to install 2 things to make DrupalConsole work:

DrupalConsole Launcher
DrupalConsole itself

Why do I need Launcher?

This is a global application that allows you to run the Drupal command from any subdirectory of your project. Without this, you will have to run the command only from the root directory of the site.

Installing Drupal Console for each of your projects

Starting with Drupal 8 RC DrupalConsole should be installed for each site.

Using the project

The Drupal console provides two types of commands:

Global launcher commands: these commands can be run outside of the root directory of Drupal 8.
Commands related to a particular site: these commands must be executed inside the root directory of Drupal 8.

Running the Drupal console commands outside the root directory of the site

You can run the Drupal console commands from any directory on your system using the --root option to set the root directory of Drupal.

drupal --root=/var/www/drupal8.dev cr all

It is worth noting that there may be a warning if the console does not run Drupal from the site's root directory.

How to copy configuration files?

The first task that you will need to do after installing the Drupal console is to start init command. This command will copy the project's configuration files to your computer. By changing the values in these files, you can change the behaviour of the Drupal console.

drupal init [--override]

The first question you will see after running this command is "Select destination to copy configuration" and the set of options will vary depending on the directory where you run this command:

Running this command is not from the root directory of the site you will see:

Select destination to copy configuration:
  [0] /etc/console/
  [1] /Users/username/.console/
 >

Running this command from the root directory of the site:

Select destination to copy configuration:
  [0] /etc/console/
  [1] /Users/username/.console/
  [2] /path/to/drupal8.dev
 >

The rest of the options do not depend on the directory in which the command was run.

How to download, install and maintain Drupal 8 with Drupal Console?

The easiest way to test Drupal 8 on your machine is as follows: drupal quick:start.

Note that before doing this, you need to run drupal init to copy ~/.console/chain/quick-start.yml to your local system.

The chain command will help automate the start of the command, allowing you to specify an external YAML file containing the description, options and arguments of several commands and run this list of commands according to the sequence of their description in the file.

The contents of the provided file ~/.console/chain/quick-start.yml are as follows:

# How to use.
# quick:start --directory="/path/to/drupal-project/"
# quick:start --directory="/path/to/drupal-project/" --profile="minimal"
# quick:start --repository="acquia/lightning-project:^8.1" --directory="/path/to/drupal-project/" --profile="lightning"
command:
  name: quick:start
  description: 'Download, install and serve a new Drupal project.'
vars:
  repository:
    - drupal-composer/drupal-project:8.x-dev
    - acquia/lightning-project
    - acquia/reservoir-project
  profile: standard
commands:
  # Create Drupal project using DrupalComposer.
  - command: exec
    arguments:
      bin: composer create-project %{{repository}} %{{directory}} --prefer-dist --no-progress --no-interaction
  # Install Drupal.
  - command: exec
    arguments:
      bin: drupal site:install %{{profile}} --root=%{{directory}} --db-type="sqlite" --no-interaction
  # Start PHP built-in server.
  - command: exec
    arguments:
      bin: drupal server --root=%{{directory}}

This configuration will run several commands that download and install Drupal using SQLite, and in the end, will launch the built-in PHP server. Now you only need to open the following URL in the browser 127.0.0.1:8088.

You can duplicate or make changes to the YAML file to load modules: module:download, install modules: module:install, import configs: config:import and restore your database database:restore or any other command provided by the Drupal console, or custom the command provided by your own module.

How to use the Drupal Console in a multi-site installation?

Drupal Console provides support for multi-site installations. To debug multi-sites, use the debug:multisite command and the -uri option to interact with multi-site installations we use at this moment.

How to get the list of all known sites by console when using a multi-site?

The Drupal console uses the sites/sites.php file to determine the multisite configuration. For an example, see the files sites/example.site.php.

drupal debug:multisite

+---------------------+--------------------------------+
| Site                | Directory                      |
+---------------------+--------------------------------+
| drupal8.dev         | /var/www/drupal8.dev/default   |
| drupal8.multi.dev   | /var/www/drupal8.dev/multi.dev |
+---------------------+--------------------------------+

Sites are written using the format: <port>.<domain>.<path>

How to run Drupal Console commands in multisite?

drupal --uri=http://drupal8.multi.dev cr all
drupal --uri=drupal8.multi.dev cr all

Use of aliases

The Drupal console allows you to run commands on your local server, but in fact, you run them on a local, remote or virtual (VM, Docker) Drupal site using aliases.

Site aliases use YAML files to provide a set of predefined options using abbreviated names.

To determine a remote site, use the type:ssh. In this case, the ssh command will be used to run commands on the remote server.

You can obtain site aliases using the following paths:

Globally: ~/.console/sites/
For each site: /path/to/site/console/sites/

Valid options for site aliases

root: The root directory of the Drupal project.
host: The domain name of the remote system is not required for local sites.
port: The port that is used when connecting to the ssh protocol (by default is 22).
user: The username for the ssh connection.
options: An array of valid console options.
arguments: An array of arguments.
extra-options: Used only if additional options are required, for example, the authentication method and/or an alternate identification file.
type: The type of site to interact with. Valid options are local, ssh, container. The local option is used by default.

Configuring the Local Environment

Using site aliases requires a specific local setting.

Global Configuration

A global configuration can be provided by a copy of this file ~/.console/config.yml. This information is grouped by remote key.

application:
  ...
  remote:
    user: drupal
    port: 22
    options:
    arguments:
    type: ssh

Configure a specific site

The site alias configuration can be provided by adding the YAML file /path/to/site/console/sites/sample.yml or ~ /.console/sites/sample.yml.

local:
  root: /var/www/drupal8.dev
  type: local
dev:
  root: /var/www/html/drupal
  host: 127.0.0.1
  user: drupal
  type: ssh
prod:
  root: /var/www/html/docroot
  host: live.drupal.org
  user: drupal
  type: ssh

Debugging Sites using Drupal Console

All known site aliases can be obtained with the debug:site command.

drupal debug:site

+--------------------+-----------------+------------------------+
| Site               | Host            | Root                   |
+--------------------+-----------------+------------------------+
| sample.local       | local           | /var/www/drupal8.dev   |
| sample.dev         | 127.0.0.1       | /var/www/html/drupal   |
| sample.prod        | live.drupal.org | /var/www/html/docroot  |
+--------------------+-----------------+------------------------+

Configuration details can be obtained by specifying the site name as an argument to the debug:site command.

drupal debug:site sample.dev

user: drupal
port: 22
options:
arguments:
root: /var/www/html/drupal
host: 127.0.0.1
type: ssh

As you can see, the global configuration and configuration of a specific site are usually combined during the debugging of the site. You can override any global configuration value by adding keys to a specific site.

How to use the Drupal console for a remote version of the site?

Site aliases can be specified using the --target parameter and the name of the site with which you want to interact.

drupal --target=sample.dev cr all

Also, you can specify site aliases using the obsolete @ identifier.

drupal @sample.dev cr all

Connecting to a virtual working environment

You can connect to a virtual machine or a Docker by passing values to the extra-options and type keys.

Example for DrupalVM

dev:
  root: /var/www/drupalvm/drupal
  host: 192.168.88.88
  user: vagrant
  extra-options: '-o PasswordAuthentication=no -i ~/.vagrant.d/insecure_private_key'
  type: ssh

Example for Drupal4Docker

dev:
  root: /var/www/html
  extra-options: docker-compose exec --user=82 php
  type: container

When using type:container, you must specify values for the host and user.

Examples of using Drupal Console

Installing the module: module:install

drupal module:install [arguments] [options]
moi

Uninstalling the module: module:uninstall

drupal module:uninstall [arguments] [options]
mou

Clearing the cache: cache:rebuild

drupal cache:rebuild [arguments]
cr

Generating a new module code: generate:module

drupal generate:module [options]
gm

Generate code to create a new field: generate:plugin:field

drupal generate:plugin:field [options]
gpf

Conclusion

It was a description of the main features of the Drupal console, a fairly powerful and convenient tool. For more information, I suggest you refer to the official documentation, which can be found here.

Comments