This chapter will kick off with an introduction to getting a Drupal 8 site installed and running. We will walk through the interactive installer that most will be familiar with from previous versions of Drupal, and from the command line with Drush.
Once we have installed a standard 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 this has changed in Drupal 8.
The chapter will wrap up with recipes on how to set up a multisite installation in Drupal 8, getting a local development environment configured and running the available test suites.
Just like most things, there are many different methods for downloading Drupal and installing it. In this recipe, we will focus on downloading Drupal from https://www.drupal.org/ and setting it up on a basic Linux, Apache, MySQL, PHP (LAMP) server.
In this recipe, we will set-up the files for Drupal 8 and go through the installation process.
Apache 2.0 (or higher) or Nginx 1.1 (or higher) web server.
PHP 5.5.9 or higher.
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 that has privileges to make tables in that database.
Ability to upload or move files to the server!
Drupal also requires specific PHP extensions and configuration. Generally a default installation of PHP should suffice. See https://www.drupal.org/requirements/php for up to date requirements information.
Drupal 8 ships with Symfony components. One of the new dependencies in Drupal 8, to support the Symfony routing system, is that the Drupal
Clean URLfunctionality is required. If the server is using Apache, ensure that
mod_rewriteis enabled. If the server is using Nginx, the
ngx_http_rewrite_modulemust be enabled.
We will be downloading Drupal 8 and placing its files in your web server's document root. Generally, this is the
/var/www folder. If you used a tool such as XAMPP, WAMP, or MAPP please consult the proper documentation to know your document root.
We need to follow the below steps to install Drupal 8:
First we need to head to Drupal.org and download the latest release of Drupal 8.x! You can find the most recent and recommended release at the bottom of this page: https://www.drupal.org/project/drupal. Extract the archive and place the files to your document root as the folder
Open your browser and visit your web server, for example
http://localhost/drupal8, to be taken to the Drupal installation wizard. You will land on the new multilingual options install screen. Select your language and click Save and continue.
On the next screen keep the default Standard option for the installation profile. This will provide us with a standard configuration with the most commonly used modules installed.
The next step will verify your system requirements. If your system does not have any reportable issues, the screen will be skipped.
If you have requirement issues, the installer will report what the specific issues are. Nearly every requirement will link to a Drupal.org handbook page with solution steps.
Enter the database information for Drupal. In most cases, you only need to supply the username, password, and database name and leave the other defaults. If your database does not exist, the installer will attempt to create the database:
Your Drupal 8 site will begin installing! When it is done installing the base modules, you will be taken to a site configuration screen.
The configure site form provides the base configuration for your Drupal site. Enter your site name and the e-mail address for the site. The site email will be used to send administrative notifications and as the originating email for outgoing emails from the Drupal site. The form allows you to set regional information regarding the country and time zone of the site. Setting the timezone ensures time values display correctly.
Fill in the site maintenance account information, also known as user 1, which acts in a similar way to root on Unix based systems. The site maintenance account is crucial. As stated, this acts as the first user and resembles the root user in Unix-based systems. In Drupal, the user with the user ID of 1 can bypass permission checks and have global access.
Enter the site's regional information and 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.org 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.
When satisfied click Save and continue and Congratulations, you installed Drupal!
Drupal 8 supports a multilingual installation. 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 https://localize.drupal.org/. Previous versions of Drupal did not support automated multilingual installations.
The installation profile instructs Drupal what modules to install by default. Contributed install profiles are termed distributions. The next recipe discusses distributions
When verifying requirements, Drupal is checking application versions and configurations. For example, if your server has the PHP Xdebug extension installed, the minimum
max_nested_value must be 256 or else Drupal will not install.
The Drupal installation process can be very straight forward, but there are a few items worth discussing.
In order to install Drupal you will need to have access to a database server and an existing (or ability to create) database (or the ability to create one). This process will depend on your server 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's documentation.
phpMyAdminas the root user
Click Add a new User from the bottom of the privileges page
Fill in the user's information
Select to create a database for the user with all privileges granted
You can now use that user's information to connect Drupal to your database
If you do not have a user interface but have command line access, you can set up your database and user using the MySQL command line. These instructions can be found in the
Log into MySQL:
$ mysql -u username -p
Create the database you will use:
$ CREATE DATABASE database CHARACTER SET utf8 COLLATE utf8_general_ci;
Create a new user to access the database:
$ CREATE USER [email protected] IDENTIFIED BY 'password';
Grant the new user permissions on the database:
$ GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES ON databasename.* TO 'username'@'localhost' IDENTIFIED BY 'password';
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. While 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.
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. Drush is covered in Chapter 13, Drupal CLI.
pm-download command will download packages from Drupal.org. The
site-install command will allow you to specify an installation profile and other options for installing a Drupal site. The installation steps in this recipe could be run through Drush as:
$ cd /path/to/document/root $ drush pm-download drupal-8 drupal8 $ cd drupal8 $ drush site-install standard –locale=en-US –-account-name=admin –-account-pass=admin –[email protected] –db-url=mysql://user:[email protected]/database
We use 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 provides a database URI string so that Drupal can connect to its database.
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 https://www.drupal.org/security.
For more on multilingual, see Chapter 8, Multilingual and Internationalization
For more on using the command line and Drupal, see Chapter 13, Drupal CLI
Drush site install http://drushcommands.com/drush-8x/site-install/site-install
A distribution is a contributed installation profile that is not provided by Drupal core. Why would you want to use a distribution? Distributions provide a specialized version of Drupal with specific feature sets. On Drupal.org 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 here https://www.drupal.org/project/project_distribution.
We will follow these steps to download a distribution to use as a customized version of Drupal 8:
Select the recommended version for the 8.x branch.
Install Drupal as you would normally, by visiting your Drupal site in your browser.
Demo Framework declares itself as an exclusive profile. Distributions which 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 http://drupal.org/node/1961012.
Follow the installation instructions and you'll have installed the distribution!
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.
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 (themes, modules, 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 look at the Demo Framework's folder you will see
drupal-org-core.make. These are parsed by the Drupal.org packager to compile the code base and package it as a
.tar.gz, like the one you downloaded.
As shown in the first recipe, you can install a Drupal site through the Drush tool. You can instruct Drush to use a specific installation profile by providing it as the first argument. The following command would install the Drupal 8 site using the Demo Framework.
$ drush pm-download df $ drush site-install df –db-url=mysql://user:[email protected]/database
See Chapter 13, Drupal CLI, for information on makefiles.
Drush documentation page for drush make http://www.drush.org/en/master/make/
Distribution documentation on Drupal.org, https://www.drupal.org/documentation/build/distributions
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 timestamp anti-spam measures on Drupal sites. This module helps protect forms from spam submissions. The Boostrap theme implements the Bootstrap front-end framework and supports using Bootswatch styles for theming your Drupal site.
If you have used Drupal previously, take 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, see https://www.drupal.org/node/22336.
Let's install modules and themes:
Visit https://www.drupal.org/project/honeypot and download the latest 8.x release for Honeypot.
In Drupal, log in and select the Extend option to access the list of available modules.
Using the search text field, type in
Honeypot. Check the checkbox and click Install.
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:
Visit https://www.drupal.org/project/bootstrap and download the latest 8.x release for Bootstrap.
In Drupal, select the Appearance option to manage your Drupal themes.
Scroll down the page and click Install and set as default under Bootstrap to enable and set the theme as default:
Respective core folder (modules, themes)
Current installed profile
The current site directory (default or current domain)
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 for them to be enabled if required. The configuration system will run any configuration definitions provided by the module on install. If there are conflicting configuration items, the module will not be installed.
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
The following outlines the procedure for installing a module or theme and some more information on it.
$ drush pm-download honeypot $ drush pm-enable honeypot
It will prompt you to confirm your action. If there were dependencies for the module, it would ask if you would like to enable those, too.
One of the larger changes in Drupal 8 is the module disable and uninstall process. Previously modules were first disabled and then uninstalled once disabled. This left 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 be safely removed from the code base.
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, projects stored in modules, profiles, and themes can be installed by all of the sites.
default folder is the default folder used if there is not a matching domain name.
If you are going to work with multisite functionality, you should have an understanding of how to setup virtual host configurations with your particular web server. In this recipe, we will use two subdomains under localhost called
We will use multisites in Drupal 8 by two subdomains under localhost:
dev2.localhostfolder inside of the sites folder.
settings.phpin each respective folder:
dev1.localhostand run the installation wizard.
dev2.localhostand see that you still have the option to install a site!
sites.php must exist for 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.
DrupalKernel class provides
getSitePath 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.
Let's understand the security concerns of using multisite:
There can be cause for concern if 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. While 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.
Multi-site documentation on Drupal.org, https://www.drupal.org/documentation/install/multi-site
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.
Let's set up the DrupalVM project by Jeff Geerling. DrupalVM is a VirtualBox virtual machine run through Vagrant, provisioned and configured with Ansible:
Download the DrupalVM archive from https://github.com/geerlingguy/drupal-vm/archive/master.zip.
Extract the archive and place the project in your directory of choice.
config.ymland modify the
local_pathsetting to be the directory where you've placed the DrupalVM project. This will be synchronized into the virtual machine:
vagrant_synced_folders: - local_path: /path/to/drupalvm destination: /var/www type: nfs create: true
Enter the command
vagrant upto tell Vagrant to build the virtual machine and begin the provisioning process.
While this process is ongoing, modify your hosts file to provide easy access to the development site. Add the line
192.168.88.88 drupalvm.devto your hosts file.
Open your browser and access http://drupalvm.com/.
Login to your Drupal site with the username
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.
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.
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 needing to be modified, however, are the
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 is developed by Acquia and can be found at https://docs.acquia.com/dev-desktop2. It is an automated environment installer for Windows and Mac. The Dev Desktop application allows you to create a regular Drupal installation or select from a distribution.
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 https://www.apachefriends.org/download.html.
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 for the command line and provides application binaries for you to install. You can learn more about Kalabox at http://www.kalamuna.com/products/kalabox/.
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. Read the change record here: https://www.drupal.org/node/2012184.
Currently core comes with Composer dependencies prepackaged and no extra steps need to be taken to run PHPUnit. This recipe will demonstrate how to run tests the same way that the QA testbot on Drupal.org does.
The process of managing Composer dependencies may change, but is currently postponed due to Drupal.org's testing and packaging infrastructure. Read more here https://www.drupal.org/node/1475510.
First enable the
Simpletestmodule. Even though you might only want to run PHPUnit, this is a soft dependency for running the test runner script.
Open a command line terminal and navigate to your Drupal installation directory and run the following to execute all available PHPUnit tests:
php core/scripts/run-tests.sh PHPUnit
Simpletesttests required executing the same script, however, instead of passing PHPUnit as the argument, you must define the
php core/scripts/run-tests.sh --url http://localhost --all
Review test output!
run-tests.sh script has been shipped with Drupal since 2008, then named
run-functional-tests.php. The command interacts with the other suites in Drupal to run all or specific tests and sets up other configuration items. We will highlight some of the useful options below:
run-tests.sh 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 from 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 are issues with discovered PHP across platforms that prevent providing a shebang line to allow executing the file as a normal
bat script. For more info view this Drupal.org issue at https://www.drupal.org/node/655178.
With Drupal 8,
Simpletest can be run from SQLlite and no longer requires an installed database. This can be accomplished by passing the sqlite and dburl options to the run-
tests.sh script. This requires the PHP SQLite extension to be installed.
Here is an example adapted from the DrupalCI test runner for Drupal core:
php core/scripts/run-tests.sh --sqlite /tmp/.ht.sqlite --die-on-fail --dburl sqlite://tmp/.ht.sqlite --all
Combined with the built in PHP webserver for debugging you can run
Simpletest without a full-fledged environment.
With Drupal 8 came a new initiative to upgrade the testing infrastructure on Drupal.org. The outcome was DrupalCI. DrupalCI is open source and can be downloaded and run locally. The project page for DrupalCI is https://www.drupal.org/project/drupalci.
The test bot utilizes Docker and can be downloaded locally to run tests. The project ships with a Vagrant file to allow it to be run within a virtual machine or locally. Learn more on the testbot's project page: https://www.drupal.org/project/drupalci_testbot.
PHPUnit manual: https://phpunit.de/manual/4.8/en/writing-tests-for-phpunit.html
Drupal PHPUnit handbook: https://drupal.org/phpunit
Simpletestfrom the command line: https://www.drupal.org/node/645286