cihispano / git-hooks

v0.2.0 2026-09-23 01:41 UTC

Requires

• php: ^8.1

Requires (Dev)

• codeigniter/coding-standard: ^1.8
• friendsofphp/php-cs-fixer: ^3.90
• mikey179/vfsstream: ^1.6
• phpstan/phpstan: ^2
• phpunit/phpunit: ^10.5
• slevomat/coding-standard: ^8.28
• squizlabs/php_codesniffer: ^4.0

MIT

• Jorge Armando Pacheco Del real

• codeigniter
• phpcs
• static-analysis
• php-cs-fixer
• pre-commit
• pre-push
• commit-msg
• PHPStan
• code-quality
• codeigniter4
• git-hooks

Published on Packagist.org on 2026-09-23 06:51 UTC

README

Automated Git Hooks for CodeIgniter 4 projects. This package ensures your code meets the highest quality standards by running automated checks before every commit.

✨ Features

• 🔍 PHP Syntax Check - Validates PHP syntax (lint) on all staged files.
• 📊 PHPStan Analysis - Performs deep static analysis to find potential bugs (Level 10).
• 👃 PHP_CodeSniffer - Validates PSR-12 compliance and coding standards.
• 🎨 PHP CS Fixer - Automatically formats code to follow defined styles.
• 🎯 Smart Scope - Only analyzes staged files to keep your workflow fast.
• 🌈 Native ANSI Output - Beautiful, colorful console feedback with icons (respects NO_COLOR).
• 🔧 Zero Config - Works out of the box with sensible defaults for CI4.

🗺️ Roadmap

Planned, not yet available:

• Extended git-hooks.json - Tool toggles (phpstan, phpcs, php_cs_fixer, phpunit), commit_msg overrides (min_length, max_length, types), and a tool/config allowlist to decide which project configuration files and vendor/bin binaries the hooks may run (trust gate for SEC-001).
• PHP-based hooks - Replace the current shell scripts with PHP bootstrap scripts that delegate to the package classes.
• NO_COLOR in shell hooks - Make the installed shell hooks honor NO_COLOR (today it is respected by the installer/uninstaller console output, not by the hook scripts).

See docs/CONFIGURATION.md for the configuration schema and defaults.

📋 Requirements

• PHP 8.1 to 8.4
• Git 2.0 or higher
• Composer 2.0 or higher

Compatibility policy

• Runtime compatibility: the package is supported on PHP 8.1 through 8.4.
• Development dependency resolution: composer.lock is generated with config.platform.php=8.1.0.
• CI validation: tests and static analysis run on PHP 8.1, 8.2, 8.3, and 8.4 in both GitHub Actions and GitLab CI.
• Coding style checks (composer sniff and composer cs) run on PHP 8.1 to keep formatter and sniffer output aligne with the minimum supported runtime.
• When running composer cs on PHP newer than 8.1, PHP CS Fixer may show a warning. This is expected; use PHP 8.1 locally if you want warning-free style checks.

📦 Installation

Install the package as a development dependency:

composer require --dev cihispano/git-hooks

Then install the hooks into the current repository:

composer install-hooks

The hooks are not installed automatically on composer install/update; run composer install-hooks once per repository (and again after updating the package) to install or refresh them. Use composer uninstall-hooks to remove them.

Install Location

Hooks are copied to the repository's hooks directory, resolved in the following order:

1. git -C <directory> rev-parse --git-path hooks — always preferred, so git decides the location for worktrees, submodules, and core.hooksPath.
2. Manual fallback that parses .git (directory or gitdir: file) and linked-worktree commondir files.

The hooks source is always read from the installed package root, so the install works identically whether the package lives at the project root or under vendor/.

🚀 Usage

Once installed, the hooks work automatically.

pre-commit

Every time you commit code, the pre-commit hook will:

1. ✅ Check PHP syntax on all staged .php files
2. ✅ Verify formatting with PHP CS Fixer (if installed)
3. ✅ Check PSR-12 compliance with PHP_CodeSniffer (if installed)
4. ✅ Run PHPStan analysis (if installed)

commit-msg

The commit-msg hook validates the first line of your commit message:

1. ✅ Minimum 10 characters
2. ✅ Maximum 100 characters
3. ✅ Conventional Commits format

See docs/CONVENTIONAL_COMMITS.md for examples and guidance.

pre-push

Before pushing, the pre-push hook runs a full-project validation:

1. ✅ PHPUnit, if available in the target project
2. ✅ Full PHPStan analysis

This repository ships its own PHPUnit suite for the package itself. The installed pre-push hook is also designed for consumer projects and will run PHPUnit there when it is available. If PHPUnit is not installed in the target project, the hook skips that step and continues with the remaining checks.

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   CiHispano: Running Centralized Quality Checks
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  [1/4] Checking PHP syntax...
✔ Syntax is valid

  [2/4] Validating code style...
✔ Coding style verified

  [3/4] Sniffing code standards...
✔ Standards check passed

  [4/4] Running static analysis...
✔ Static analysis completed

  ✔ All checks passed! Proceeding with commit.

When a Check Fails

If any check fails, the commit will be blocked:

  [2/4] Validating code style...
✘ Style violations found.

Fix the issues and try again:

# Fix code style automatically
composer cs:fix

# Stage the fixed files
git add .

# Try committing again
git commit -S -m "Your message"

🛠️ Configuration

Project configuration (git-hooks.json)

An optional git-hooks.json file in the project root controls installer behavior:

{
    "auto_install": false,
    "build_dir": "build"
}

• auto_install (bool, default false): install hooks automatically on composer install/update. Without it (or with false), use composer install-hooks explicitly.
• build_dir (string, default build): QA cache directory (PHPStan, PHP CS Fixer, PHPUnit).
• composer init-hooks generates the file with defaults.
• Invalid JSON or wrong value types fail loudly — no silent fallback.

In consumer projects, automatic installation requires wiring the composer events in the project's own composer.json (scripts do not propagate from dependencies): "post-install-cmd": "CiHispano\\ComposerScripts::postInstall" (and post-update-cmd).

Skipping Hooks (Not Recommended)

If you need to commit without running the hooks:

git commit --no-verify -m "Emergency fix"

⚠️ Warning: Only use this in emergencies. Your code should always pass the quality checks.

Uninstalling Hooks

To remove the Git hooks:

composer uninstall-hooks

Customizing the Hooks

The hooks are located in your repository's hooks directory (usually .git/hooks/, but git-first resolution honors core.hooksPath and worktrees) after installation. You can modify them if needed, but keep in mind they will be overwritten when you update the package.

🔒 Trust boundary

The hooks execute repository-controlled code with your user's privileges:

• pre-commit runs the QA tools from vendor/bin (php-cs-fixer, phpcs, phpstan) against the staged files, using the project's own configs when present (.php-cs-fixer(.dist).php, phpcs.xml(.dist), phpstan.neon(.dist), phpunit.xml(.dist)).
• pre-push runs the project's PHPUnit suite and a full PHPStan analysis.

A malicious config file or vendor/bin tool in a checked-out branch can therefore run code on every developer's machine at the next commit/push. Install these hooks only in repositories you already trust — the repo config overrides the package defaults by design, and the trust model is documented in docs/INSTALLATION.md.

For the 0.1.0 line this is documentation only; a git-hooks.json allowlist to gate which configs and binaries the hooks may run is planned (see Roadmap).

📊 Composer Scripts

This package provides the following Composer scripts:

{
    "scripts": {
        "install-hooks": "CiHispano\\ComposerScripts::install",
        "uninstall-hooks": "CiHispano\\ComposerScripts::uninstall",
        "analyze": "@php -d xdebug.mode=off -d xdebug.log= vendor/bin/phpstan analyze --verbose",
        "check:all": [
            "@analyze",
            "@sniff",
            "@cs",
            "@test"
        ],
        "clear:cache": [
            "@php -r \"if (file_exists('build/.php-cs-fixer.cache')) unlink('build/.php-cs-fixer.cache');\"",
            "@php -r \"if (file_exists('build/phpstan.cache')) unlink('build/phpstan.cache');\"",
            "@php -r \"echo 'Cache cleared successfully' . PHP_EOL;\""
        ],
        "cs": "@php -d xdebug.mode=off -d xdebug.log= vendor/bin/php-cs-fixer fix --ansi --verbose --dry-run --diff",
        "cs:fix": "@php -d xdebug.mode=off -d xdebug.log= vendor/bin/php-cs-fixer fix --ansi --verbose --diff",
        "reset": [
            "@php scripts/reset.php",
            "@composer install --no-interaction --optimize-autoloader"
        ],
        "sniff": "@php -d xdebug.mode=off -d xdebug.log= vendor/bin/phpcs",
        "sniff:fix": "@php -d xdebug.mode=off -d xdebug.log= vendor/bin/phpcbf",
        "style": "@cs:fix",
        "test": "@php -d xdebug.mode=off -d xdebug.log= vendor/bin/phpunit --configuration phpunit.xml.dist --colors=always",
        "test:coverage": "@php -d xdebug.mode=coverage -d xdebug.start_with_request=yes vendor/bin/phpunit --configuration phpunit.xml.dist --colors=always --coverage-text --coverage-html build/coverage"
    }
}

Add these to your composer.json to access them easily:

composer install-hooks
composer uninstall-hooks
composer analyze
composer check:all
composer clear:cache
composer sniff
composer cs
composer cs:fix
composer sniff:fix
composer style
composer reset
composer test
composer test:coverage

composer reset removes installed dependencies and QA cache artifacts (vendor/, build/, .php-cs-fixer.cache, .phpunit.result.cache) and reinstalls everything from scratch, keeping composer.lock for reproducible validation. Run it before validating each feature, fix, or bug.

🔧 Integration with Existing Projects

With PHPStan

Add PHPStan to your project:

composer require --dev phpstan/phpstan

Create phpstan.neon:

parameters:
    level: max
    paths:
        - app

With PHP CS Fixer

Add PHP CS Fixer to your project:

composer require --dev friendsofphp/php-cs-fixer

Create .php-cs-fixer.dist.php:

<?php

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$finder = Finder::create()
    ->in(__DIR__ . '/app')
    ->name('*.php');

return (new Config())
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder($finder);

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or merge request.

Development Setup

# Clone the repository
git clone https://github.com/cihispano/git-hooks.git
cd git-hooks

# Install dependencies
composer install

# Run all active quality checks
composer check:all

# Or run them individually
composer analyze
composer sniff
composer cs
composer test

# Fix code style
composer cs:fix

# Generate coverage locally
composer test:coverage

Test Suite

• composer analyze
• composer sniff
• composer cs
• composer test

For a full local validation pass, run composer check:all. If you want an HTML coverage report, run composer test:coverage and open the generated files under build/coverage/.

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🔒 Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

📄 License

The MIT License (MIT). Please see License File for more information.

👥 Credits

• Jorge Armando Pacheco
• All Contributors

🌟 Support

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📖 Improving documentation
• 🔀 Contributing code

📚 Related Packages

• codeigniter4/framework - The CodeIgniter 4 framework
• phpstan/phpstan - PHP Static Analysis Tool
• friendsofphp/php-cs-fixer - PHP Coding Standards Fixer

Made with ❤️ for the CodeIgniter community