mstrelan / drupal-contrib

Starter project for contribution to Drupal

Drupal contrib starter project

Prerequisites

• Composer
• Docker / Docker compose
• PhpStorm (optional)

Getting started

To get started run the following command:

composer create-project mstrelan/drupal-contrib

Directory structure

• app/ - this is the web root. The Drupal repo will be checked out here.
• assets/scaffold/files/ - files that will be copied to their destination with composer.
• bin/ - vendor binaries go here.
• src/ - scripts used by composer.
• vendor/ - composer vendor dir.

Docker compose

Start the stack by running docker-compose up or make start.

You can override port numbers and other env vars by copying .env.dist to .env

The following services are available:

• nginx - the webserver
• php-fpm - serves the Drupal site
• php-cli - a CLI container for interacting with the Drupal site
• mysql - an empty database container
• chrome - for running webdriver tests

Makefile targets

Make commands should be executed on the host machine.

• clean - runs composer install, installs minimal profile and provides a one-time login link
• start - starts the stack
• stop - stops the stack
• stop-php - stops the php containers
• minimal - installs Drupal with the minimal profile
• standard - installs Drupal with the standard profile
• umami - installs Drupal with the demo_umami profile
• login - gets a one-time login link
• switch - switches branch, e.g. make BRANCH=9.3 switch
• 10.2|10.3|10.4|11.0|11.x - provides a clean environment with the specified Drupal version
• php8.1|php8.2|php8.3 - starts the stack with the specified php version

PhpStorm configuration

Upon first installation you'll be asked if you want to configure PhpStorm. This will configure a remote PHP interpreter, PHPUnit and path mappings for debugging.

The remote interpreter assumes that you have Docker integration configured and working already. See the Enable Docker support section of the PhpStorm documentation to set this up.

Running tests

If you elected to automatically configure PhpStorm you should be able to click the green triangle next to each test in PhpStorm.

Alternatively you can run phpunit on the command line like so:

docker-compose exec php-cli bash
phpunit -c app/core/phpunit.xml.dist app/core/tests/Drupal/Tests/Core/DrupalKernel/

Debugging

Xdebug can be enabled for HTTP requests via the Xdebug helper browser extension:

• Firefox - Xdebug Helper for Firefox
• Chrome - Xdebug helper

For CLI scripts including drush and phpunit, use XDEBUG_SESSION=1. For example:

You can also toggle Xdebug for debugging tests directly in PhpStorm by clicking the Run Test button next to a test and choosing Debug.

docker-compose exec php-cli bash
XDEBUG_SESSION=1 phpunit app/core/tests/Drupal/Tests/Core/DrupalTest.php --filter=testSetContainer

Debugging WebDriver tests with Selenium and VNC

The .env.dist file contains examples for how to configure the selenium service to use either Chrome or Firefox in debug mode. This exposes a VNC port (default 5900) that you can connect to in order to see tests running in the browser. Using a VNC client such as Remmina or VNC Viewer, simply connect to port 127.0.0.1:5900 with the password secret. If you've changed the VNC_PORT environment variable be sure to connect to that port instead.

Mailpit

The mailpit service is available and configured to capture email sent from the site. This can be accessed at http://localhost:8025. For more info see https://github.com/axllent/mailpit.

Contributing

Once you're up and running you'll have Drupal core checked out in the app directory. From here you can create a new branch for each issue that you're working on.

drupal-contrib's Issues

Document additional steps to use PHP interpreter

When the project is created we attempt to configure a remote interpreter in PhpStorm automatically. This assumes that the Docker connection is already globally configured in PhpStorm and has the name "Docker". If this is not configured, or configured incorrectly, the remote interpreter won't work. We should document additional steps required to get this working.

FunctionalJavascript tests not running since Selenium 4.9.0

Selenium 4.9.0 removes support for JSON Wire. This resulted in FunctionalJavascript tests not running. They just hang and fail to connect to Selenium.

Unable to run analysis from upgrade_status module reports

The upgrade status report shows the following error:

The PHPStan binary was not found in the default vendor directory based on the location of /data/app/composer.json. You may need to configure a vendor-dir in composer.json. See https://getcomposer.org/doc/06-config.md#vendor-dir. Attempted: /data/app/vendor/bin/phpstan. Scanning is not possible until this is resolved.

This tracks back to webflo/drupal-finder#48 which is resolved by webflo/drupal-finder#55. At this point in time there is no release with this fix (as per webflo/drupal-finder#57).

For now we could fix this with the following:

composer require "webflo/drupal-finder:dev-master as 1.2.2"

And setting the DRUPAL_FINDER env vars:

DRUPAL_FINDER_DRUPAL_ROOT=/data/app
DRUPAL_FINDER_COMPOSER_ROOT=/data
DRUPAL_FINDER_VENDOR_DIR=/data/vendor

For a very quick workaround you can delete app/composer.json as this will allow DrupalFinder to search the parent directory to find composer.json.

Tests fail when pushing tags

We're currently using dev-${{ github.ref_name }} as the version constraint for composer create-project. When pushing tags (e.g. 1.1.0) this resolves to dev-1.1.0 which is invalid. We may need to drop the dev- prefix if we can detect a tag was pushed, or skip running tests for tags, since they already run on the commit that was pushed.