README

About this project

This package provides an action for CaptainHook which will invoke any binary dependencies if (and only if) packages are installed.

I recommend to install your dependencies with the Composer Bin Plugin to avoid conflicts. On my own opinion it's a better strategy than using the require-dev entry of your composer.json config file that install all dependencies without control and/or filter possibilities.

If you follow this recommendation, I suggest to configure it correctly in your composer.json

{
    "extra": {
        "bamarni-bin": {
            "bin-links": true,
            "forward-command": false,
            "target-directory": "vendor-bin"
        }
    }
}

Important

The forward-command set to false allow to install only dependencies that you want by manually run composer bin <namespace> update Otherwise, it will act as the require-dev Composer strategy, and install all dependencies at once.

And use a CaptainHook bootstrapping option with file such as the vendor bin autoloader example that register only additional autoloader of your dependencies handled by the Composer Bin Plugin.

Goals

This CaptainHook Plugin avoid situation where you run a binary dependency action and got a failure because the binary is not available (package not installed).

It provides :

1. A Condition that check if package you want to use is installed or not (optional usage).
2. A Plugin that configure the runtime environment for running action in optimized way
3. Act as CaptainHook SimplePlugin with an improved presentation for debugging purpose.
4. Possibilities to avoid hard-coding values on action command line. All flags should be resolved at CaptainHook runtime.

Features

• Execute any of your favorite PHP toolchain via the Command Line Interface, only if available
• Skip vendor action execution, if the dependency is not installed or does not satisfy minimum requirement of your platform
• Automatic Condition applied if not specified in your captainhook.json configuration.

Installation

Install this package as a development dependency using Composer:

composer require --dev bartlett/captainhook-bin-plugin

Note

This project provides some additional PHP toolchain that you can install (for demo purpose) with Composer-Bin-Plugin to isolate your binary dependencies.

Usage

Add the following and minimal code to your captainhook.json configuration file:

{
    "config": {
        "plugins": [
            {
                "plugin": "\\Bartlett\\CaptainHookBinPlugin\\BinPlugin"
            }
        ]
    }
}

Conditional usage

If you want to perform your Action only when your dependency is installed, you have two strategies available :

1. the standard CaptainHook way with conditions
2. the plugin options via the package-require configuration property.

Standard CaptainHook Conditions

You can add a corresponding condition to the action:

For example, if you want to run action for at least PHP Code Sniffer 3.3 or greater :

{
    "pre-commit": {
        "enabled": true,
        "actions": [
            {
                "action": "vendor/bin/phpcs",
                "config": {
                    "label": "Static Analysis (with PHP Code Sniffer)"
                },
                "conditions": [
                    {
                        "exec": "\\Bartlett\\CaptainHookBinPlugin\\Condition\\PackageInstalled",
                        "args": ["squizlabs/php_codesniffer", "^3.3 || ^4.0"]
                    }
                ]
            }
        ]
    }
}

Note

On Condition arguments :

• the first entry is the Composer package name,
• the second entry is the version constraint (same syntax as Composer Semver), with default value to '*' means no constraint.

Try it with following command :

vendor/bin/captainhook hook:pre-commit --configuration captainhook-sample1.json

That prints something like

Know more when verbose mode is enabled (at least level 1)

Plugin Configuration

You can add a corresponding condition to the action:

For example, if you want to run action for at least PHP Code Sniffer 3.3 or greater :

{
    "pre-commit": {
        "enabled": true,
        "actions": [
            {
                "action": "vendor/bin/phpcs",
                "config": {
                    "label": "Static Analysis (with PHP Code Sniffer)"
                },
                "options": {
                    "package-require": [
                        "squizlabs/php_codesniffer",
                        "^3.3 || ^4.0"
                    ]
                }
            }
        ]
    }
}

Try it with following command :

vendor/bin/captainhook hook:pre-commit --configuration captainhook-sample2.json --verbose

That prints something like

Configuration

Configuration Properties

Configuration for bartlett/captainhook-bin-plugin consists of the following properties:

Please read the full documentation of Captain Hook that can be found at php.captainhook.info.

Learn by example

On official documentation, you can find many examples that demonstrate features of this plugin.

With captainhook-sample.json config file, you can quickly see all plugin options defined with a pre-push hook running the Mago PHP toolchain.

This is an efficient example that show (if binary dependency support it), how to run the same CaptainHook config file without to change its contents, and override only Environment Variables.

First try with :

vendor/bin/captainhook hook:pre-push -c captainhook-sample.json --verbose

Gave following results

Second try with :

FORCE_COLOR=1 vendor/bin/captainhook hook:pre-push -c captainhook-sample.json --verbose

Gave following results

Tip

Since release 1.1.0, the verbose level 2 display contextual information for an easy debugging

Documentation

Full documentation may be found in docs folder into this repository, and may be read online without to do anything else.

As alternative, you may generate a professional static site with Material for MkDocs.

Configuration file mkdocs.yml is available and if you have Docker support, the documentation site can be simply build with following command:

docker run --rm -it -u "$(id -u):$(id -g)" -v ${PWD}:/docs squidfunk/mkdocs-material build --verbose

Credits

Inspired by moxio/captainhook-eslint, a Captain Hook Plugin, that validate files using ESLint only if it installed on your platform.