We recently worked on a project where after reviewing the requirements decided to get our feet into the waters of Drupal 8. We set up a development server on Acquia cloud and proceeded as we would with Drupal 7:

• Spin up a new Drupal installation on Acquia cloud
• Do a git clone to get the site to a local machine
• Install Drupal locally
• Do some local development and push our work up to the development server.

It mostly went as planned until we decided to import local configuration into the dev server, kind of like we would do with the Features module on Drupal 7. It failed.

As it stands you can only share configuration between cloned instances of a site, not Git clone, but full database clone where the UUID must be same. That did put us under some pressure as we were racing to deliver on the project, now we had to deal with some internal plumbing that the client cannot review.

So for the next site we had to do it the right way, and that is what I would be sharing on this post. Let’s ride.

Since we use Acquia Cloud our workflow may be different from yours but the principles are basically the same. As with Drupal 7, we spin up a new Drupal 8 instance on Acquia cloud, then just after that we backup the database on Acquia cloud to store the near Zen version of the database and download that to our local machine. This version of the database would be used to set up our new site on local machines for the developers, as well as on the production machine.

The next step is to get the site onto our local computer for development. So, run Git clone to create a local instance of the development site but rather than install a fresh version on your local machine and creating a fresh UUID in the process, you will have to import the database you downloaded from Acquia cloud. That way your local site and the development site will have the same UUID. This process would also be repeated for all local machines for developers and on the production site.

To get your site to work, you would need to enter database configuration for your local site. Drupal would have done this for you if you followed the install process by inserting the database connection settings into the settings.php file. However, your settings.php file is being tracked by Git in your repository and the database configuration needs to be unique across the various environments, that is, the database settings for your local, development, and production environment are different, you will need a way to maintain the uniqueness across the various environments.

settings.local.php to the Rescue

Acquia cloud provides its own database configuration so we are left with that of the production and local sites. Different developers would need a different database configuration for their own machines, so we handle this by having all shared configuration in the settings.php file while unique configurations goes into a settings.local.php file and this file is excluded from the shared repository by providing the appropriate entry in your .gitignore file. To use settings.local.php, include an if file exist directive in your settings.php file to load your settings.local.php as shown.

    
      /**
       * Load local development override configuration, if available.
       *
       * Use settings.local.php to override variables on secondary (staging,
       * development, etc) installations of this site. Typically used to disable
       * caching, JavaScript/CSS compression, re-routing of outgoing emails, and
       * other things that should not happen on development and testing sites.
       *
       * Keep this code block at the end of this file to take full effect.
       */
       if (file_exists(__DIR__ . '/settings.local.php')) {
         include __DIR__ . '/settings.local.php';
      }
    
  

Configuration Synchronization

The single biggest feature of Drupal 8 is the Configuration Management System. Drupal 8 provides an interface for exporting and importing config from site to site, however, the command line proves to be much faster and productive than clicking through the Drupal 8 interface. Besides, I don’t enjoy downloading a compressed archive onto my computer, searching my download directory for it and then uploading it onto the next site.

Drush provides a handy means of importing and exporting configuration between sites. To begin we need to setup a synchronization directory for our site in our settings.php file. This goes into our settings.php file as it is a shared configuration. To achieve this all that is required is to add the following entry to our settings.php file.

    
       $config_directories = array(
          CONFIG_STAGING_DIRECTORY => 'sites/default/config',
      );
    
  

To export configuration from your local site you need to do is to run

And you would be prompted for the directory into which to export your site configuration.

Option 2, sync, is the drupal synchronization directory created during installation of your site, but the directory we are interested in is the staging directory which is option 1. Following the prompt would export the local config as a bunch of YAML files into the staging directory you defined and show in the image above. These files are then committed into your Git repository and pushed to your development server where other developers can pull or fetch to their own local machines.

To import configuration from the staging directory onto your active configuration, aka database, you also use drush by running

Bringing a composer to the mix

Drupal 8 is based on the Symfony project which is managed using composer - part of what Drush and Drush make does for drupal. Composer is the new Drush make for Drupal 8 something like the package.json file for a Node Js project. It is highly recommended that you manage your project with Composer. Drupal 8 ships with a composer.json file however we need to add some entries to enable us manage our project. The most important is the repository where Composer should look for our packages in our case that would be https://packages.drupal.org/8 and should be entered as shown:

    
      "repositories": {
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
         }
       }
    
  

We would also need to set the directory where contrib modules, themes, and install profiles would be downloaded into using the following entry:

        "installer-paths": {
          "modules/contrib/{$name}": ["type:drupal-module"],
          "profiles/contrib/{$name}": ["type:drupal-profile"],
          "themes/contrib/{$name}": ["type:drupal-theme"]
        }

This would cause contrib modules, themes, and install profiles to be downloaded into the contrib subdirectories. To add a contrib module with composer, all we need do is run the require command:

That is, composer require drupal/module-name

As can be seen, this would also download the dependencies of the module as well as the module itself. In this case with pathauto it had to first get both the token and ctools modules which pathauto depends on. At the same time it also updates our composer.json file with the appropriate entry.

Composer does not interact with our database so to install the modules you still need to use the Drupal interface or use any of the command line tools such as Drush and Drupal console.

Updating our project is rather straightforward by running:

That would look through all our projects and update any that requires an update along with their dependencies. So you can use this to update Drupal core, contrib modules, themes, and Symfony components. If you only want to update a single component, let’s say Drupal core, then you would run:

When all is done, we can now commit our project to Git and push to our dev server where other developers can pull to their local machine or the test server after which it can also be deployed onto the production server.

Once you get the setup right, Drupal 8 is an interesting platform to develop on.