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.
Before we start, you are going to need the below mentioned development environments that meet 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.
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.
Note
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 URL
functionality is required. If the server is using Apache, ensure thatmod_rewrite
is enabled. If the server is using Nginx, thengx_http_rewrite_module
must 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
drupal8
: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.
Note
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.
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.
Sign into
phpMyAdmin
as the root userClick 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 core/INSTALL.mysql.txt
files:
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.
The 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
See the Drupal.org handbook on installing Drupal https://www.drupal.org/documentation/install
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:
Download a distribution from Drupal.org. For this recipe let's use the Demo Framework provided by Acquia https://www.drupal.org/project/df.
Select the recommended version for the 8.x branch.
Extract the folder contents to your web server's document root. You'll notice there is Drupal core and, within the profiles folder, the installation profile's folder
df
.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.
Note
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.make
and drupal-org-core.make
. These are parsed by the Drupal.org packager to compile the code base and package it as a .zip
or .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.
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
Let's install modules and themes:
Visit https://www.drupal.org/project/honeypot and download the latest 8.x release for Honeypot.
Extract the archive and place the
honeypot
folder inside themodules
folder inside of your Drupal core installation: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.
Extract the archive and place the
bootstrap
folder inside thethemes
folder inside your Drupal core installation.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:
The following outlines the procedure for installing a module or theme and how Drupal discovers these extensions.
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:
Respective core folder (modules, themes)
Current installed profile
The root
modules
orthemes
folderThe 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.
The following outlines the procedure for installing a module or theme and some more information on it.
Modules can be downloaded and enabled through the command line using drush
. The command to replicate the recipe would resemble:
$ 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.
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.
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.
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 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 dev1
and dev2
.
We will use multisites in Drupal 8 by two subdomains under localhost:
Copy
sites/example.sites.php
tosites/sites.php
.Create a
dev1.localhost
and adev2.localhost
folder inside of the sites folder.Copy the
sites/default/default.settings.php
file intodev1.localhost
anddev2.localhost
assettings.php
in each respective folder:Visit
dev1.localhost
and run the installation wizard.Visit
dev2.localhost
and see that you still have the option to install a site!
The 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.
The DrupalKernel
class provides findSitePath
and 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.
Luckily you only need to have VirtualBox and Vagrant installed on your machine and DrupalVM works on Windows, Mac OS X, and Linux.
To get started, you will need to install the two dependencies required for DrupalVM:
VirtualBox: https://www.virtualbox.org/wiki/Downloads
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.
Copy
example.drupal.make.yml
todrupal.make.yml
.Copy
example.config.yml
toconfig.yml
Edit
config.yml
and modify thelocal_path
setting 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
Open a terminal and navigate to the directory where you have placed the DrupalVM project.
Enter the command
vagrant up
to 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.dev
to your hosts file.Open your browser and access http://drupalvm.com/.
Login to your Drupal site with the username
admin
and passwordadmin
.
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 needing to be modified, however, are the config.yml
and drupal.make.yml
files.
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/.
See Chapter 13, Drupal CLI, for information on makefiles
DrupalVM documentation http://docs.drupalvm.com/en/latest/
Drupal.org community documentation on local environment set-up https://www.drupal.org/node/157602
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.
Note
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
Simpletest
module. 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
Running
Simpletest
tests required executing the same script, however, instead of passing PHPUnit as the argument, you must define theurl
option andtests
option:php core/scripts/run-tests.sh --url http://localhost --all
Review test output!
The 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:
--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
Simpletest
without having to have Drupal installed--concurrency: This allows you to define how many tests run in parallel
The 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 bash
or 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.
Each example thus far has used the all
option to run every Simpletest
available. There are various ways to run specific tests:
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
Simpletest
from the command line: https://www.drupal.org/node/645286