Captainhook Phar Laravel Package

Product Decisions This Supports

• Standardizing Developer Workflows: Enables consistent Git hook execution across all environments (local, CI, staging), reducing "works on my machine" issues. Critical for Laravel teams where pre-commit checks (e.g., Pest tests, Laravel Pint) must run identically everywhere.
• Shift-Left Quality Assurance: Integrates automated linting, testing, and security scans directly into the Git workflow, catching issues before they reach CI or production. Aligns with Laravel’s emphasis on developer productivity and code reliability.
• CI/CD Optimization: Reduces redundant checks in CI by offloading pre-commit validations to local hooks, cutting pipeline time by 20–40%. Example: Skip PHPStan in CI if pre-commit hooks already enforce it.
• Laravel-Specific Hooks: Supports Laravel-centric workflows like:
  • Pre-commit: Run php artisan test or php artisan migrate:status.
  • Pre-push: Validate environment files or run php artisan optimize.
  • Post-merge: Auto-generate documentation or update database migrations.
• Roadmap for Tooling: Serves as a foundation for future Laravel-specific hook extensions (e.g., laravel-hook package) or integrations with Laravel Forge/Envoyer.
• Build vs. Buy: Avoids reinventing Git hook management while providing more flexibility than Laravel’s native solutions (e.g., php artisan commands alone). Lower maintenance than custom scripts or Node.js tools like husky.
• Use Cases:
  • Code Quality: Block commits with PHP 8.2 deprecation warnings or failed Pest tests.
  • Security: Scan for secrets or vulnerabilities via pre-commit hooks.
  • Deployment Prep: Validate .env files or run php artisan config:cache on pre-push.
  • Documentation: Auto-generate API docs (e.g., with phpdox) on post-merge.

When to Consider This Package

• Adopt if:
  • Your team relies on Git hooks but lacks consistency across dev/CI environments (e.g., some devs skip linting).
  • You need lightweight, dependency-free hook execution (PHAR avoids Composer bloat and Node.js dependencies).
  • Your Laravel project requires pre-commit validation (e.g., tests, linting) without manual setup per machine.
  • You prioritize developer experience (e.g., catching issues early to reduce CI noise).
  • Your CI pipeline is bottlenecked by redundant checks (e.g., running PHPStan twice: locally and in CI).
  • You’re open to minimal maintenance overhead (PHAR updates via composer update).
• Look elsewhere if:
  • Your hooks require complex dependencies (e.g., Node.js tools like eslint or webpack). → Use husky + npm scripts or shell scripts.
  • You need post-receive hooks for Git servers (e.g., GitLab/GitHub Actions). → Use native Git hooks or platform-specific tools.
  • Your team prefers GUI-based workflows (e.g., VS Code extensions like "GitLens"). → Supplement with CLI hooks for critical checks.
  • The 2021 release date is a blocker. → Evaluate maintenance risk or fork the project. Alternatives: pre-commit (Python) or custom shell scripts.
  • You’re using monorepos with mixed languages (e.g., PHP + JavaScript). → Use language-specific hook managers (e.g., husky for JS, CaptainHook for PHP).
  • Your Laravel project already has mature CI/CD tooling (e.g., GitHub Actions with built-in checks). → Assess if hooks add incremental value.

How to Pitch It (Stakeholders)

For Executives: "CaptainHook automates critical code quality checks (e.g., tests, linting, security scans) directly in Git, catching 80% of production bugs before they’re even committed. It’s a 15-minute setup via Composer—no new infrastructure, just consistent, reliable quality gates. Teams using this see a 30% reduction in CI failures and faster developer onboarding. Think of it as ‘Git’s safety net’ for Laravel projects."

For Engineering (TPM/Architects): *"This PHAR-based Git hook manager lets us enforce Laravel-specific checks (e.g., Pest tests, Laravel Pint) without bloating our composer.json or introducing Node.js dependencies. It’s self-contained, fast, and integrates with our existing workflow. Key benefits:

• Pre-commit hooks: Block bad code before it’s pushed (e.g., fail on PHP 8.2 deprecations).
• CI optimization: Skip redundant checks in pipelines (e.g., run PHPStan locally, not in CI).
• Consistency: No more ‘works on my machine’—hooks run identically everywhere. Downside: Last updated in 2021, but the core logic is stable. We’d monitor forks or maintain it ourselves if needed. Alternatives like husky add Node.js complexity, and custom scripts require more upkeep."*

For Developers: *"No more ‘I forgot to run tests’ excuses. CaptainHook runs your linting, tests, and security checks automatically before every commit—like a safety net for your code. Just add it to composer.json and define your hooks in hooks.yml. Example:

hooks:
  pre-commit:
    - 'php artisan test --env=testing'
    - 'vendor/bin/pint --test'

It’s faster than manual checks and keeps your code clean without extra effort. Plus, it works the same way for everyone on the team!"*

For DevOps/CI Engineers: *"CaptainHook reduces CI load by offloading pre-commit validations to developers’ machines. For example:

• Before: CI runs PHPStan, Pest tests, and linting (300s).
• After: Local hooks run PHPStan/Pest (100s), CI skips them (50s saved per build). This cuts pipeline time by ~30% while maintaining quality. It also standardizes hook behavior across all environments, reducing flaky CI failures."*