Drupal 8 scaffold

A springboard project for new Drupal 8 projects.

Some areas may be opinionated towards the internal best practices at Real Life Digital, but will stick to community accepted standards as closely as possible.

Provides integration with platform.sh, but isn't dependent on its use. Notably there are some platform.sh sensible default files at:

• .platform.app.yaml
• .platform/routes.yaml
• .platform/services.yaml
• web/sites/default/settings.platformsh.php
• (Include statement in web/sites/default/example.settings.php)

This project differs from the Drupal 8 project template for Platform.sh in that it uses the drupal-composer/drupal-scaffold to build Drupal's scaffolded files (index.php, .htaccess etc) required on top of the composer dependencies, rather than including them here in this repo.

This project also aims to provide step-by-step documentation to speed up the roll up time for new projects.

Improvements

Areas for improvement are welcome through pull requests.

Prerequisites

• Composer installed on your development and production environments.
• A working MySQL or MariaDB database already set up with user permissions set.
• You have a remote git repository available and set up to accept your new project's git pushes.
• You have a means of serving the web root from PROJECT_DIRECTORY/web wherever you place it on your filesystem.
• MAMP or LAMP stack set up as per drupal.org system requirements documentation

Get going

1. Clone this repository and navigate inside.

git clone --depth=1 --branch=master [email protected]:reallifedigital/drupal-scaffold.git PROJECT_DIRECTORY
cd PROJECT_DIRECTORY

where PROJECT_DIRECTORY is the destination directory for the project.

2. Remove the .git directory so you can make your own git history.

rm -rf .git

3. Initialise your repository

git init && git config core.filemode false

4. Add your remote git repository location

Note: Ensure permissions are set up on the remote repository (i.e. with your SSH key).

git remote add origin USER@SERVER:REPO

Alter USER, SERVER and REPO above to suit your needs.

Note: for platform.sh use:

git remote add origin [email protected]:PROJECT_ID.git

Replace PROJECT_ID with the ID seen in the platform.sh UI, and LOCATION with the location which the platform is set up: e.g. 'eu'.

5. Create initial commit

git add . && git commit -m "Initial commit"

6. Push master branch to your remote

git push origin master

7. Build out the scaffold with the included build script

./build

Note: this build script can be used in the general development workflow to build new dependencies. See the contents of this file for more information on building with dev dependencies.

8. Create a settings.php file

cp web/sites/default/example.settings.php web/sites/default/settings.php

The example file contains sensible defaults which you can alter for the needs of the project.

Any changes you make to settings.php should be for all environments and should be checked into your git repository. This file is not git-ignored.

9. Set up you setting.local.php file

cp web/sites/default/example.development.settings.local.php web/sites/default/settings.local.php

Any changes you make to settings.local.php should be for the current environment only and should not be checked into your git repository. This file is git-ignored.

Edit the file at web/sites/default/settings.local.php and set the $databases array with your database settings.

10. Install Drupal

Either through the web interface:

http://SERVER_NAME/install.php

where SERVER_NAME is your remote or local server name where the site is served from - e.g. localhost.

Or use drush:

drush site-install standard --site-name="New site" --account-name="something_but_not_admin" --account-pass="something_secure" --site-mail="[email protected]"

Obviously, replace the placeholder argument above with sensible values.

Use: drush help site-install for more argument options.

11. Add your custom code

• Add your custom theme(s) to web/themes/custom
• Add your custom module(s) to web/modules/custom
• Add your static non-PHP libraries to web/libraries

12. Install contrib modules and themes with composer

composer require drupal/PROJECT_NAME

Tip: to see available drupal project (module) versions, run:

composer show -a drupal/PROJECT_NAME | grep versions

and then run, for example:

composer require "drupal/PROJECT_NAME:1.0.0"

where PROJECT_NAME is the project name at https://drupal.org/project/`PROJECT_NAME`

13. For any patches to be applied, update composer.json

First, ensure there is an upstream issue on drupal.org. Add an entry the patches section of the composer.json file.

Format to capture key information about the patch should be:

{
    "extra": {
        "patches": {
            "owner/repo": {
                "Module:Version, Issue description, Issue + Comment URL": "https://www.drupal.org/files/issues/example.patch"
            }
        }
    }
}

For example:

{
    "extra": {
        "patches": {
            "drupal/address": {
                "Address:8.x-1.x-dev, Add field settings for global overrides of required/optional behavior, https://www.drupal.org/node/2514126#comment-11917633": "https://www.drupal.org/files/issues/2514126-49.field-behavior-settings-as-table.patch"
            }
        }
    }
}

• Remember that this is a JSON object - the last patch in the list should not have a trailing comma.
• Remember that composer.json file use 4 spaces for indentation.
• Remember to run composer install after updating patch entries.

Further notes

• Config files located in web/sites/default/files are not git-ignored, so are safe to include, however, it's recommended to place the config exports outside the web root in the ../config/ directory. The example.settings.php file adds this as the default config directory.
• Uses the drupal-composer/drupal-scaffold project
• .gitignore file handles common use case, but may need to be tweaked to suit your own project
• Once you've run composer you should commit the composer.lock file. This file is not git-ignored.
• www symlink is in place for legacy support.

For contributing to this project

Fork the repo on GitHub and submit pull requests. All feedback is appreciated.

Further reading:

• Custom Drupal 8 theme up and running with Sass, Singularity, Breakpoint, LiveReload and Gulp
• Drupal's Coding standards

Author: Barry Fisher

Last updated: 2017-03-17