Composer template for Drupal projects
, (*1)
This project template should provide a kickstart for managing your site
dependencies with Composer., (*2)
This is a fork of drupal-composer/drupal-project
which is set up with support for Continuous Integration out of the box., (*3)
Additional features
This fork has the following additions to the original version of drupal-project:, (*4)
-
Customizable builds: Different builds for production and development
environments are created with Phing. These can be
fully customized using a set of configuration files.
-
Behat support: Behat is included so you can easily test user scenarios.
-
Preconfigured test suites: PHPUnit is fully set up for running unit tests
as well as kernel tests, web tests and javascript tests.
-
PHP CodeSniffer: Check compliance with coding standards with a single
command, or set it up to scan automatically whenever you
git push.
-
Travis CI: Integrates seamlessly with Travis CI
so you can automate your tests right from the start. No setup needed!
If you want to know how to use it as replacement for
Drush Make visit
the Documentation on drupal.org., (*5)
Usage
First you need to install composer., (*6)
Note: The instructions below refer to the global composer installation.
You might need to replace composer with php composer.phar (or similar)
for your setup., (*7)
After that you can create the project:, (*8)
git clone https://github.com/dennisdigital/drupal-project.git some-dir
cd some-dir
composer install
With composer require ... you can download new dependencies to your
installation., (*9)
composer require drupal/devel:~1.0
The composer create-project command passes ownership of all files to the
project that is created. You should create a new git repository, and commit
all files not excluded by the .gitignore file., (*10)
composer create-project dennisdigital/drupal-project:8.x-dev /some-dir --stability dev --no-interaction
What does the template do?
When installing the given composer.json some tasks are taken care of:, (*11)
- Drupal will be installed in the
web-directory.
- Autoloader is implemented to use the generated composer autoloader in
vendor/autoload.php,
instead of the one provided by Drupal (web/vendor/autoload.php).
- Modules (packages of type
drupal-module) will be placed in web/modules/contrib/
- Theme (packages of type
drupal-theme) will be placed in web/themes/contrib/
- Profiles (packages of type
drupal-profile) will be placed in web/profiles/contrib/
- Creates default writable versions of
settings.php and services.yml.
- Creates
sites/default/files-directory.
- Latest version of drush is installed locally for use at
vendor/bin/drush.
- Latest version of DrupalConsole is installed locally for use at
vendor/bin/drupal.
Updating Drupal Core
This project will attempt to keep all of your Drupal Core files up-to-date; the
project drupal-composer/drupal-scaffold
is used to ensure that your scaffold files are updated every time drupal/core is
updated. If you customize any of the "scaffolding" files (commonly .htaccess),
you may need to merge conflicts if any of your modfied files are updated in a
new release of Drupal core., (*12)
Follow the steps below to update your core files., (*13)
- Run
composer update drupal/core --with-dependencies to update Drupal Core and its dependencies.
- Run
git diff to determine if any of the scaffolding files have changed.
Review the files for any changes and restore any customizations to
.htaccess or robots.txt.
- Commit everything all together in a single commit, so
web will remain in
sync with the core when checking out branches or running git bisect.
- In the event that there are non-trivial conflicts in step 2, you may wish
to perform these steps on a branch, and use
git merge to combine the
updated core files with your customized files. This facilitates the use
of a three-way merge tool such as kdiff3. This setup is not necessary if your changes are simple;
keeping all of your modifications at the beginning or end of the file is a
good strategy to keep merges easy.
Generate composer.json from existing project
With using the "Composer Generate" drush extension
you can now generate a basic composer.json file from an existing project. Note
that the generated composer.json might differ from this project's file., (*14)
Customize build properties
Create a new file in the root of the project named build.properties.local
using your favourite text editor:, (*15)
$ vim build.properties.local
This file will contain configuration which is unique to your development
machine. This is mainly useful for specifying your database credentials and the
username and password of the Drupal admin user so they can be used during the
installation., (*16)
Because these settings are personal they should not be shared with the rest of
the team. Make sure you never commit this file!, (*17)
All options you can use can be found in the build.properties.dist file. Just
copy the lines you want to override and change their values. For example:, (*18)
# The location of the Composer binary.
composer.bin = /usr/bin/composer
# Database settings.
drupal.db.name = my_database
drupal.db.user = root
drupal.db.password = hunter2
# Admin user.
drupal.admin.username = admin
drupal.admin.password = admin
# The base URL to use in tests.
drupal.base_url = http://platform.local
# Verbosity of Drush commands. Set to 'yes' for verbose output.
drush.verbose = yes
Listing the available build commands
You can get a list of all the available Phing build commands ("targets") with a
short description of each target with the following command:, (*19)
$ ./vendor/bin/phing
Install the website.
$ ./vendor/bin/phing install
If you want to install a version suitable for development you can execute the
setup-dev Phing target., (*20)
$ ./vendor/bin/phing setup-dev
This will perform the following tasks:, (*21)
- Configure Behat.
- Configure PHP CodeSniffer.
- Enable 'development mode'. This will:
- Enable the services in
development.services.yml.
- Show all error messages with backtrace information.
- Disable CSS and JS aggregation.
- Disable the render cache.
- Allow test modules and themes to be installed.
- Enable access to
rebuild.php.
- Enable development modules.
- Create a demo user for each user role.
To set up a development environment quickly, you can perform both the install
and setup-dev targets at once by executing install-dev:, (*22)
$ ./vendor/bin/phing install-dev
Running Behat tests
The Behat test suite is located in the tests/ folder. The easiest way to run
them is by going into this folder and executing the following command:, (*23)
$ cd tests/
$ ./behat
If you want to execute a single test, just provide the path to the test as an
argument. The tests are located in tests/features/:, (*24)
$ cd tests/
$ ./behat features/authentication.feature
If you want to execute one test of a group of tests, use tags. Use ~ to exclude a tag., (*25)
$ cd tests/
$ ./behat --tags="@api&&@user"
If you want to run the tests from a different folder, then provide the path to
tests/behat.yml with the -c option:, (*26)
# Run the tests from the root folder of the project.
$ ./vendor/bin/behat -c tests/behat.yml
Testing JavaScript functionality
For testing functionality written in JavaScript you can use software such as
Selenium and PhantomJS to run Behat tests in a real browser., (*27)
To enable JavaScript testing for a Behat scenario, add the @javascript tag to
the test, and make sure the WebDriver of your choice is running in the
background., (*28)
Chrome
Set the following build property in your behat.yml.dist file:, (*29)
# The browser to use for testing, either 'firefox' or 'chrome'.
behat.browser_name = chrome
Make sure to regenerate your Behat configuration file after making this change:, (*30)
$ drupal site:behat:setup site_name
You can install Selenium and Chrome / Chromium locally on your system and start
Selenium with java -jar selenium-server-standalone.jar., (*31)
However the simplest way of running Chrome on Selenium is using a container.
You can use Docker to install and run it with a single command. This will
download all necessary files and start it in the background in headless mode:, (*32)
$ docker run -d -p 4444:4444 --network=host selenium/standalone-chrome
If you want to look at the browser running, you can run the 'debug' version and
use a VNC client such as TigerVNC to connect to the browser (the password is
'secret'):, (*33)
$ docker run -d -p 4444:4444 -p 5900:5900 --network=host selenium/standalone-chrome-debug
For more information on running a containerized Selenium, see
SeleniumHQ/docker-selenium., (*34)
Firefox
Set the following build property in your behat.yml.dist file:, (*35)
# The browser to use for testing, either 'firefox' or 'chrome'.
behat.browser_name = firefox
Make sure to regenerate your Behat configuration file after making this change:, (*36)
$ drupal site:behat:setup site_name
You can install Selenium and Firefox locally on your system and start Selenium
with java -jar selenium-server-standalone.jar., (*37)
However the simplest way of running Firefox on Selenium is using a container.
You can use Docker to install and run it with a single command. This will
download all necessary files and start it in the background in headless mode:, (*38)
$ docker run -d -p 4444:4444 --network=host selenium/standalone-firefox:2.53.1
Note that the WebDriver implementation for Firefox
(Marionette)
is not yet complete for Selenium 3, so we are specifying the latest 2.x
version. This will probably be ready soon, when Selenium 3 is out of beta., (*39)
If you want to look at the browser running, you can run the 'debug' version and
use a VNC client such as TigerVNC to connect to the browser (the password is
'secret'):, (*40)
$ docker run -d -p 4444:4444 -p 5900:5900 --network=host selenium/standalone-firefox-debug:2.53.1
For more information on running a containerized Selenium, see
SeleniumHQ/docker-selenium., (*41)
PhantomJS
PhantomJS is a headless browser based on Webkit, which is the same engine which
Chrome uses. You can install it from your package manager, or download
it., (*42)
Declare that you are using a Chrome-alike browser in your behat.yml.dist
file:, (*43)
# The browser to use for testing, either 'firefox' or 'chrome'.
behat.browser_name = chrome
Make sure to regenerate your Behat configuration file after making this change:, (*44)
$ drupal site:behat:setup site_name
Now you can run PhantomJS in WebDriver mode, and run your tests. All your tests
marked with @javascript will now be executed using PhantomJS., (*45)
$ phantomjs --webdriver=4444
Running PHPUnit tests
Run the tests from the root:, (*46)
$ ./vendor/bin/phpunit
By default all tests in the folders web/modules/custom, web/profiles and
web/themes/custom are included when running the tests. Check the section on
PHPUnit in the build.properties.dist to customize the tests., (*47)
Checking for coding standards violations
Set up PHP CodeSniffer
PHP CodeSniffer is included to do coding standards checks of PHP and JS files.
In the default configuration it will scan all files in the following folders:
- web/modules (excluding web/modules/contrib)
- web/profiles
- web/themes, (*48)
First you'll need to execute the setup-php-codesniffer Phing target (note that
this also runs as part of the install-dev and setup-dev targets):, (*49)
$ ./vendor/bin/phing setup-php-codesniffer
This will generate a phpcs.xml file containing settings specific to your local
environment. Make sure to never commit this file., (*50)
Run coding standards checks
Run checks manually
The coding standards checks can then be run as follows:, (*51)
# Scan all files for coding standards violations.
$ ./vendor/bin/phpcs
# Scan only a single folder.
$ ./vendor/bin/phpcs web/modules/custom/mymodule
Run checks automatically when pushing
To save yourself the embarrassment of pushing non-compliant code to the git
repository you can put the following line in your build.properties.local:, (*52)
# Whether or not to run a coding standards check before doing a git push. Note
# that this will abort the push if the coding standards check fails.
phpcs.prepush.enable = 1
and then regenerate your PHP CodeSniffer configuration:, (*53)
$ ./vendor/bin/phing setup-php-codesniffer
If your project requires all team members to follow coding standards, put this
line in the project configuration (build.properties) instead., (*54)
Note that this will not allow you to push any code that fails the coding
standards check. If you really need to push in a hurry, then you can disable
the coding standards check by executing this Phing target:, (*55)
$ ./vendor/bin/phing disable-pre-push
The pre-push hook will be reinstated when the setup-php-codesniffer target
is executed., (*56)
Customize configuration
The basic configuration can be changed by copying the relevant Phing properties
from the "PHP CodeSniffer configuration" section in build.properties.dist to
build.properties and changing them to your requirements. Then regenerate the
phpcs.xml file by running the setup-php-codesniffer target:, (*57)
$ ./vendor/bin/phing setup-php-codesniffer
To change to PHP CodeSniffer ruleset itself, make a copy of the file
phpcs-ruleset.xml.dist and rename it to phpcs-ruleset.xml, and then put this
line in your build.properties file:, (*58)
phpcs.standard = ${project.basedir}/phpcs-ruleset.xml
For more information on configuring the ruleset see Annotated ruleset., (*59)
FAQ
Should I commit the contrib modules I download
Composer recommends no. They provide argumentation against but also
workrounds if a project decides to do it anyway., (*60)
How can I apply patches to downloaded modules?
If you need to apply patches (depending on the project being modified, a pull
request is often a better solution), you can do so with the
composer-patches plugin., (*61)
To add a patch to drupal module foobar insert the patches section in the extra
section of composer.json:, (*62)
"extra": {
"patches": {
"drupal/foobar": {
"Patch description": "URL to patch"
}
}
}
Wallogit.com
