Search icon
Cart icon
Close icon
You have no products in your basket yet
Save more on your purchases!
Savings automatically calculated. No voucher code required
Arrow left icon
All Products
Best Sellers
New Releases
Learning Hub
Free Learning
Arrow right icon
Over 7,000 tech titles at $9.99 each with AI-powered learning assistants on new releases
Drupal 8 Development Cookbook - Second Edition
Drupal 8 Development Cookbook - Second Edition

Drupal 8 Development Cookbook: Harness the power of Drupal 8 with this practical recipe-based guide, Second Edition

By Matt Glaman
$39.99 $9.99
Book Sep 2017 430 pages 2nd Edition
$39.99 $9.99
$15.99 Monthly
$39.99 $9.99
$15.99 Monthly

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now

Product Details

Publication date : Sep 26, 2017
Length 430 pages
Edition : 2nd Edition
Language : English
ISBN-13 : 9781788290401
Category :
Languages :
Concepts :
Table of content icon View table of contents Preview book icon Preview Book

Drupal 8 Development Cookbook - Second Edition

Chapter 1. Up and Running with Drupal 8

In this chapter, we will get introduced to Drupal 8 and cover the following recipes:

  • Installing Drupal
  • Using a distribution with Drupal
  • Installing modules and themes
  • Using multisites in Drupal 8
  • Tools for setting up an environment
  • Running tests: Simpletest and PHPUnit


This chapter will kick off with an introduction to installing a Drupal 8 site. We will walk through Drupal's interactive installer. We will cover installing Drupal using a command-line tool called Drush. Drupal provides two installation types: standard and minimal. Throughout this book, we will use the standard installation.

Once we have installed our Drupal 8 site, we will cover the basics of extending Drupal. We will discuss using distributions and installing contributed projects, such as modules and themes. We will also include uninstalling modules, as the process for uninstalling modules has changed in Drupal 8.

This book will involve a hands-on example for working with Drupal 8, and this chapter will provide information on setting up a local development environment. This chapter will also provide recipes on how to set up a Multisite installation in Drupal 8 and run the available test suites.

Before we get started, you should install Composer. Composer is the de facto package management tool for PHP. In case you are unfamiliar with Composer, it is just like using Gems for Ruby, npm for Node.js, and Bower for frontend libraries. Go to the Composer documentation to learn how to install Composer globally on your system:

Installing Drupal

There are many different methods to download Drupal and install it. In this recipe, we will focus on downloading Drupal from and setting it up on a basic Linux, Apache, MySQL, or PHP (LAMP) server.

In this recipe, we will set up the files for Drupal 8 and step through the installation process.

Getting ready

Before we start, you will need a development environment that meets the new system requirements for Drupal 8:

  • Apache 2.0 (or higher) or Nginx 1.1 (or higher) web server
  • PHP 5.5.9 or higher, but PHP 5.6 or PHP 7 is recommended, as PHP 5.5 has reached its end-of-life support
  • MySQL 5.5 or MariaDB 5.5.20 for your database


You will need a user with privileges to create databases or a created database with a user who has privileges to make tables in that database.

  • Access to upload or move files to the server
  • While a default installation of PHP will work with Drupal, it does require certain PHP extensions, such as mbstring. Check out for up-to-date requirement information.


Drupal 8 ships with Symfony ( components. One of the new dependencies in Drupal 8, to support the Symfony routing system, is the Drupal Clean URL functionality. If the server is using Apache, ensure that mod_rewrite is enabled. If the server is using Nginx, the ngx_http_rewrite_module must be enabled.

We will download Drupal 8 and place its files in your web server's document root. This is the /var/www folder. If you used a tool, such as XAMPP, WAMP, or MAPP, consult the proper documentation to know your document root.

For full system requirements for Drupal 8, check out The documentation is currently being migrated. Also, review the Drupal 7 requirements page on, which highlights Drupal 8 items, as well.

How to do it...

We need to follow these steps to install Drupal 8:

  1. First, we will need to navigate to and download the latest release of Drupal 8.x. You can find the most recent and recommended release on the page for Drupal 8 (8.3.1, 8.4.0, and so on). Extract the archive and place the files in your document root as the drupal8 folder :
  1. Open your browser and visit your web server, for example, http://localhost/drupal8, which will then take you to the Drupal installation wizard. You will land on the new multilingual options install screen. Select your language and click on Save and continue:
  1. On the next screen, select the default Standard option for the installation profile. This will provide us with a standard configuration with the most commonly used modules installed.
  2. The next step will verify your system requirements. If your system does not have any reportable issues, the screen will be skipped. If you do have any requirement conflicts, you can resolve them and click on the button to try again.


If you have requirement issues, the installer will report the specific issues. Nearly every requirement will link to a handbook page with solution steps.

  1. Enter the database information for Drupal. In most cases, you will only need to supply the username, password, and database name and leave others as defaults. If your database does not exist, the installer will attempt to create the database:


See the There's more... section of this recipe for information on setting up your database.

  1. Your Drupal 8 site will begin installing. When it is done installing the base modules, you will be taken to a site configuration screen.


  1. The configure site form provides the base configuration for your Drupal site. Enter your site name and the email address for the site. The site email will be used to send administrative notifications and has the originating email for outgoing emails from the Drupal site. This form allows you to set regional information regarding the country and time zone of the site. Setting the timezone ensures that time values display correctly.
  2. Fill in the site maintenance account information, also known as user 1, which acts in a similar way to the root on Unix-based systems. The site maintenance account is crucial. As stated, this acts as the first user and is given the user ID of 1. In Drupal, the user with the user ID of 1 often can bypass permission checks automatically and have global access.
  3. Enter the site's regional information, and check whether the site should check for updates available for modules enabled and Drupal itself. By checking for updates automatically, your site will report anonymous usage statistics to Drupal along with providing a summary of your version status. You have the option to also opt-in for the site to email you notifications of new releases, including security releases.
  4. When the information is satisfied, click on Save and continue, and congratulations, you installed Drupal! The next screen will provide you a link to your installed Drupal site.

How it works...

The Drupal installation process will provide a Drupal installation for the selected language and install modules and configuration based on the installation profile (standard or minimal in this recipe.)

When you visit the installer, it reads the language code from the browser. With this language code, it will then select a supported language. If you choose a non-English installation, the translation files will be automatically downloaded from Previous versions of Drupal did not support automated multilingual installs. More on multilingual will be covered in Chapter 8, Multilingual and Internationalization.

The installation profile instructs Drupal what modules to install by default. Contributed install profiles are termed distributions; we will discuss this more in the next recipe.

When verifying requirements, Drupal checks application versions and PHP configurations. For example, if your server has the PHP Xdebug ( extension installed, the minimummax_nesting_level must be 256 or else Drupal will not be installed (

There's more...

The Drupal installation process is straightforward, but there are a few things worth discussing.

Creating a database user and a database

As mentioned earlier, to install Drupal, you will need to have access to a database server (or the ability to create one) and an existing database (or the ability to create one). This process will depend on your environment setup.

If you are working with a hosting provider, there is more than likely a web-based control panel. This should allow you to create databases and users. Refer to your hosting provider's documentation for more information on this topic.

If you are using phpMyAdmin ( on your server, often installed by MAMP, WAMP, and XAMPP, and have root access, you can create your databases and users by following these steps:

  1. Sign in to phpMyAdmin as the root user.
  2. Click on Add a new User from the bottom of the privileges page.
  3. Fill in the user's information.
  4. Select to create a database for the user with all privileges granted.
  5. You can now use that user's information to connect Drupal to your database.

If you do not have a user interface but have a command-line access, you can set up your database and user using the MySQL command line. These instructions can be found in the core/INSTALL.mysql.txt file. From the command line of your site, perform the following:

  1. Log in to MySQL:
$ mysql -u username -p
  1. Create the database; you will use the following command to create the my_database database:
$ CREATE DATABASE my_database CHARACTER SET utf8 COLLATE utf8_general_ci;
  1. Create a new user to access the database:
$ CREATE USER username@localhost IDENTIFIED BY 'password';
  1. Grant the new user permissions on the database, as follows:


If you are installing Drupal with a PostgreSQL or SQLite database, check out the appropriate installation instructions, either INSTALL.pgsql.txt or INSTALL.sqlite.txt.

Database prefixes

Drupal, like other content management systems, allows you to prefix its database tables from the database set-up form. This prefix will be placed before table names to help make them unique. Although it is not recommended, this would allow multiple installations to share one database. Utilizing table prefixes can, however, provide some level of security through obscurity since the tables will not be their default names:

Downloading and installing with Drush

You may also install Drupal using the PHP command-line tool, Drush. Drush is a command-line tool created by the Drupal community and must be installed if you wish to use it. Drush is covered in Chapter 13, The Drupal CLI.


As of Drush 9, which supports Drupal 8.3+, this section is deprecated. Using Drush to download Drupal core or contributed modules will throw a warning to use Composer instead.

The pm-download command will download packages from The site-install command will allow you to specify an installation profile and other options to install a Drupal site. The installation steps in this recipe could be run through Drush, as follows:

$ cd /path/to/web$ drush pm-download drupal-8 drupal8$ cd drupal8$ drush site-install standard -locale=en-US --account-name=admin --account-pass=admin -db-url=mysql://user:pass@localhost/database

We used Drush to download the latest Drupal 8 and place it in a folder named drupal8. Then, the site-install command instructs Drush to use the standard install profile, configure the maintenance account, and provide a database URI string so that Drupal can connect to its database.

Using Composer to create a Drupal site

You can download Drupal using Composer, the de facto PHP package manager. The preferred method is to use the Drupal Composer project template provided by the community.

To build your Drupal 8 site, run the following commands:

$ cd /path/to/document/root$ composer create-project drupal-composer/drupal-project drupal8 --stability dev

Wait for the commands to finish--it may take some time, as it downloads all the required dependencies. You can feel free to grab a coffee (the first time takes a while; it primes caches. Have faith, it will be much faster the next time.)

When finished, you will find a different directory structure inside your drupal8 directory. The vendor directory contains all third-party PHP libraries, and the web directory contains your Drupal 8 site. You will need to modify your web server to use the web directory as the new docroot within your drupal8 directory.

The project and its details can be found at, along with its full documentation.

Security updates

If you choose to disable the update options, you will have to check manually for module upgrades. While most upgrades are for bug fixes or features, some are for security updates. It is highly recommended that you subscribe to the Drupal security team's updates. These updates are available on Twitter at @drupalsecurity ( or the feeds on

See also

Using a distribution with Drupal

Why would you want to use a distribution? A distribution is a contributed installation profile that is not provided by Drupal core. Distributions provide a specialized version of Drupal with specific installed modules and themes along with specific configurations (content types, and blocks.) On, when you download an installation profile, it not only includes the profile and its modules but a version of Drupal core, hence the name distribution. You can find a list of all Drupal distributions at

How to do it...

We will follow these steps to download a distribution to use as a customized version of Drupal 8:

  1. Download a distribution from For this recipe, let's use the Demo Framework provided by Acquia at
  2. Select the recommended version for the 8.x branch.
  3. Extract the folder contents to your web server's document root--you'll note that there is Drupal core; within the profiles folder, there's the installation profile's folder--df.
  4. Due to current packaging limitations, there is a manual step that you will need to run in order to install additional dependencies. Run the following command using your terminal inside of the extracted contents:
$ composer require "commerceguys/intl: ~0.7" "commerceguys/addressing: ~1.0" "commerceguys/zone: ~1.0" "embed/embed: ~2.2
  1. Install Drupal as you would normally, by navigating to your Drupal site in your browser.
  2. Follow the installation instructions in the site to install the distribution.

How it works...

Installation profiles work by including additional modules that are part of the contributed project realm or custom modules. The profile will then define them as dependencies to be installed with Drupal. When you select an installation profile, you are instructing Drupal to install a set of modules on installation.

Demo Framework declares itself as an exclusive installation profile. Distributions that declare this are automatically selected and assumed to be the default installation option. The exclusive flag was added with Drupal 7.22 to improve the experience of using a Drupal distribution (

There's more...

Distributions provide a specialized version of Drupal with specific feature sets, but there are a few items worth discussing.


The current standard for generating a built distribution is the utilization of Drush and makefiles. Makefiles allow a user to define a specific version of Drupal core and other projects (such as themes, modules, and third-party libraries) that will make up a Drupal code base. It is not a dependency management workflow, like Composer, but is a build tool.

If you take a look at the Demo Framework's profile folder, you will see drupal-org.make and drupal-org-core.make. These are parsed by the packager to compile the code base and package it as a .zip or .tar.gz, like the one you downloaded.

Installing with Drush

As discussed in the first recipe's There's more... section, you can install a Drupal site through the Drush command-line tool. You can instruct Drush to use a specific installation profile by providing it as the first argument.


As of Drush 9, which supports Drupal 8.3+, this section is deprecated. Using Drush to download Drupal core or contributed modules will throw a warning to use Composer instead.

The following command would install the Drupal 8 site using the Demo Framework:

    $ cd /path/to/drupal8
$ drush pm-download df$ drush site-install df -db-url=mysql://user:pass@localhost/database

Using Composer

Currently, does not package distributions using Composer, which is why there was an extra step to add dependencies when installing the distribution. Many distributions provide project templates to make scaffolding projects simpler.

For example, the following command will set up a Demo Framework site with docroot as the directory for the web server document root, which contains Drupal 8:

$ composer create-project acquia/df-project df

The project template is available on Acqua's GitHub at

Another distribution, Open Social, provides a template of its own:

$ composer create-project goalgorilla/social_template

The project template is available at

See also...

Installing modules and themes

Drupal 8 provides more functionality out-of-the-box than previous versions of Drupal, allowing you to do more with less. However, one of the more appealing aspects of Drupal is the ability to extend and customize.

In this recipe, we will download and enable the Honeypot module ( and tell Drupal to use the Bootstrap theme ( The Honeypot module provides Honeypot and timestamps antispam measures on Drupal sites. This module helps protect forms from spam submissions. The Bootstrap theme implements the Bootstrap frontend framework and supports using Bootswatch styles to theme your Drupal site.


This chapter's recipe will use the standard way of installing modules, by downloading archives available on As of Drupal 8.2.0, installing modules through Composer has been possible and is the required method for some modules. Installing modules and themes using Composer is covered in the There's more... section of this recipe and is highly recommended.

Getting ready

If you have used Drupal before, note that the folder structure has changed. Modules, themes, and profiles are now placed in their respective folders in the root directory and no longer under sites/all. For more information about the developer experience change, refer to


Downloading the example code: You can download the example code files for all Packt books you have purchased from your account at If you have purchased this book from elsewhere, you can go to and register yourself to have the files emailed directly to you.

How to do it...

Let's install modules and themes:

  1. Visit and download the latest 8.x release for Honeypot.
  2. Extract the archive and place the honeypot folder inside the modules folder, which is inside of your Drupal core installation:

  1. In Drupal, log in and select the Extend option to access the list of available modules.
  2. Using the search text field, type in Honeypot. Check the checkbox and click on Install.


  1. Once enabled, search for it again. Clicking on the module's description will expand the row and expose links to configure permissions and module settings:

  1. Visit and download the latest 8.x release for Bootstrap.
  2. Extract the archive and place the bootstrap folder inside the themes folder, which is inside your Drupal core installation:

  1. In Drupal, select the Appearance option to manage your Drupal themes.
  2. Scroll down the page and click on Install and set as default under Bootstrap to enable and set the theme as default:

How it works...

The following sections outline the procedure for installing a module or theme and how Drupal discovers these extensions.

Discovering modules and themes

Drupal scans specific folder locations to identify modules and themes defined by the .info.yml file in their directory. The following is the order in which projects will be discovered:

  • Their respective core folders (modules, or themes)
  • The currently installed profile
  • The root modules or themes folder
  • The current site directory (default or current domain)

Module installation

By placing the module inside the root modules folder, we are allowing Drupal to discover the module and allow it to be installed. When a module is installed, Drupal will register its code with the system through the module_installer service. The service will check for required dependencies and prompt them to be enabled if required. The configuration system will run any configuration definitions provided by the module on installation. If there are conflicting configuration items, the module will not be installed.

Theme installation

A theme is installed through the theme_installer service and sets any default configuration by the theme along with rebuilding the theme registry. Setting a theme to default is a configuration change in system.theme.default to the theme's machine name (in the recipe, it would be bootstrap).

There's more...

The following section outlines the procedure for installing a module or theme and includes some additional information for installing.

Installing a module or theme using Composer

Although it is not the required way to install an extension, this should become your default method. Why? Because each module is a dependency in your project, and each of those may have its own dependencies. Composer can manage dependencies for you, or you can manage them manually. Your time and capabilities probably will not grow to scale as well as Composer will. Not to mention, it also provides a standard way for PHP projects to interoperate and load classes.

You can get the Honeypot module and Bootstrap using the following two commands:

$ cd /path/to/drupal8
$ composer require drupal/honeypot$ composer require drupal/bootstrap

Here is an example of contributed projects, which require Composer for installation, because they leverage existing libraries in the PHP community at large:

  • Drupal Commerce
  • GeoIP
  • Search API Solr
  • Entity Print

As more and more modules integrate existing SDK libraries, the requirement to use Composer will increase.

Installing a module with Drush

Modules can be downloaded and enabled through the command line using drush. The command to replicate the recipe would resemble the following:

$ drush pm-download honeypot$ drush pm-enable honeypot


As of Drush 9, which supports Drupal 8.3+, this section is deprecated. Using Drush to download Drupal core or contributed modules will throw a warning to use Composer instead.


It will prompt you to confirm your action. If there were dependencies for the module, it would ask whether you will like to enable those, too.


Drush simply downloads the archive available from If the module or theme requires third-party PHP library dependencies, these will not be downloaded or be available in Drupal's class autoloading process.

Uninstalling a module

One of the substantial changes in Drupal 8 is the module disable and uninstall process. Previously, modules were first disabled and then uninstalled once disabled. This created a confusing process, which would disable its features, but not clean up any database schema changes. In Drupal 8, modules cannot just be disabled but must be uninstalled. This ensures that when a module is uninstalled it can safely be removed from the code base.

A module can only be uninstalled if it is not a dependency of another module or does not have a configuration item in use--such as a field type--which could disrupt the installation's integrity.


With a standard installation, the Comment module cannot be uninstalled until you delete all the Comment fields on the article content type. This is because the field type is in use.

See also

  • Refer to Chapter 4, Extending Drupal, to learn about setting defaults on enabling a module.
  • Refer to Chapter 9, Configuration Management - Deploying in Drupal 8.

Using multisites in Drupal 8

Drupal provides the ability to run multiple sites from one single Drupal code base instance. This feature is referred to as multisite. Each site has a separate database; however, extensions stored in modules, profiles, and themes can be installed by all of the sites. Site folders can also contain their own modules and themes. When provided, these can only be used by that one site.

The default folder is the default folder used if there is no matching domain name.

Getting ready

If you are going to work with multisite functionality, you should have an understanding of how to set up virtual host configurations with your web server. In this recipe, we will use two subdomains under localhost, called dev1 and dev2.

How to do it...

We will use multisites in Drupal 8 by two subdomains under localhost:

  1. Copy sites/example.sites.php to sites/sites.php.
  2. Create a dev1.localhost and dev2.localhost folder inside the sites folder.
  3. Copy the sites/default/default.settings.php file into dev1.localhost and dev2.localhost as settings.php in their respective folder:

  1. Got to dev1.localhost and run the installation wizard.
  2. Got to dev2.localhost and verify that you still have the option to install a site!

How it works...

The sites.php must exist for the multisite functionality to work. By default, you do not need to modify its contents. The sites.php file provides a way to map aliases to specific site folders. The file contains the documentation for using aliases.

The DrupalKernel class provides findSitePath and getSitePath methods to discover the site folder path. On Drupal's Bootstrap, this is initiated and reads the incoming HTTP host to load the proper settings.php file from the appropriate folder. The settings.php file is then loaded and parsed into a \Drupal\Core\Site\Settings instance. This allows Drupal to connect to the appropriate database.

There's more...

Let's understand the security concerns of using multisite.

Security concerns

There can be cause for concern if you are using multisite. Arbitrary PHP code executed on a Drupal site might be able to affect other sites sharing the same code base. Drupal 8 marked the removal of the PHP filter ( module that allowed site administrators to use PHP code in the administrative interface. Although this mitigates the various ways an administrator had easy access to run PHP through an interface, it does not mitigate the risk wholesale. For example, the PHP filter module is now a contributed project and could be installed.

Domain aliases

The sites.php file provides a way to add domain aliases. This can be useful when you use a multisite functionality and need to develop it locally. A simple example would be providing a local.alias to each site.

If you had and as different site directories, the following mapping would allow and to map to those directories:

<?php$sites[''] = '';$sites[''] = '';$sites[''] = '';$sites[''] = '';

See also...

Tools for setting up an environment

One of the initial hurdles to getting started with Drupal is a local development environment. This recipe will cover how to set up the DrupalVM project by Jeff Geerling. DrupalVM is a VirtualBox virtual machine run through Vagrant, provisioned and configured with Ansible. It will set up all of your services and build a Drupal installation for you.

Luckily, you will only need to have VirtualBox and Vagrant installed on your machine, and DrupalVM works on Windows, macOS X, and Linux.

Getting ready

To get started, you will need to install the two dependencies required for DrupalVM:

How to do it...

Let's set up the DrupalVM project by Jeff Geerling by following these steps:

  1. Download the DrupalVM archive from
  2. Extract the archive and place the project in the directory of your choice.
  3. Copy example.drupal.make.yml to drupal.make.yml.
  4. Copy default.config.yml to config.yml.



  1. Edit config.yml and modify the local_path setting to be the directory where you've placed the DrupalVM project. This will be synchronized into the virtual machine:
local_path: /path/to/drupalvm 
destination: /var/www 
type: nfs 
create: true 
  1. Open a terminal and navigate to the directory where you have placed the DrupalVM project.
  2. Enter the vagrant up command to tell Vagrant to build the virtual machine and begin the provisioning process.
  3. While this process is ongoing, modify your host file to provide easy access to the development site. Add the line to your host file.
  4. Open your browser and access
  5. Log in to your Drupal site with the username admin and password admin.

How it works...

DrupalVM is a development project that utilizes the Vagrant tool to create a VirtualBox virtual machine. Vagrant is configured through the project's Vagrantfile. Vagrant then uses Ansible--an open source IT automation platform--to install Apache, PHP, MySQL, and other services on the virtual machine.

The config.yml file has been set up to provide a simple way to customize variables for the virtual machine and provisioning process. It also uses Drush to create and install a Drupal 8 site, or whatever components are specified in drupal.make.yml. This file is a Drush make file, which contains a definition for Drupal core by default and can be modified to include other contributed projects.

The vagrant up command tells Vagrant to either launch an existing virtual machine or create one anew in a headless manner. When Vagrant creates a new virtual machine, it triggers the provisioning process. In this instance, Ansible will read the provisioning/playbook.yml file and follow each step to create the final virtual machine. The only files that need to be modified, however, are the config.yml and drupal.make.yml files.

There's more...

The topic of automating and streamlining a local environment is quite popular right now with quite a few different options. If you are not comfortable with using Vagrant, there are a few other options that provide a server installation and Drupal.

Acquia Dev Desktop

Acquia Dev Desktop is developed by Acquia and can be found at It is an automated environment installer for Windows and Mac. It is a xAMP stack (or DAMP stack) installer that provides a full Drupal-specific stack that includes Apache, MySQL, and PHP. The Dev Desktop application allows you to create a regular Drupal installation or select from a distribution.

XAMPP + Bitnami

XAMPP - Apache + MySQL + PHP + Perl - is a cross-platform environment installation. XAMPP is an open source project from Apache Friends. XAMPP has partnered with Bitnami ( to provide free all-in-one installations for common applications, including Drupal 8. You can download XAMPP at


Kalabox is developed by the Kalamuna group and intends to be a robust workflow solution for Drupal development. Kalabox is cross-platform compatible, allowing you to easily work on Windows machines. It is based on the command line and provides application binaries for you to install. You can learn more about Kalabox at

See also

Running tests - Simpletest and PHPUnit

Drupal 8 ships with two testing suites. Previously, Drupal only supported Simpletest. Now, there are PHPUnit tests as well. In the official change record, PHPUnit was added to provide testing without requiring a full Drupal Bootstrap, which occurs with each Simpletest test. You can read the change record at

There is currently a PHPUnit initiative active in Drupal core development. The goal is to fully remove the Simpletest framework by Drupal 9. No new Simpletest tests are being written, at least since 8.2. All current tests are currently being converted by contributors. More about the initiative can be found in this issue,, where it is being coordinated.

We will be running tests using the test runner. This is a test runner provided by Drupal that supports concurrency and running all of the various test suites. Running tests directly with PHPUnit will be covered in the following There's more... section.

Getting ready

Drupal 8.1.0 introduced the ability to perform JavaScript browser tests. This is powered using PhantomJS (, which uses a browser emulator powered by the Mink PHP library ( In order to run the FunctionalJavascript test suite, you must have PhantomJS running.

To install PhantomJS, refer to the official installation instructions at

How to do it...

  1. First, install the Simpletest module. Even though you might only want to run PHPUnit, this is a soft dependency for running the test runner script.
  2. Open a command-line terminal and navigate to your Drupal installation directory.
  3. Next, we will run the test runner script. We will pass it a url option so that the Functional tests can run the browser emulator properly. We will also specify the test suites to run. This allows us to skip FunctionalJavascript tests due to PhantomJS not handling concurrency properly in the test runner:
$ php core/scripts/ --url http://localhost--types Simpletest,PHPUnit-Unit,PHPUnit-Kernel,PHPUnit-Functional --concurrency 20 --all
  1. Running FunctionalJavascripts tests require PhantomJS to be running. Since PhantomJS prints output to the terminal, open a new tab or terminal and run the following command:
phantomjs --ssl-protocol=any --ignore-ssl-errors=true vendor/jcalderonzumba/gastonjs/src/Client/main.js 8510 1024 768
  1. With PhantomJS running, we can now execute the FunctionalJavascript test suite:
php core/scripts/ --url http://localhost--types PHPUnit-FunctionalJavascript --concurrency 1 --all
  1. Review test output from each test suite run.

How it works...

The script has been shipped with Drupal since 2008, then namedrun-functional-tests.php. This command interacts with the test suites in Drupal to run all or specific tests and sets up other configuration items.

There are several different test suites that operate in specific ways:

  • Simpletest: The deprecated test system, full bootstraps and installs Drupal and uses its own browser emulator pattern using curl and XPath.
  • PHPUnit-Unit: Unit tests backed by PHPUnit. These are intended to test specific classes and not interact with the database.
  • PHPUnit-Kernel: Integration-level tests backed by PHPUnit. It is a test that has the ability to install schema and configuration to the database, minimally bootstrapping Drupal for basic integration testing.
  • PHPUnit-Functional: Functional tests are tests that require a fully bootstrapped Drupal and provide browser emulation via Mink. These can be considered a direct replacement of Simpletest tests but leveraging third-party testing libraries.
  • PHPUnit-FunctionalJavascript: Functional tests that have the ability to interact with PhantomJS in order to test JavaScript, such as AJAX operations and specific user interface interactions.

The following are some of the useful options:

  • --help: This displays the items covered in the following bullets
  • --list: This displays the available test groups that can be run
  • --url: This is required unless the Drupal site is accessible through http://localhost:80
  • --sqlite: This allows you to run tests without having Drupal installed
  • --concurrency: This allows you to define how many tests run in parallel

There's more...

We will now discuss more techniques and information for running Drupal's test suites.

Is run-tests a shell script?

The isn't actually a shell script. It is a PHP script--which is why you must execute it with PHP. In fact, within core/scripts, each file is a PHP script file meant to be executed using the command line. These scripts are not intended to be run through a web server, which is one of the reasons for the .sh extension.

There can be issues with PHP across platforms that prevent providing a shebang line to allow executing the file as a normal bash or bat script. For more information, refer to this issue at

Running tests without Drupal installed

With Drupal 8, tests can also be run from SQLlite and no longer requires an installed database. This can be accomplished by passing the sqlite and dburl options to script. This requires the PHP SQLite extension to be installed.

Here is an example adapted from the DrupalCI test runner for Drupal core. DrupalCI is the continuous integration service, which runs on for all submitted patches and commits:

php core/scripts/ --sqlite /tmp/.ht.sqlite --die-on-fail --dburl sqlite://tmp/.ht.sqlite --all

Combined with the built-in PHP web server for debugging, you can run test suites without a full-fledged environment.

Running specific tests

Each example so far has used the all option to run every Simpletest available. There are various ways to run specific tests:

  • --module: This allows you to run all the tests of a specific module
  • --class: This runs a specific path, identified by a full namespace path
  • --file: This runs tests from a specified file
  • --directory: This run tests within a specified directory


Previously in Drupal, tests were grouped inside the module.test files, which is where the file option derives from. Drupal 8 utilizes the PSR-4 autoloading method and requires one class per file.

PhpStorm - Drupal Test Runner

Drupal 8 has seen a surge in test coverage for both Drupal core and contributed projects, most likely due to PHPUnit adoption. In response to this, the author has written a PhpStorm plugin called Drupal Test Runner that simplifies executing the script runner.

The plugin's page can be found at, and it's public source code can be found at


With Drupal 8 came a new initiative to upgrade the testing infrastructure on The outcome was DrupalCI. DrupalCI is open source and can be downloaded and run locally. The project page for DrupalCI is

The test bot utilizes Docker and can be downloaded locally to run tests. The project ships with a Vagrant file that allows it to be run within a virtual machine or locally. Learn more on the testbot's project page at

See also...


Left arrow icon Right arrow icon

Key benefits

  • Discover the enhanced content authoring experience that comes with Drupal 8 and how to customize it
  • Take advantage of the broadened multilingual and tools of the new version to provide an internationalized website
  • This step-by-step guide will show you how to deploy from development, staging, and production of a website with Drupal 8's brand new configuration management system


Began as a message board, Drupal today is open source software maintained and developed by a community of over 1,000,000 users and developers. Drupal is used by numerous local businesses to global corporations and diverse organizations all across the globe. With Drupal 8’s exciting features it brings, this book will be your go-to guide to experimenting with all of these features through helpful recipes. We’ll start by showing you how to customize and configure the Drupal environment as per your requirements, as well as how to install third-party libraries and then use them in the Drupal environment. Then we will move on to creating blocks and custom modules with the help of libraries. We will show you how to use the latest mobile-first feature of Drupal 8, which will help you make your apps responsive across all the major platforms. This book will also show you how to incorporate multilingual facilities in your sites, use web services and third-party plugins with your applications from inside Drupal 8, and test and deploy your apps.

What you will learn

[*] Extend Drupal through contributed or custom modules and themes [*] Develop an internationalized website with Drupal s multilingual tools [*] Integrate third-party front-end and back-end libraries with Drupal [*] Turn Drupal into a web services provider using REST [*] Create a mobile-first responsive Drupal application [*] Run SimpleTest and PHPUnit to test Drupal [*] Understand the plugin system that powers many of Drupal 8 s new APIs to extend its functionality [*] Get to grips with the mechanics of the configuration management system and the ability to import and export site configuration

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now

Product Details

Publication date : Sep 26, 2017
Length 430 pages
Edition : 2nd Edition
Language : English
ISBN-13 : 9781788290401
Category :
Languages :
Concepts :

Table of Contents

20 Chapters
Title Page Chevron down icon Chevron up icon
Credits Chevron down icon Chevron up icon
About the Author Chevron down icon Chevron up icon
About the Reviewer Chevron down icon Chevron up icon Chevron down icon Chevron up icon
Customer Feedback Chevron down icon Chevron up icon
Preface Chevron down icon Chevron up icon
1. Up and Running with Drupal 8 Chevron down icon Chevron up icon
2. The Content Authoring Experience Chevron down icon Chevron up icon
3. Displaying Content through Views Chevron down icon Chevron up icon
4. Extending Drupal Chevron down icon Chevron up icon
5. Frontend for the Win Chevron down icon Chevron up icon
6. Creating Forms with the Form API Chevron down icon Chevron up icon
7. Plug and Play with Plugins Chevron down icon Chevron up icon
8. Multilingual and Internationalization Chevron down icon Chevron up icon
9. Configuration Management - Deploying in Drupal 8 Chevron down icon Chevron up icon
10. The Entity API Chevron down icon Chevron up icon
11. Off the Drupalicon Island Chevron down icon Chevron up icon
12. Web Services Chevron down icon Chevron up icon
13. The Drupal CLI Chevron down icon Chevron up icon

Customer reviews

Filter icon Filter
Top Reviews
Rating distribution
Empty star icon Empty star icon Empty star icon Empty star icon Empty star icon 0
(0 Ratings)
5 star 0%
4 star 0%
3 star 0%
2 star 0%
1 star 0%

Filter reviews by

No reviews found
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial


How do I buy and download an eBook? Chevron down icon Chevron up icon

Where there is an eBook version of a title available, you can buy it from the book details for that title. Add either the standalone eBook or the eBook and print book bundle to your shopping cart. Your eBook will show in your cart as a product on its own. After completing checkout and payment in the normal way, you will receive your receipt on the screen containing a link to a personalised PDF download file. This link will remain active for 30 days. You can download backup copies of the file by logging in to your account at any time.

If you already have Adobe reader installed, then clicking on the link will download and open the PDF file directly. If you don't, then save the PDF file on your machine and download the Reader to view it.

Please Note: Packt eBooks are non-returnable and non-refundable.

Packt eBook and Licensing When you buy an eBook from Packt Publishing, completing your purchase means you accept the terms of our licence agreement. Please read the full text of the agreement. In it we have tried to balance the need for the ebook to be usable for you the reader with our needs to protect the rights of us as Publishers and of our authors. In summary, the agreement says:

  • You may make copies of your eBook for your own use onto any machine
  • You may not pass copies of the eBook on to anyone else
How can I make a purchase on your website? Chevron down icon Chevron up icon

If you want to purchase a video course, eBook or Bundle (Print+eBook) please follow below steps:

  1. Register on our website using your email address and the password.
  2. Search for the title by name or ISBN using the search option.
  3. Select the title you want to purchase.
  4. Choose the format you wish to purchase the title in; if you order the Print Book, you get a free eBook copy of the same title. 
  5. Proceed with the checkout process (payment to be made using Credit Card, Debit Cart, or PayPal)
Where can I access support around an eBook? Chevron down icon Chevron up icon
  • If you experience a problem with using or installing Adobe Reader, the contact Adobe directly.
  • To view the errata for the book, see and view the pages for the title you have.
  • To view your account details or to download a new copy of the book go to
  • To contact us directly if a problem is not resolved, use
What eBook formats do Packt support? Chevron down icon Chevron up icon

Our eBooks are currently available in a variety of formats such as PDF and ePubs. In the future, this may well change with trends and development in technology, but please note that our PDFs are not Adobe eBook Reader format, which has greater restrictions on security.

You will need to use Adobe Reader v9 or later in order to read Packt's PDF eBooks.

What are the benefits of eBooks? Chevron down icon Chevron up icon
  • You can get the information you need immediately
  • You can easily take them with you on a laptop
  • You can download them an unlimited number of times
  • You can print them out
  • They are copy-paste enabled
  • They are searchable
  • There is no password protection
  • They are lower price than print
  • They save resources and space
What is an eBook? Chevron down icon Chevron up icon

Packt eBooks are a complete electronic version of the print edition, available in PDF and ePub formats. Every piece of content down to the page numbering is the same. Because we save the costs of printing and shipping the book to you, we are able to offer eBooks at a lower cost than print editions.

When you have purchased an eBook, simply login to your account and click on the link in Your Download Area. We recommend you saving the file to your hard drive before opening it.

For optimal viewing of our eBooks, we recommend you download and install the free Adobe Reader version 9.