Introduction to DrupalConsole

DrupalConsole is a command line interface (CLI) tool for the generation of boilerplate code, speeding up of administration tasks, and interaction with a Drupal 8 site. A similar tool, Drupal Shell (Drush), grew out of the need for managing Drupal sites from the terminal, which reduces the time it takes to perform numerous administrative tasks, without many clicks and page refreshes in the browser.

With the decision to build Drupal 8 on existing industry-standard tools, such as Composer and Symfony components, DrupalConsole was the natural evolution for a CLI tool. Unlike Drush, which has been around since Drupal 4.7, currently, DrupalConsole is only compatible with Drupal 8.

While retaining features that are familiar to developers using the console command in Symfony and Sylius or artisan in Laravel, it has added others for the Drupal CMS, including some similar to the ones in Drush. The CLI tools all derive from the Console Component, one of several Symfony components that can be used in other PHP projects.

Installation

Make sure you have Composer installed and working. This tutorial assumes you have a working knowledge of Drupal 8, but we are going to do a clean installation of Drupal 8 with Drupal Console, version 1.0.0-rc19 at the time of writing this article.

There are 2 parts to this tool — DrupalConsole Launcher (or Launcher) and DrupalConsole. The launcher is a globally executable program. The console is the suite of tools that run commands, and it is installed in each Drupal 8 site project. See the Drupal Console Documentation for further details.

Briefly, to install DrupalConsole Launcher, open a terminal, and run these commands:

curl https://drupalconsole.com/installer -L -o drupal.phar
mv drupal.phar /usr/local/bin/drupal
chmod +x /usr/local/bin/drupal

Confirm that the following gives you something meaningful:

drupal --version

Now, we are going to install Drupal together with Drupal Console. Change directory to where you usually have websites. For example, my username on a Mac is "dakala" and this is what I will do:

cd /Users/dakala/Sites/

Yours may be /var/www/ or something like that. Inside the directory, create a Drupal 8 project with Composer by executing the following:

composer create-project drupal-composer/drupal-project:8.x-dev xteam --prefer-dist --no-progress --no-interaction

This creates the xteam directory (you may call this anything you like) and downloads the Drupal 8 source code together with DrupalConsole into it.

If you would like to use an existing Drupal 8 installation, from the terminal, go to the directory and run:

composer require drupal/console:~1.0 --prefer-dist --optimize-autoloader

Check the composer.json file inside the directory for a line like this, which indicates that the Drupal Console package has been downloaded to the vendor folder:

// composer.json

"require": {
    "drupal/console": "~1.0",
}

Still in the new directory, try the following:

drupal

Among other things, you will see the following 4 commands:

drupal init
drupal site:install
drupal list
drupal self-update

drupal init

drupal init will copy configuration files for DrupalConsole from /your/web/root/project_name/vendor/drupal/console-core/config/dist/phpcheck.yml to a destination you specify. Run the command and you will be given a set of prompts. Choose any of the three destinations by typing, 0, 1 or 2. I like the option of creating the .console directory in my home directory which is 1. Also, I answered "yes" to all other questions.

After running it, if you go to the destination you selected, you will find the copied files. This is what I've got:

.
├── aliases.yml
├── chain
│   ├── create-data.yml
│   ├── form-sample.yml
│   ├── quick-start.yml
│   ├── sample.yml
│   ├── site-install-placeholers-env.yml
│   ├── site-install-placeholers.yml
│   ├── site-install.yml
│   ├── site-new.yml
│   ├── site-update.yml
│   ├── update-command-data.yml
│   └── update-gitbook.yml
├── config.yml
├── console.rc
├── drupal.fish
├── phpcheck.yml
├── router.php
├── site.mode.yml
└── sites
    ├── drupalvm.yml
    └── sample.yml

Most of the files are in YAML format. Each file inside the chain folder represents a single command, which in turn may invoke one or more commands with different options and arguments to be executed in order.

drupal site:install

Open site-install.yml. There is only one command — site:install — with arguments and options configured, which will install Drupal with those settings. Without using this file, running drupal site:install on the command line will take you through an interactive process of site installation, presenting you with some questions and options. The default will do in most cases:

The same thing can be achieved with the chain command and a path to a YAML file with the configuration settings. For example:

drupal chain --file=/path/to/.console/chain/site-install.yml

You may try one of the methods above, but I suggest the interactive process with the SQLite option, because it saves time. After the installation has been completed successfully, there is a quick way to view the site. Run this:

drupal server

This command starts the built-in PHP web server. You can visit http://127.0.0.1:8088/ and log in with admin/admin. Stop the server.

Open quick-start.yml and check each of the three commands that are chained into the one called quick:start. They will create a new Drupal project, install and serve it with the PHP web server.

Look at the instances of % in the file. These are placeholders for the actual values you will have to specify when running the command. % means you must specify the root directory of the site. % signifies that the profile placeholder is optional. If you do not provide it, standard will be used by default. The same goes for %, which defaults to the Drupal project as there are other Drupal distributions which can be installed too.

To install a second Drupal site, all you need is the following:

drupal quick:start --placeholder="directory:/path/to/your/new/project/"

You may explore the other configuration files later.

drupal list

We have seen a couple of commands in action — drupal site:install, drupal chain and drupal server. To see a list of available commands, run this:

drupal list

This lists all available commands with a short description of what each one does. Broadly speaking, these commands fall into the following 4 categories:

1. Informative

These give you some information about your site. Some of these end in "debug" e.g config:debug. Running drupal list | grep :debug will filter the list.

Try runnning this:

drupal config:debug

You get a list of names of all your configuration entities. To find out more about any of them, just re-run the command with the name in front of it. For example, to find out more about system settings:

drupal config:debug system.site

That command gives me this:

system.site
uuid: e7e60d36-c866-4de6-b7b2-d41dc6a02f7f
name: 'Drupal 8: X-Team'
mail: admin@example.com
slogan: ''
page:
  403: ''
  404: ''
  front: /node
admin_compact_mode: false
weight_select_max: 100
langcode: en
default_langcode: en
_core:
  default_config_hash: AyT9s8OUcclfALRE_imByOMgtZ19eOlqdF6zI3p7yqo

2. Administrative

Rebuild cache, install/uninstall modules, import/export site configuration, create/delete users etc are some administrative tasks that can be performed with Drupal console commands. Let us try one for creating new users:

drupal user:create

Follow the prompt at each step and at the end you will see a summary of the new user that has just been created. Something like this:

3. Creative

These are commands that:

• generate content, e.g. drupal create:users
• generate code, e.g. drupal generate:module

Try running:

drupal list | grep generate:

That gives a long list of commands to speed up development. Type a command, answer some questions and get valid boilerplate code.

4. Supportive

Some commands offer support by improving developer experience. We have seen drupal server, which starts the built-in server to run a development site in no time.

Then there is drupal shell. Try it. It prints out something like "Psy Shell v0.8.5 (PHP 5.6.30 — cli) by Justin Hileman" and drops you into a prompt. Type quit or exit and hit Enter.

Psy Shell is a Read-Eval-Print-Loop (REPL) for PHP that can be used for interactive debugging of PHP scripts.

drupal self-update

This command is for updating the DrupalConsole Launcher. Running composer update drupal/console --with-dependencies will update the console and its dependencies. If you run it now, it will not do much, since it is a fresh installation which should be the latest version. If I run it later, I might get some updates.

Conclusion

We have taken a brief tour of DrupalConsole and executed a couple of commands with a lot of areas left unexplored. However, the aim of this article is to introduce this great tool, designed to ease development and interaction with a Drupal 8 site.