Download the PHP package dev-kraken/php-commitlint without Composer

PHP CommitLint 🎯

A powerful Git hooks and commit message linting tool for PHP projects - combining the best of husky and commitlint in a native PHP implementation.

🚀 Features

• 🎯 Commit Message Validation - Enforce conventional commit format with customizable rules
• 🪝 Git Hooks Management - Easy installation and management of Git hooks
• ⚙️ Flexible Configuration - Configure via .commitlintrc.json or composer.json
• 🔧 Developer Friendly - Beautiful CLI output with helpful error messages
• 📦 Zero Dependencies - Pure PHP implementation using only Symfony Console
• 🧪 Fully Tested - Comprehensive test suite with Pest
• 🎨 Modern PHP - PHP 8.3+ with strict types and modern syntax
• 🔒 Security First - Built-in security features and input validation
• 🎛️ Custom Hooks - Add your own git hooks with custom commands

📦 Installation

Install via Composer:

🔧 Quick Start

1. Install Git Hooks

2. Start Making Commits!

📋 Commands

Install Hooks

Install Git hooks and create default configuration:

Options:

• --force, -f - Force installation even if hooks already exist
• --skip-config - Skip creating default configuration file

Validate Commit Message

Validate commit messages against your configuration:

Options:

• --file, -f - Read commit message from specific file
• --quiet, -q - Suppress output (exit code only)
• --verbose-errors - Show detailed error information

Manage Custom Hooks

Add and manage custom Git hooks:

Uninstall

Remove all installed Git hooks:

⚙️ Configuration

PHP CommitLint can be configured via .commitlintrc.json file or within your composer.json. The tool automatically merges your custom configuration with sensible defaults.

Configuration File Priority

1. .commitlintrc.json in your project root
2. extra.php-commitlint in composer.json
3. Default configuration

Complete Configuration Reference

Configuration Options Explained

General Settings

• auto_install (boolean, default: false) - Automatically install hooks when composer install/update runs

Rules Configuration

Type Rules (rules.type)

• required (boolean, default: true) - Whether commit type is required
• allowed (array, default: see above) - Array of allowed commit types

Scope Rules (rules.scope)

• required (boolean, default: false) - Whether commit scope is required
• allowed (array, default: []) - Array of allowed scopes (empty = any scope allowed)

Subject Rules (rules.subject)

• min_length (int, default: 1) - Minimum subject length
• max_length (int, default: 100) - Maximum subject length
• case (string, default: "any") - Case requirement: "lower", "upper", or "any"
• end_with_period (boolean, default: false) - Whether subject must end with period

Body Rules (rules.body)

• max_line_length (int, default: 100) - Maximum line length for body (0 = no limit)
• leading_blank (boolean, default: true) - Require blank line between subject and body

Footer Rules (rules.footer)

• leading_blank (boolean, default: true) - Require blank line between body and footer

Pattern Validation (patterns)

Define custom regex patterns for additional validation:

Hook Configuration (hooks)

Control which Git hooks are installed:

Team-Wide Pre-Commit Commands (pre_commit_commands)

Configure commands that run automatically for all team members during pre-commit:

Benefits:

• Automatic for all team members - No manual hook setup required
• Consistent quality checks - Same commands run for everyone
• Version controlled - Configuration is committed and shared
• Easy maintenance - Update once, applies to all developers

When any team member runs composer install (with auto_install: true), these commands automatically run before every commit.

Format Configuration (format)

• type (boolean) - Require commit type
• scope (string) - Scope requirement: "required", "optional", "forbidden"
• description (boolean) - Require commit description
• body (string) - Body requirement: "required", "optional", "forbidden"
• footer (string) - Footer requirement: "required", "optional", "forbidden"

🪟 Windows Support

PHP CommitLint provides full Windows compatibility with automatic detection and setup:

Automatic Windows Support

• PHP Detection: Automatically finds PHP in XAMPP, WAMP, Laragon, or standard installations
• Path Handling: Converts Windows paths for Git Bash compatibility
• Batch Wrapper: Includes php-commitlint.bat for Windows CLI
• Hook Compatibility: Git hooks work seamlessly in Git Bash, PowerShell, and Command Prompt

Windows Installation

Windows Troubleshooting

If you see "PHP CommitLint not found":

1. Ensure PHP is in your PATH: php --version
2. Try using the batch file: vendor\bin\php-commitlint.bat install
3. Check Git Bash compatibility: Use /c/path/to/php format

Common Windows Scenarios:

• XAMPP: C:\xampp\php\php.exe (automatically detected)
• WAMP: C:\wamp\bin\php\php8.3\php.exe (automatically detected)
• Laragon: C:\laragon\bin\php\php8.3\php.exe (automatically detected)
• Standalone: C:\php\php.exe (automatically detected)

📖 Example Configurations

Minimal Configuration (examples/commitlintrc.minimal.json)

Strict Configuration (examples/commitlintrc.strict.json)

Configuration in composer.json

You can also configure PHP CommitLint in your composer.json:

📝 Commit Message Format

This package enforces the Conventional Commits specification:

Examples

Default Commit Types

• feat - New features
• fix - Bug fixes
• docs - Documentation changes
• style - Code style changes (formatting, etc)
• refactor - Code refactoring
• perf - Performance improvements
• test - Adding or updating tests
• chore - Maintenance tasks
• ci - CI/CD changes
• build - Build system changes
• revert - Reverting previous commits

Special Commit Types (Auto-Skip Validation)

The following commit types automatically skip validation:

• Merge commits - Merge branch "feature" into main
• Revert commits - Revert "feat: add user authentication"
• Initial commits - Initial commit
• Fixup commits - fixup! feat: add user authentication

🛠️ Development & Testing

Running Tests

Code Quality

Available Make Commands

🔄 Integration with CI/CD

GitHub Actions

GitLab CI

🚨 Error Codes

PHP CommitLint uses specific exit codes for different error conditions:

• 0 - Success
• 1 - Validation failed
• 2 - Configuration error
• 3 - File system error
• 4 - Invalid argument
• 5 - Runtime error
• 6 - Permission denied
• 7 - Not a Git repository

🔒 Security Features

• Input validation for all commit message processing
• Safe command execution using Symfony Process component
• Configuration validation to prevent malicious configs
• Path traversal protection in file operations
• File size limits (100KB max for config files)
• No eval() or dynamic code execution
• Command validation prevents dangerous operations in custom hooks

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run the test suite (composer test)
5. Check code style (composer cs:check)
6. Run static analysis (composer analyse)
7. Commit your changes (git commit -m "feat: add amazing feature")
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by husky and commitlint
• Built with Symfony Console
• Tested with Pest

📚 Documentation

• 📖 API Documentation - Detailed API reference for developers
• ❓ FAQ - Frequently asked questions and troubleshooting
• 🤝 Contributing Guide - How to contribute to the project
• 📋 Changelog - Release notes and version history
• 🔒 Security Policy - Security guidelines and reporting

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ❓ FAQ: Frequently Asked Questions

Made with ❤️ by DevKraken