Drupal underwent a sea change moving from 7 to 8. Although the stock administrative interface and site building concepts will look familiar to long-time users, much is different beneath the surface. This requires a different approach to site building and management for your Drupal projects.
Following are tips for standing up a Drupal 8 site locally for test and evaluation, as well as some guidelines for running a complete build. The code instructions are geared for Unix-based systems such as MacOS or Linux, but can be adapted for Windows.
Initial Setup
To set up the local environment, we will be using Drupal VM. You will need to download and install:
Vagrant and VirtualBox are downloaded and installed via package installers, and require little time to set up.
Since Composer will be downloaded as a PHP package, it’s best to follow the listed instructions for downloading Composer.
This changes frequently, so it’s best to check the above link for the latest, and run that code from your user root. The code should look like this (often with a different hash):
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '48e3236262b34d30969dca3c37281b3b4bbe3221bda826ac6a9a62d6444cdb0dcd0615698a5cbe587c3f0fe57a54d8f5') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
When this has successfully completed, run this: mv composer.phar /usr/local/bin/composer
Moving an application to your /usr/local/bin folder enables you to use it without declaring a PATH variable in your ~/.bashrc file.
Then: Either run this in your same session:
source ~/.bashrc
Or close your Terminal window, reopen, and enter this to test:
composer --version
If all is installed properly, the version should display.
Recommended Addition
It is also a good to install Vagrant VirtalBox Guest by running:
vagrant plugin install vagrant-vbguest
This can help avoid issues such as your browser not being able to find your local build.
With these items now set up, we’ll go to building the local environment:
Setting Up a Drupal 8 Local:
For this demonstration, we will be using the build provided at Drupal VM. The drupal builds managed here are built off the Composer template for Drupal Projects
For those wishing to look at other options, the Composer Scaffold method build is available here.
To install the Drupal VM demonstration build, from a new Terminal session:
cd Sites
git clone https://github.com/geerlingguy/drupal-vm.git
cd drupal-vm/
chmod -R 777 drupal-vm
Running this wards off any potential file/folder permissions issues.
vagrant up
Note: This process may take ~10-15 minutes, depending upon your computer hardware and Internet connection.
Once this process has run successfully, you should be able to see your local Drupal 8 build at:
http://drupalvm.test
Version Control
While using a version control system (VCS)—such as Git—is an essential component of team-based workflows, it’s also advisable to use them on solo projects. The reason for this is that due to the number of dependencies installed when running a Composer-based build, doing a manual rollback can be a frustrating and tedious process. Unless you’re doing a quick throw-away spin-up for testing, such as this example, initiating a git reset --hard HEAD makes things much easier when problems are experienced.
Composer Tasks in Drupal 8
A major change in Drupal 8 was the move to Composer-based dependency management. For deployments and local development, this offers an advantage where file depedndencies aren’t added to the base repository, but only installed when needed. This keeps file sizes smaller and transfers quicker.
To manage basic tasks in Composer, these are standard commands:
composer install This will run the installation specified in your project’s composer.json and composer.lock files.
composer require [vendor]/[project] [version number-if needed] This is how a project (such as a module) would be added to added to your build. The version number will specify which version to use, if you need to do this.
composer remove [vendor]/[project] [version number-if needed] This is how a project (such as a module) would be removed from your build.
composer update [vendor]/[project] [version number-if needed] This is how you update a specific project, to a specific version number.
--with dependencies This flag can be added to the end of an update or require call to make sure all dependencies get installed. A good example of this would be when updating Drupal core, such as like this: composer update drupal/core --with-dependencies
composer clear-cache This is clears the Composer caches, which should be run when mystifying errors crop up.
Use with caution/avoid: composer update Used alone, this will update ALL items in your build (unless a specific version is set or locked). This can have unexpected adverse consequences, and is best avoided.
Drush in Drupal 8
In Drupal Core 8.4+, it is no longer possible to call upon a global Drush installed in your system. This was done to avoid the issues of version mismatches when running multiple projects. Like modules, Drush is now a Composer-managed project, and is set in your project’s composer.json.
To access Drush in this test project, go to the site root (go to drupal/ from your site root), then run:
vagrant ssh This will put you inside the Drupal VM, where commands can be executed. This is best done in a separate Terminal window from your Composer/VCS commands.
Common Drush Commands:
drush cr Drush Cache Rebuild. This clears all your site’s caches, and replaces the drush cc all in older versions of Drush.
drush cron Runs the system cron functions for your site.
drush en [project name] Enables modules.
drush sql:dump Will run a database dump into your Terminal session.
drush sql:dump --result-file=../../drupal_backup.sql --gzip Will run create a Gzipped SQL archive file of your database back two levels up from your project root.
What Drush no longer does: drush dl [project name]
drush up drupal These functions are no longer allowed, due to the new Composer workflow.
For a more complete listing of Drush 9 commands, refer to Drush Commands.
Installing and Removing Modules
Drush no longer can install modules, so older commands such as drush dl [project name] will no longer work.
Instead, the process is to run is via Composer (or the GUI, but not recommended). This is because contributed projects built to Drupal 8 specifications can have numerous dependencies managed via Composer, which would be tedious to manage manually—not to mention being a challenge to troubleshoot.
Project Example—Pathauto Module
For instance in this demo build (from the project root): cd drupal (this is the site project root)
composer require drupal/pathauto
The way the syntax here is set up is: composer require [vendor]/[project] [version]
This task installs the module, and any dependencies needed.
Then, in your CLI session in the VM: drush en pathauto
This enables the module, and any dependencies.
Uninstalling modules:
As with enabling modules, the process has changed in D8. First, and this is important, uninstall the module in the GUI (go to [project name]/admin/modules/uninstall, or via Drush:
drush pm-uninstall pathauto
To remove a module: composer remove [project name]
composer remove drupal/pathauto
Configuration Management
Another major change to Drupal 8 is the Configuration Management Initiative (CMI). Here, older processes and workflows such as those managed with the Features module have been replaced with core functionality.
An advantage of CMI is that various configurations can be shared out between different build environments depending upon their specific needs. A common example of this would be having Google Analytics tracking running on your production site, but not on staging or local development. Depending upon your project needs, the Configuration Split module can be very helpful for managing this.
Hopefully this will help you on your way to launching your own Drupal 8 Projects. Based on feedback from workshops, I will also be updating this.
Additional Resources
Here are links to some articles on using Composer in Drupal 8:
Use Composer with Your Drupal Project This provides basic tips, plus pointers on how to move an existing D8 project over to Composer management after the fact.