Drupal Console is a fantastic tool for helping to write Drupal 8 modules; of that there is little debate. Its "generate" functionality takes much of the pain out of setting up the scaffolding for many types of Drupal 8 modules, and in the process that alone saves developers a significant amount of time. When using Drupal Console, module developers usually don't have to worry too much about basic "use" statements, PSR-4 directory structures and file names, annotations, and much boilerplate code that is normally part of the development process.
Here at DrupalEasy, we're such big fans of Drupal Console, we've designed our "Introduction to Drupal 8 Module Development" full-day workshop around it (<shameless-plug>we're offering it at DrupalCon Baltimore</shameless-plug>). To some newcomers, getting Drupal Console up-and-running can be a bit tedious as there are a few ways to install it. Plus, the distinction between the Drupal Console Launcher (global executable) and the rest of Drupal Console can be confusing.
This blog post's goal is to describe one method for installing Drupal Console Launcher and Drupal Console on an existing Drupal 8 site. This example will not utilize a fully-Composer-ized™ Drupal 8 install (possibly expect a second blog post once best practices evolve a bit more - see below), rather it will focus on a "standard" (old school?) Drupal install via traditional methods. That being said, you'll still need Composer installed, as we're going to use it to install part of Drupal Console (a bit confusing, I know).
So, let's assume you have a local Drupal 8 instance installed and up-and-running on your local machine. For this exercise, your local development environment doesn't matter all that much unless you're running a virtualized solution. If you are, you're probably clever enough to modify these instructions appropriately. In the past, I've often used Acquia Dev Desktop when teaching new students to use Drupal, so I can confirm that these instructions work just fine in that environment. The only real prerequisite is that Drupal Console requires PHP 5.5.9 (on the command line) or higher.
As mentioned above, there are actually two parts of Drupal Console that users are strongly recommended to install - the "Drupal Console Launcher" and "Drupal Console" itself. The launcher is installed globally on your machine, while Drupal Console is installed separately on each of your local Drupal 8 projects. This is a bit different than earlier (pre-release-candidate) versions of Drupal Console, and can be a source of confusion.
Installing the launcher should be pretty straight-forward on Mac or Linux as there's a simple curl command:
curl https://drupalconsole.com/installer -L -o drupal.phar
Once downloaded, run:
mv drupal.phar /usr/local/bin/drupal
chmod +x /usr/local/bin/drupal
These commands will move the launcher into your /usr/local/bin directory and set it to be executable by everyone. You may need to use "sudo" with the "mv" command.
On Windows the project documentation is pretty good (as well as this Evolving Web blog post by Dave Vasilevsky). With just the launcher installed, you're limited to just a few Drupal Console commands involving installing (via the very cool "chain" command) Drupal, working with generic .yml files, and some Drupal Console non-site-specific functionality.
You can verify the launcher is installed properly by doing a
drupal about command from anywhere in your file system - this will show you the current version of the launcher as well as some available commands.
It is the launcher's job to provide the global executable for which to run Drupal Console commands against any site on your system from any location (using the --root option - similar to the Drush --uri option) or by running the command from inside the site root.
But, in order to run most Drupal Console commands (including the glorious "generate" related ones), each Drupal 8 site on your local must have Drupal Console (and its dependencies) installed. Luckily, this is pretty easy to do as well. Navigate into your site root, then (because Drupal 8 ships with composer support) run the following command to install:
composer require drupal/console:~1.0 --prefer-dist --optimize-autoloader --sort-packages
This will modify your site's composer.json and composer.lock files with their new Drupal Console dependency and then download Drupal Console and all of its dependencies into the site's vendor directory. That's it - you're done! Remember - you must do this for each Drupal 8 site on your local.
You can test the Drupal Console goodness with a
drupal site:status command (similar to
drush status). Once confirmed, you're good to start using Drupal Console to help you generate all those custom modules.
Updating Drupal Console
Looking at the Drupal Console project page, it's easy to see that it's still a work in progress (there are commits almost daily). So, the next (hopefully) obvious question is "how do I update Drupal Console"? Well, first off, remember that there are now two things to update - the global launcher as well as all the Drupal Console stuff in your site's vendor directory.
To update the global launcher, navigate to somewhere outside of your Drupal 8 site (your home directory works) and run
drupal self-update (you may need to use "sudo").
To update your site's Drupal Console "stuff" (I'm struggling to figure out exactly what to call it - "files"? "dependencies"?, "code"? I'm open to suggestions), navigate to your site root and, remembering that we used Composer to install it, run the following command to update it:
composer update drupal/console --with-dependencies
Keep in mind that you'll need to do this for each Drupal 8 site on your machine.
So, what will the differences in this blog post be once we all fully embrace Composer as the-one-and-only-way-to-manage-Drupal-projects? I'm not entirely sure there will be any. Stay tuned.