Learning Drupal Console for Drupal 8 Development (or How Sloths Don’t Get Enough Play)

November 04, 2018
By Bounteous

Welcome! If you’re an old pro at Drupal, you’ve likely used Drush before. Drupal 8 brings tons of new improvements and features. One of them is Drupal Console. This tool is not a replacement for Drush, it’s a new BFF! Drupal Console comes from the Symfony world and helps you do plenty of awesome things such as generate boilerplate code, set configuration, and run your own command-line commands.

Prerequisites 

So let’s get started. First, you’ll need Composer. Simply put, Composer is PHP’s dependency manager. It’s analogous to NPM for Node JS packages or Bundler for Ruby.

If you already have Composer, then great! But if you need to install it, this is how:

curl -sS https://getcomposer.org/installer | sudo -H php -- --install- dir=/usr/lo- cal/bin --filename=composer 

This set of commands will install Composer globally for Linux/Unix/OSX. Now you should be able to run the composer --version command to see the latest version of Composer running on your system. If you’re still having trouble, you can troubleshoot on the Composer site here.

Once you have Composer, you can install both Drush and Drupal Console and this is the preferred method.

Drush:

composer global require drush/drush:7.* 

Now wait a second, this looks like Drush 7, you might say. Well, it is. That’s because personally, I’m still doing mostly Drupal 7 development and I’ll bet you are as well. Per an awesome article by Lullabot’s Karen Stevenson, I like to have multiple versions of Drush readily available locally if I’m not working in a Vagrant environment. This makes it easy to handle different major versions of Drupal by using simple aliases such as drush (for default Drush 7.* version) or drush8 for Drush 8.* version.

Let’s set that up quickly. Since we already have Drush 7 as our default we can just drush some-command if dealing with a Drupal 7 site. In order to install Drush 8 for our Drupal 8 fun, let’s do this:

mkdir ~/drush8 

cd ~/drush8 

composer require drush/drush:dev-master 

Now you’ll need to create a BASH alias for Drush 8 so that you can use it easily. To do that, open your .bash_profile in a text editor and add this line:

alias drush8='~/drush8/vendor/bin/drush' 

Test out your alias to make sure it’s working the way we expect. You may have to source ~/.bash_profile or open a new terminal window for the new alias to take effect.

drush8 --version 

And now test out your default version to make sure it’s Drush 7.*

drush --version 

Installing Drupal Console 

Great, now we’re ready to install Drupal Console (finally!). You can find all the relevant Drupal Console documentation here as well.

composer global require drupal/console:@stable 

echo "PATH=$PATH:~/.composer/vendor/bin" >> ~/.bash_profile 

drupal --version 

Ready to roll!

Using Drupal Console to Quick-Start a Local Site 

Now, straight from the Drupal Console documentation, the first thing you should do:

The first task you should do after installing Drupal Console is to execute the init command. Executing this command will copy the project configurations files to your ~/.console/ directory. Overriding values on these copied files is how you can change DrupalConsole behavior. 

That command looks like this:

drupal init --override 

Here’s where the fun begins! Let’s spin up a Quick-Start Drupal 8 site, right from our local machine. Drupal Console creates this using the quick-start.yml configuration file that we copied to ~/.console. It utilizes a flat-file sqlite database so no Apache is needed here. Create a directory for your project if you want to, but Drupal Console creates one for you and names it drupal8.dev/ by default.

drupal chain --file=~/.console/chain/quick-start.yml 

Drupal Console will now download the latest Drupal 8 release and begin serving it at localhost:8088. The port number may be different on your system, but you can always check that by checking the message in your terminal window. Mine reads:

[OK] Your Drupal 8 installation was completed successfully 

[OK] Executing php from /usr/local/php5-7.0.2-20160108-102134/bin/php. PHP 7.0.2 Development Server started at Mon Feb 8 12:07:38 2016 Listening on http://127.0.0.1:8088

This means that I am running PHP 7.0.2 on my local machine and the built-in PHP server is available in my browser at localhost:8088.

Now you can log into your site by visiting localhost:8088/user/login and using admin for the username and admin for the password. Again, these are the defaults provided in your ~/.console/chain/quick-start.yml config file. (Feel free to copy this file and customize it to your liking.)

You can also explore the Drupal server command more here.

Using Drush with Drupal Console 

OK, so what about Drush? Well, the truth is we can use Drush 8 and Drupal Console interchangeably in some cases. For instance, let’s say we ctrl + c our PHP server from before to shut it down. How do we get it started again? We could do it two ways. In the root of our project we could either run:

drupal server 

Or we could run:

drush8 rs 

Please note that each command uses a different port to serve up the site. Console uses :8088 here while Drush uses :8888. Also remember our Drush command is now drush8 because of our handy alias from earlier.

Cool, now we have two different tools to do the same job. Wat?

But wait! Here’s the cool stuff.

Generating a Custom Module 

Probably the most useful thing Drupal Console can be used for is the generation of boilerplate code. So let’s generate a custom module.

drupal generate:module 

Drupal Console then leads you through a command-line questionnaire and does all the dirty work for you. Each question has a default value in brackets. If you are OK with the default, you can just hit enter to move to the next question.

The only problem now is that your module is missing a controller. Drupal 8 modules require controllers to hook up the modules. No worries, Console’s got us covered. Try this:

drupal generate:controller 

You will then be welcomed to the Drupal Controller generator and you can answer some more questions. Fantastic. Now, assuming we’ve used mostly defaults and named everything after New Module (with no composer.json file or declared dependencies), we’ve got a module that looks like this:

modules/custom 

-new_module -Tests 

-Controller NewModuleControllerTest.php 

new_module.info.yml new_module.module new_module.routing.yml -src 

-Controller 

NewModuleController.php 

Done. Now you can use your old buddy Drush to enable the module using drush8 en new_module.

Generating a Custom Theme 

This is going to be just as fun! To generate the custom theme:

drupal generate:theme 

Please note that if you don’t feel like filling out the entire questionnaire you may absolutely pass in your answers as arguments to the consolecommand, as such:

drupal generate:theme --theme=Sloth --machine-name=sloth --description='A slow and steady theme for Drupal 8' --core=8.* --package='Custom Themes' 

This still leaves a few questions that the generator wants answered such as Global Library and Base Theme. You will still have to answer those.

So what does drupal generate:theme do? What do any of these commands do? They render these templates for us in the appropriate places within our Drupal 8 project and replace the defaults with any arguments we may have provided in our command line statement or in “filling out” the generator’s questionnaire. So for a custom theme we now see:

sloth.info.yml 

sloth.theme 

If you provided parameters for breakpoints you would also see a sloth.breakpoints.yml file.

Creating Your Own Commands 

Now that you’re feeling more comfortable with this process–after all, we’ve generated a new site, a new custom module, and a brand new custom theme all with a few commands–you may be wondering how you can take it to the next level. Drupal Console is really, really helpful. Let us bend it to our will!

Get this, there is even a generate command for commands.

drupal generate:command 

I love it. This runs us through a list of questions as well.

Enter the module name [sloth]: 

Enter the command name [sloth:default]:Enter the Command Class. (Must end with the word 'Command'). [DefaultCom- mand]:Is the command aware of the drupal site installation when executed?. (yes/no) [yes]:Do you confirm generation? (yes/no) [yes]: 

Now we have a custom command set-up to run when our custom module is enabled (don’t forget to enable that module before you run the command!). Now when we run drupal sloth:default in our terminal we get this output:

Hello, I am a new generated command for the module: sloth 

This just gets you started. Now get creative and incorporate Drupal Console into your development!