Drupal 8 Development Cookbook - Second Edition

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 (https://www.phpmyadmin.net/) 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:

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:

$ mysql -u username -p

$ CREATE DATABASE my_database CHARACTER SET utf8 COLLATE utf8_general_ci;

$ CREATE USER username@localhost IDENTIFIED BY 'password';

$ 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. 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:

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.

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 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 -account-email=demo@example.com -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.

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 https://github.com/drupal-composer/drupal-project, along with its full documentation.

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 (https://twitter.com/drupalsecurity) or the feeds onhttps://www.drupal.org/security.

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 Drupal.org packager to compile the code base and package it as a .zip or .tar.gz, like the one you downloaded.

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.

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

Currently, Drupal.org 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 https://github.com/acquia/df-project/.

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

$ composer create-project goalgorilla/social_template

The project template is available at https://github.com/goalgorilla/social_template.

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:

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.

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).

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:

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

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

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.

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.

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 (https://www.drupal.org/docs/8/modules/php/overview) 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.

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 example.com and mycompany.com as different site directories, the following mapping would allow local.example.com and local.mycompany.com to map to those directories:

<?php$sites['example.com'] = 'example.com';$sites['local.example.com'] = 'example.com';$sites['mycompany.com'] = 'mycompany.com';$sites['local.mycompany.com'] = 'mycompany.com';

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. 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 - Apache + MySQL + PHP + Perl - is a cross-platform environment installation. XAMPP is an open source project from Apache Friends. XAMPP has partnered with Bitnami (https://bitnami.com/) 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 on the command line and provides application binaries for you to install. You can learn more about Kalabox at http://www.kalamuna.com/products/kalabox/.

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 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 Drupal.org issue at https://www.drupal.org/node/655178.

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 therun-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. DrupalCI is the continuous integration service, which runs on Drupal.org for all submitted patches and commits:

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 web server for debugging, you can run test suites without a full-fledged environment.

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

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 run-tests.sh script runner.

The plugin's page can be found at https://plugins.jetbrains.com/plugin/8384-drupal-test-runner, and it's public source code can be found at https://github.com/mglaman/intellij-drupal-run-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 that allows it to be run within a virtual machine or locally. Learn more on the testbot's project page at https://www.drupal.org/project/drupalci_testbot.