Plugin Composer Laravel Package

Getting Started

Start by understanding this package is deprecated as of 2022 — new projects should skip it entirely and use captainhook/hook-installer instead. For legacy projects already using captainhook/plugin-composer, simply add it to require-dev in composer.json, run composer install, and Git hooks will auto-install on next composer install/update. The plugin hooks into Composer’s post-autoload-dump and post-install-cmd events — no manual setup needed. First use case: onboard a new developer — after composer install, their local Git hooks (e.g., pre-commit checks, PHPStan, PHPUnit) are automatically active.

Implementation Patterns

• Centralize hook config: Store hook definitions in captainhook.json (or custom name via "extra.captainhook.config"), ensuring consistency across local dev and CI. The plugin ensures hooks are installed even if Git existed before Composer.
• Flexible execution mode: Use "extra.captainhook.exec": "tools/captainhook.phar" to run the PHAR (recommended for modern stacks), or rely on "captainhook/captainhook" dependency. Avoid mixing with plugin-composer for new setups — migrate to hook-installer to decouple installation from dependencies.
• CI robustness: Enable "extra.captainhook.force-install": true to guarantee hooks reinstall on CI agents after clones or rebases, avoiding worktree/detection issues.
• Emergency bypass: Set CAPTAINHOOK_DISABLE=true in the environment to skip hook execution during debugging — useful for urgent commits without uninstalling the plugin.

Gotchas and Tips

• ⚠️ Deprecation warning: This package is unmaintained since Jan 2022. Even though it still works, every new Laravel project should use captainhook/hook-installer — it’s the officially supported replacement that allows PHAR, source, or PHIVE installation without forcing CaptainHook as a Composer dependency.
• Git worktree breakage: Versions <5.3.2 fail in Git worktrees. Verify version if using nested repos, and prioritize migration — hook-installer fixes this.
• PHP binary mismatch: Pre-5.3.1 versions may invoke hooks with the wrong php binary (e.g., CLI vs. Composer’s runtime). Upgrade or migrate — hook-installer uses the same binary as Composer by design.
• Silent failures: The plugin won’t abort Composer if captainhook install fails (≥5.2.0). Manually verify .git/hooks/ if hooks are missing — run composer dump-autoload -vvv for debug output.
• Path & quoting issues: Older releases had bugs with spaces in paths (e.g., C:\Program Files\). While patched in 5.1.x, always quote custom PHAR paths in "exec" config — and double-check this in Windows environments.
• Migration path: Remove captainhook/plugin-composer, add captainhook/hook-installer + captainhook/captainhook-phar (or captainhook/captainhook), update extra.captainhook.exec if using PHAR — then run composer update. Zero downtime.