PHPackages bartlett/captainhook-bin-plugin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. bartlett/captainhook-bin-plugin ActiveLibrary[Utility & Helpers](/categories/utility) bartlett/captainhook-bin-plugin =============================== Captain Hook Plugin to execute any binary dependencies if (and only if) packages are installed 1.1.0(2mo ago)055MITPHPPHP ^8.1CI passing Since Mar 16Pushed 1mo agoCompare [ Source](https://github.com/llaville/captainhook-bin-plugin)[ Packagist](https://packagist.org/packages/bartlett/captainhook-bin-plugin)[ RSS](/packages/bartlett-captainhook-bin-plugin/feed)WikiDiscussions main Synced 3w ago READMEChangelog (4)Dependencies (10)Versions (5)Used By (0) About this project ================== [](#about-this-project) This package provides an action for [CaptainHook](https://github.com/captainhook-git/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](https://github.com/bamarni/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 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](https://github.com/llaville/captainhook-bin-plugin/blob/main/examples/vendor-bin-autoloader.php) example that register only additional autoloader of your dependencies handled by the Composer Bin Plugin. Goals ----- [](#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](https://github.com/llaville/captainhook-bin-plugin/blob/main/src/Condition/PackageInstalled.php) that check if package you want to use is installed or not (optional usage). 2. A [Plugin](https://github.com/llaville/captainhook-bin-plugin/blob/main/src/BinPlugin.php) that configure the runtime environment for running `action` in optimized way 3. Act as CaptainHook [SimplePlugin](https://github.com/captainhook-git/captainhook/blob/main/src/Plugin/Hook/SimplePlugin.php) 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 -------- [](#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 ------------ [](#installation) Install this package as a development dependency using [Composer](https://getcomposer.org): ``` 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](https://github.com/bamarni/composer-bin-plugin) to isolate your binary dependencies. Usage ----- [](#usage) Add the following and minimal code to your `captainhook.json` configuration file: ``` { "config": { "plugins": [ { "plugin": "\\Bartlett\\CaptainHookBinPlugin\\BinPlugin" } ] } } ``` Conditional usage ----------------- [](#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`](https://php.captainhook.info/conditions.html) 2. the plugin options via the `package-require` configuration property. ### Standard CaptainHook Conditions [](#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 [![conditional-usage-1a](docs/assets/images/conditional-usage-standard-way.png)](docs/assets/images/conditional-usage-standard-way.png) Know more when verbose mode is enabled (at least level 1) [![conditional-usage-1b](docs/assets/images/conditional-usage-standard-way-verbose.png)](docs/assets/images/conditional-usage-standard-way-verbose.png) ### Plugin Configuration [](#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 [![conditional-usage-2](docs/assets/images/conditional-usage-plugin-options.png)](docs/assets/images/conditional-usage-plugin-options.png) Configuration ------------- [](#configuration) ### Configuration Properties [](#configuration-properties) Configuration for `bartlett/captainhook-bin-plugin` consists of the following properties: PropertyDescription`package-require`The package name (Composer Identifier) and optionally a version constraint (Composer Semver syntax)`config-directory`The Configuration directory where to find your binary dependency config file`config-file`Your binary dependency configuration filename`binary-directory`Your binary dependency lookup directory (see )`dependency-manager`Your dependency manager : `Composer` (default), `Phive` (alternative) ... or your own implementation`colors`Choice what colors flag (pre-set) you want to use for your CLI tool : `auto` (default), `always`, `never`Please read the full documentation of Captain Hook that can be found at [php.captainhook.info](https://php.captainhook.info/). Learn by example ---------------- [](#learn-by-example) On official documentation, you can find [many examples](docs/examples/README.md) 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](https://github.com/carthage-software/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 [![results](docs/assets/images/mago-sample-auto-colors.png)](docs/assets/images/mago-sample-auto-colors.png) Second try with : ``` FORCE_COLOR=1 vendor/bin/captainhook hook:pre-push -c captainhook-sample.json --verbose ``` Gave following results [![results](docs/assets/images/mago-sample-force-color.png)](docs/assets/images/mago-sample-force-color.png) Tip Since release 1.1.0, the verbose level 2 display contextual information for an easy debugging [![very-verbose-mode](docs/assets/images/plugin-very-verbose-mode.png)](docs/assets/images/plugin-very-verbose-mode.png) Documentation ------------- [](#documentation) Full documentation may be found in [`docs`](docs/README.md) 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](https://github.com/squidfunk/mkdocs-material). 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 ------- [](#credits) Inspired by [`moxio/captainhook-eslint`](https://github.com/Moxio/captainhook-eslint), a Captain Hook Plugin, that validate files using ESLint only if it installed on your platform. ### Health Score 40 — FairBetter than 86% of packages Maintenance89 Actively maintained with recent releases Popularity11 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Total 4 Last Release 72d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/555d494363fdc69e712d56b46d3b9bf3fe221f2dae8a0cf3c732b0138d54f192?d=identicon)[llaville](/maintainers/llaville) --- Top Contributors [![llaville](https://avatars.githubusercontent.com/u/364342?v=4)](https://github.com/llaville "llaville (38 commits)") --- Tags captainhookcaptainhook-extension ### Embed Badge ![Health badge](/badges/bartlett-captainhook-bin-plugin/health.svg) ``` [![Health](https://phpackages.com/badges/bartlett-captainhook-bin-plugin/health.svg)](https://phpackages.com/packages/bartlett-captainhook-bin-plugin) ``` ### Alternatives [symfony/symfony The Symfony PHP framework 31.4k86.9M2.2k](/packages/symfony-symfony)[composer/composer Composer helps you declare, manage and install dependencies of PHP projects. It ensures you have the right stack everywhere. 29.5k193.1M3.0k](/packages/composer-composer)[friendsofphp/php-cs-fixer A tool to automatically fix PHP code style 13.5k245.4M23.9k](/packages/friendsofphp-php-cs-fixer)[drush/drush Drush is a command line shell and scripting interface for Drupal, a veritable Swiss Army knife designed to make life easier for those of us who spend some of our working hours hacking away at the command prompt. 2.4k59.5M767](/packages/drush-drush)[drupal/core Drupal is an open source content management platform powering millions of websites and applications. 19564.8M1.6k](/packages/drupal-core)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.6k38.2k](/packages/matomo-matomo) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)