WPCLI Docker Config

The setup process for contributing to WPCLI can be tricky. Although the docs are clear and concise, any contributors who prefer using Docker instead of Vagrant may get stuck. This guide attempts to bridge the gaps to enable Docker enjoyers to contribute just as easily.
The steps to follow assume that you are comfortable with WordPress development in general as well as basic Docker configuration.

Review Docs

Before proceeding, read through WPCLI Pull Requests guide. The official documentation mentions how the setup process differs slightly between Working on a specific command/package or Working on the project as a whole. This guide is focused towards working on a specific command/package (i.e. wp-cli/entity-command ).

Setting up Environment

PHPCS

WPCLI project uses squizlabs/PHP_CodeSniffer to check that any contributed code conforms to a custom ruleset(WP_CLI_CS). Just out of the box, PHP_CodeSniffer will produce an error when running phpcs from within wp-cli repository directory.

ERROR: Referenced sniff "WP_CLI_CS" does not exist

This isn’t detailed in the documentation for Pull Requests, but some grep-ing and googling for “WP_CLI_CS”, should lead you to the WP_CLI_CS ruleset -[https://github.com/wp-cli/wp-cli-tests/blob/main/WP_CLI_CS/ruleset.xml]

Install the ruleset:

phpcs --config-set installed_paths /path/to/WP_CLI_CS/ruleset.xml

Running phpcs again will produce a new error:

ERROR: Referenced sniff "PHPCompatibility" does not exist

A closer look at WP_CLI_CS ruleset reveals that it uses PHPCompatibility and WordPress-Coding-Standards under the hood.

Download and install these standards as well:

phpcs --config-set installed_paths /path/to/PHPCompatibility,/path/to/WordPress-Coding-Standards,/path/to/WP_CLI_CS/ruleset.xml

Check currently installed sniffs withphpcs -i

Check config paths with phpcs --config-show .

Using config file: /Users/devunstuck/vendor/squizlabs/php_codesniffer/CodeSniffer.conf

installed_paths: /Users/devunstuck/vendor/wp-coding-standards/wpcs,/Users/devunstuck/entity-command/wp-cli-tests/WP_CLI_CS
phpcs –config-show

Behat Test

Currently, branches of wpcli public repository runs Behat tests via GitHub Actions whenever code is pushed. So you’ll want run tests in your dev environment to see that they pass prior to submitting a PR.

To explore the referenced behat commands in more detail, take a peek at the "scipts": section of composer.json file

PHP MYSQL Setup

The official guides for setting up and running Behat assume that the runner context has access to php and mysql commands. This will not work when developing using Docker compose managed container where PHP and MYSQL are separate services. Use the following workaround for Behat testing.

Assuming your mysql container has a port mapping '33060:3306', you’ll can set WP_CLI_TEST_DBHOST on your computer:

export WP_CLI_TEST_DBHOST=127.0.0.1:33060

You may also need to update any other database credentials constants of wp-cli-tests.

Optionally, but recommended – Create an alias to ensure that php command runs the version from the container ( e.g. ) instead of version installed on your computer. For example, if your PHP docker container is named du-wordpress-develop-php-1, run:

alias php='docker exec -it -u wp_php du-wordpress-develop-php-1 php'

Running the composer prepare-tests will run install-package-tests shell script. You can check that the test database( default name wp_cli_test ) was created once the script exits.

Debugger

A step debugger is a great help in making sense of the unintuitive execution flow involving shell scripts, loopback requests, etc. If you already have xdebug enabled, map the location of the the WPCLI repo you are working on to the container and update the mapping in your IDE or debug config.

For example, when working on the entity command:

Update the path in php container. Assuming your docker compose contains the volume mapping:

  php:
    volumes:
      - ./entity-command:/usr/local/etc/entity-command`

Update IDE path mapping( Using VSCode here, but most modern IDEs have some way to do this). Edit your launch config in VSCode so it contains the following path mapping:

"pathMappings": {
                    "/usr/local/etc/entity-command": "/Users/devunstuck/assets/My-Projects/DevUnstuck/website/www/DU-wordpress-develop/entity-command",
}

Add the version of wp-cli to $PATH within the PHP container.

export PATH=/usr/local/etc/entity-command/vendor/wp-cli/wp-cli/bin:$PATH

Confirm that the PHP container is using the version of wp-cli in the repo you are working on.

which wp

Output should be something like usr/local/etc/entity-command/vendor/wp-cli/wp-cli/bin/wp .

Happy Developing

After completing these steps, your work path should be clear to code!