Adding a custom Robo hook or command¶

BLT uses Robo and the Annotated Command library to define commands. You can use annotated commands to define new custom commands or hook into existing commands, such as executing custom code before or after an existing BLT command.

You can generate a file containing an example custom command and hook by running the following command:

blt recipes:blt:command:init

You can place custom commands in a different directory in your project or even a separate Composer package, as long as you expose the command file using PSR4.

To create your own Robo PHP command or hook, complete the following steps:

1. Create a new file named using the required pattern *Commands.php. For instance, the generated example uses the file name ExampleCommands.php.
2. Use a namespace ending in *\Blt\Plugin\Commands exposed using PSR4 in your composer.json file. For instance, the generated example uses the namespace Example\Blt\Plugin\Commands.
3. Follow the Robo PHP Getting started guide to write a custom command. For a list of all available hook types, see Annotated Command’s hook types.

Replacing or overriding a Robo command¶

To replace a BLT command with your own custom version, use the replace command annotation for your custom command.

Disabling a command¶

You can disable any BLT command. This will cause the target to be skipped during the normal build process. To disable a target, add a disable-targets key to your blt.yml file, as follows:

disable-targets:
  tests:
    phpcs:
      sniff:
        all: true
        files: true

This snippet causes BLT builds to skip the tests:phpcs:sniff:all and tests:phpcs:sniff:files targets.

Adding or overriding filesets¶

You can also define your own custom filesets or override existing filesets.

You can generate a file with an example custom fileset by running the following command:

blt recipes:blt:filesystem:init

You can place custom commands in a different directory in your project or even a separate Composer package, as long as you expose the command file using PSR4.

To create your own fileset definition, complete the following steps:

1. Create a new file named using the required pattern *Filesets.php. For instance, the generated example uses the file name ExampleFilesets.php.
2. Use a namespace ending in *\Blt\Plugin\Filesets exposed using PSR4 in your composer.json file. For instance, the generated example uses the namespace Example\Blt\Plugin\Filesets.
3. Create a public method in the Filesets class in the generated file.

4. Add a Fileset annotation to your public method, specifying its id:

   @fileset(id="files.yaml.custom")
   

5. Instantiate and return a Symfony\Component\Finder\Finder object. The files found by the finder form the fileset.

To change the filesets used in commands such as tests:twig:lint:all, tests:yaml:lint:all, and tests:php:lint, add the following configuration key to blt/blt.yml:

validate:
  yaml:
    filesets:
      - files.yaml.custom

Overriding the environment detector¶

BLT includes a unified environment detector class providing information about the current hosting environment such as the stage (dev, stage, or prod), provider (Acquia or Pantheon), and type (local or CI). The environment detector primarily examines environment variables and system configuration files to give details about the current environment.

You can extend the environment detector to support custom environments or override the detection behavior of built-in environments.

To override environment detector methods, create a new BLT plugin as follows:

1. Create a new custom environment detector class implementing BLT’s environment detector.
2. Override any supported method in your custom class.
3. Expose your custom class using PSR4 and add your class to Composer’s classmap in your plugin’s composer.json file.

BLT’s Environment Detector will discover your overrides using PSR4 and re-dispatch any method calls to your custom implementation.

As a reference implementation, the BLT Tugboat plugin illustrates how to override the Environment Detector in practice.

For more discussion on the Environment Detector architecture, design choices, and performance considerations, see this issue.

Modifying your BLT configuration¶

You can customize your BLT configuration by overriding the value of default variable values. The build.yml file contains the default values of all BLT variables.

behat.tags: @mytags

blt tests:behat:run -D behat.tags='@mytags'

Modifying the build artifact¶

To modify the behavior of the artifact:build target, you may override BLT’s deploy configuration. For example, review the deploy key in the build.yml file.

You can customize which files are committed to the build artifact using two general methods:

• An exclude file that prevents certain files from being copied into the build artifact
• A gitignore file that prevents files in the build directory from being committed to Git

deploy:
   exclude_file: ${repo.root}/blt/deploy/rsync-exclude.txt

/directorytoexclude
excludeme.txt

deploy:
   gitignore_file: ${repo.root}/blt/deploy/.gitignore

Pre and post command hooks¶

BLT provides two types of hooks for running custom tasks before, during, or after a built-in command.

# Executed after deployment artifact is created.
post-deploy-build:
   dir: ${deploy.dir}/docroot/profiles/contrib/acquia_cms
   command: npm install

/**
* This will be called after the artifact:build command.
*
* @hook post-command artifact:build
*/
public function postArtifactBuild() {
   $this->doSomething();
}

Modifying Git hooks¶

You may disable a Git hook by setting its value under git.hooks to false:

git:
   hooks:
      pre-commit: false

You can use a custom Git hook in place of BLT’s default Git hooks by setting its value under git.hooks to the directory path containing the hook. The directory must contain an executable file named after the Git hook:

git:
   hooks:
      pre-commit: ${repo.root}/my-custom-git-hooks

In the preceding example, an executable file named pre-commit should exist in ${repo.root}/my-custom-git-hooks.

Execute blt blt:init:git-hooks after modifying these values for changes to take effect. As most projects will already have a git key in their blt.yml file, ensure that you append hooks to the existing key.

By default, BLT will execute the internal:git-hook:execute:commit-msg command when new Git commits are made. This command validates that the commit message matches the regular expression defined in git.commit-msg.pattern. You can override the default configuration.

Modifying tests¶

You can modify the following test targets:

• tests:behat:run: To modify the behavior of the tests:behat:run target, you may override BLT’s Behat configuration. For examples, review the build.yml file.
• tests:phpcs:sniff:all: To change the behavior of the tests:phpcs:sniff:all target, you may copy phpcs.xml.dist to phpcs.xml in your repository’s root directory and modify the XML. For more information, see the official PHPCS documentation.

• tests:twig:lint:all: To prevent validation failures on any Twig filters or functions created in custom or contrib module twig.extension services, add filters and functions as follows:

  validate:
    twig:
      filters:
        - my_filter_1
        - my_filter_2
      functions:
        - my_function_1
        - my_function_2