Document safe usage of GrumPHP with Integrated Composer

[xaqrox]

Re: GrumPHP with Lando or other localdev commands breaks IC

Priority: Medium

Issue Description

Documentation is needed on best practices for supporting GrumPHP on a site that uses a containerized local development environment AND Integrated Composer. I'm not sure where exactly this belongs but I offer the following content as a starting draft.

How will this impact users?

Users will be able to use GrumPHP and their development environment of choice for Pantheon sites using Integrated Composer.

Context

GrumPHP is a code quality tool that installs itself into git hooks via a Composer plugin. The hook runs whatever tasks the user specifies in their grumphp.yml (e.g. unit tests, code sniffing, etc.) and allows or prevents a commit as needed.

Developers using both GrumPHP and a containerized local dev environment (such as Lando or Docksal) may choose to run GrumPHP within that environment by changing the command triggered by GrumPHP on commit in thir grumphp.yml:

grumphp:
  git_hook_variables:
    EXEC_GRUMPHP_COMMAND: 'lando php'

The problem is GrumPHP runs in Integrated Composer, which in this case will cause the entire build to fail. Composer installs GrumPHP, then IC tries to make a commit, GrumPHP tries to run lando php and then fails because lando doesn't exist in Pantheon's build environment.

Suggested Resolution

The solution is to set EXEC_GRUMPHP_COMMAND to run a script that tests for the needed dependencies and only runs the GrumPHP tasks if everything is all good.

grumphp:
  git_hook_variables:
    EXEC_GRUMPHP_COMMAND: '.scripts/grumphp.sh' # YOUR SCRIPT NAME HERE

In the case of Lando, something like this works:

#!/bin/sh
if command -v lando &> /dev/null
then
  lando php "$@"
fi

The test in the script could be whatever is needed in your particular case. Here's one that tests for the existence of the PANTHEON_ENVIRONMENT env var (credit @joestewart):

#!/bin/sh
if [ -z "$PANTHEON_ENVIRONMENT" ]  &> /dev/null
then
  php "$@"
fi

[graham73may]

Just to add another example - Our team are using DDEV for our local dev environments, so instead of the lando commands we're using

#!/bin/sh
if command -v ddev $ >/dev/null; then
  ddev php "$@"
fi

(Tested and is working for us).