PHPackages ramsey/conventional-commits - 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. ramsey/conventional-commits ActiveLibrary[Utility & Helpers](/categories/utility) ramsey/conventional-commits =========================== A PHP library for creating and validating commit messages according to the Conventional Commits specification. Includes a CaptainHook action! 1.7.0(2mo ago)1931.2M—7.4%24[9 issues](https://github.com/ramsey/conventional-commits/issues)[3 PRs](https://github.com/ramsey/conventional-commits/pulls)20MITPHPPHP ^8.1CI passing Since Aug 13Pushed 2mo ago3 watchersCompare [ Source](https://github.com/ramsey/conventional-commits)[ Packagist](https://packagist.org/packages/ramsey/conventional-commits)[ GitHub Sponsors](https://github.com/ramsey)[ RSS](/packages/ramsey-conventional-commits/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (50)Versions (16)Used By (20) ramsey/conventional-commits =========================== [](#ramseyconventional-commits) **A PHP library for creating and validating commit messages.** [![Source Code](https://camo.githubusercontent.com/abe5472570e53c68c125cf732577eb2a9624c69b122275ac912d53412b822a1b/687474703a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d72616d7365792f636f6e76656e74696f6e616c2d2d636f6d6d6974732d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/ramsey/conventional-commits) [![Download Package](https://camo.githubusercontent.com/ce1cdf7bfd7a26f31127755197a92e335756607f72bab5c637c1cee79a245fd4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72616d7365792f636f6e76656e74696f6e616c2d636f6d6d6974732e7376673f7374796c653d666c61742d737175617265266c6162656c3d72656c65617365)](https://packagist.org/packages/ramsey/conventional-commits) [![PHP Programming Language](https://camo.githubusercontent.com/eae794bfde258de6098acebc5bf356db9c0b94e653549f2a066bda6a9cfa5ac5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f72616d7365792f636f6e76656e74696f6e616c2d636f6d6d6974732e7376673f7374796c653d666c61742d73717561726526636f6c6f72423d253233383839324246)](https://php.net) [![Read License](https://camo.githubusercontent.com/df5cdfc911655483ae2798de6467bc8f6b6f23c7c9115229c5f8a0bca9e2e3c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f72616d7365792f636f6e76656e74696f6e616c2d636f6d6d6974732e7376673f7374796c653d666c61742d73717561726526636f6c6f72423d6461726b6379616e)](https://github.com/ramsey/conventional-commits/blob/main/LICENSE) [![Build Status](https://camo.githubusercontent.com/fab51091e05a876c2836d72aec8e38bc47da472a447f77dd53a81fe44e90280d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f72616d7365792f636f6e76656e74696f6e616c2d636f6d6d6974732f636f6e74696e756f75732d696e746567726174696f6e2e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6f676f3d676974687562)](https://github.com/ramsey/conventional-commits/actions/workflows/continuous-integration.yml) [![Codecov Code Coverage](https://camo.githubusercontent.com/9f8f628b40285932c9cb6ff63a539af4698d2f2a6baa63b56bcb384491a8865f/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f67682f72616d7365792f636f6e76656e74696f6e616c2d636f6d6d6974733f6c6162656c3d636f6465636f76266c6f676f3d636f6465636f76267374796c653d666c61742d737175617265)](https://codecov.io/gh/ramsey/conventional-commits) About ----- [](#about) ramsey/conventional-commits is a PHP library for creating and validating commit messages according to the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/). It also includes a [CaptainHook](https://github.com/captainhookphp/captainhook) action! This project adheres to a [code of conduct](CODE_OF_CONDUCT.md). By participating in this project and its community, you are expected to uphold this code. Installation ------------ [](#installation) Install this package as a development dependency using [Composer](https://getcomposer.org). ``` composer require --dev ramsey/conventional-commits ``` Usage ----- [](#usage) To use the `conventional-commits` console command to help you prepare commit messages according to Conventional Commits, enter the following in your console: ``` ./vendor/bin/conventional-commits prepare ``` You can also validate the commit message using the following command: ``` ./vendor/bin/conventional-commits validate "[commit message]" ``` If you don't provide a commit message in the command line, the command will prompt you for it. To see all the features of the console command, enter: ``` ./vendor/bin/conventional-commits ``` ### CaptainHook Action [](#captainhook-action) To use ramsey/conventional-commits with CaptainHook as part of your `commit-msg`and/or `prepare-commit-msg` Git hooks, be sure to require CaptainHook as a development dependency. Check out the [CaptainHook documentation](https://github.com/captainhookphp/captainhook)for more information on installing and configuring CaptainHook. #### Validating Commit Messages [](#validating-commit-messages) To use the CaptainHook action to validate commit messages according to the Conventional Commits specification, add the following to the `commit-msg`property in your `captainhook.json` file: ``` { "commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\ValidateConventionalCommit" } ] } } ``` #### Preparing Commit Messages [](#preparing-commit-messages) You can set up this library to prompt you to prepare commit messages when you use `git commit`! To use the CaptainHook action to prepare commit messages according to the Conventional Commits specification, add the following to the `prepare-commit-msg`property in your `captainhook.json` file: ``` { "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\PrepareConventionalCommit" } ] } } ``` ### Configuration [](#configuration) Configuring ramsey/conventional-commits offers control over a few more aspects of commit messages, such as letter case (i.e. lower, upper), allowed types and scopes, required footers, and more. We look for configuration in one of two places: - `composer.json` - `captainhook.json` > ⚠️ **Please note:** if your `composer.json` file is not in the same location as the `vendor/` directory, we might have trouble locating it. Feel free to open an issue, and we'll work with you to see if we can find a solution. #### Configuration Properties [](#configuration-properties) Configuration for ramsey/conventional-commits consists of the following properties: PropertyDescription`typeCase`The letter case to require for the type. By default, any letter case is acceptable.`types`An array of accepted types (in addition to "feat" and "fix"). By default, any type is acceptable.`scopeCase`The letter case to require for the scope. By default, any letter case is acceptable.`scopeRequired`Whether a scope is required. By default, scope is not required.`scopes`An array of accepted scopes. By default, any scope is acceptable.`descriptionCase`The letter case to require for the description. By default, any letter case is acceptable.`descriptionEndMark`A character to require at the end of the description. By default, any character is allowed. Use an empty string to indicate a punctuation character is not allowed at the end of the description.`bodyRequired`Whether a body is required. By default, a body is not required.`bodyWrapWidth`An integer indicating the character width to auto-wrap the body of the commit message. By default, the commit body does not auto-wrap.`requiredFooters`An array of footers that must be provided. By default, footers are not required.When specifying configuration, if you wish to use the default behavior for a property, it is not necessary to list the property in your configuration. Recognized letter cases are: IdentifierNameExample`ada`Ada case`The_Quick_Brown_Fox``camel`Camel case`theQuickBrownFox``cobol`COBOL case`THE-QUICK-BROWN-FOX``dot`Dot notation`the.quick.brown.fox``kebab`Kebab case`the-quick-brown-fox``lower`Lower case`the quick brown fox``macro`Macro case`THE_QUICK_BROWN_FOX``pascal`Pascal case`TheQuickBrownFox``sentence`Sentence case`The quick brown fox``snake`Snake case`the_quick_brown_fox``title`Title case`The Quick Brown Fox``train`Train case`The-Quick-Brown-Fox``upper`Upper case`THE QUICK BROWN FOX`#### Configuration in composer.json [](#configuration-in-composerjson) If you choose to put your configuration in `composer.json`, place it within the `extra` property, namespaced under `ramsey/conventional-commits`, like this: ``` { "extra": { "ramsey/conventional-commits": { "config": { "typeCase": null, "types": [], "scopeCase": null, "scopeRequired": false, "scopes": [], "descriptionCase": null, "descriptionEndMark": null, "bodyRequired": false, "bodyWrapWidth": null, "requiredFooters": [] } } } } ``` > 📝 The properties in this example represent the default values. #### Configuration in captainhook.json [](#configuration-in-captainhookjson) If you choose to put your configuration in `captainhook.json`, you must provide it for *each action* you configure, like this: ``` { "commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\ValidateConventionalCommit", "options": { "config": { "typeCase": null, "types": [], "scopeCase": null, "scopeRequired": false, "scopes": [], "descriptionCase": null, "descriptionEndMark": null, "bodyRequired": false, "bodyWrapWidth": null, "requiredFooters": [] } } } ] }, "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\PrepareConventionalCommit", "options": { "config": { "typeCase": null, "types": [], "scopeCase": null, "scopeRequired": false, "scopes": [], "descriptionCase": null, "descriptionEndMark": null, "bodyRequired": false, "bodyWrapWidth": null, "requiredFooters": [] } } } ] } } ``` However, if you provide your configuration in `composer.json`, it is not necessary to also provide it in `captainhook.json`. > 🚨 If using the Git commit hook functionality of Captain Hook, any configuration provided in `captainhook.json` will override configuration in `composer.json`. > > ⚠️ When using the standalone command (i.e. `./vendor/bin/conventional-commits`), only configuration in `composer.json` will apply, unless providing the `--config` option. #### Configuration in a Separate File [](#configuration-in-a-separate-file) You may also store your configuration in a separate file. For example, you may store it in `conventional-commits.json`, like this: ``` { "typeCase": "kebab", "types": [ "ci", "deps", "docs", "refactor", "style", "test" ], "scopeCase": "kebab", "scopeRequired": false, "scopes": [], "descriptionCase": "lower", "descriptionEndMark": "", "bodyRequired": true, "bodyWrapWidth": 72, "requiredFooters": ["Signed-off-by"] } ``` When stored in a separate file, we won't know where to look for your configuration, unless you tell us, so you must still provide a small amount of configuration in either `composer.json` or `captainhook.json`, so we can find it. Here's what this looks like in `composer.json`: ``` { "extra": { "ramsey/conventional-commits": { "configFile": "./conventional-commits.json" } } } ``` And here's what this looks like in `captainhook.json`: ``` { "commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\ValidateConventionalCommit", "options": { "configFile": "./conventional-commits.json" } } ] }, "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\PrepareConventionalCommit", "options": { "configFile": "./conventional-commits.json" } } ] } } ``` Contributing ------------ [](#contributing) Contributions are welcome! To contribute, please familiarize yourself with [CONTRIBUTING.md](CONTRIBUTING.md). Coordinated Disclosure ---------------------- [](#coordinated-disclosure) Keeping user information safe and secure is a top priority, and we welcome the contribution of external security researchers. If you believe you've found a security issue in software that is maintained in this repository, please read [SECURITY.md](SECURITY.md) for instructions on submitting a vulnerability report. Copyright and License --------------------- [](#copyright-and-license) The ramsey/conventional-commits library is copyright © [Ben Ramsey](https://benramsey.com)and licensed for use under the terms of the MIT License (MIT). Please see [LICENSE](LICENSE) for more information. ### Health Score 66 — FairBetter than 99% of packages Maintenance85 Actively maintained with recent releases Popularity58 Moderate usage in the ecosystem Community37 Small or concentrated contributor base Maturity71 Established project with proven stability Bus Factor1 Top contributor holds 76.4% 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 ~169 days Recently: every ~270 days Total 13 Last Release 75d ago PHP version history (2 changes)1.0.0PHP ^7.4 || ^8 1.5.0PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/f514481fa9cfdfd5dbcaccb3e5b480f18ea05ebf331cddf9b1c5a2a96a78fef5?d=identicon)[ramsey](/maintainers/ramsey) --- Top Contributors [![ramsey](https://avatars.githubusercontent.com/u/42941?v=4)](https://github.com/ramsey "ramsey (120 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (24 commits)")[![llupa](https://avatars.githubusercontent.com/u/41073314?v=4)](https://github.com/llupa "llupa (4 commits)")[![hussainweb](https://avatars.githubusercontent.com/u/1040271?v=4)](https://github.com/hussainweb "hussainweb (4 commits)")[![Lewiscowles1986](https://avatars.githubusercontent.com/u/2605791?v=4)](https://github.com/Lewiscowles1986 "Lewiscowles1986 (2 commits)")[![aadmathijssen](https://avatars.githubusercontent.com/u/3796971?v=4)](https://github.com/aadmathijssen "aadmathijssen (1 commits)")[![nick-lai](https://avatars.githubusercontent.com/u/7104395?v=4)](https://github.com/nick-lai "nick-lai (1 commits)")[![delolmo](https://avatars.githubusercontent.com/u/659868?v=4)](https://github.com/delolmo "delolmo (1 commits)") --- Tags captainhookcommitcommit-msgconventionalconventional-commitsgithookphppluginplugingitHOOKcommitconventional-commitscommit-msgconventionalcaptainhook ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/ramsey-conventional-commits/health.svg) ``` [![Health](https://phpackages.com/badges/ramsey-conventional-commits/health.svg)](https://phpackages.com/packages/ramsey-conventional-commits) ``` ### Alternatives [marcocesarato/php-conventional-changelog Generate changelogs and release notes from a project's commit messages and metadata and automate versioning with semver.org and conventionalcommits.org 2511.3M109](/packages/marcocesarato-php-conventional-changelog)[captainhook/captainhook PHP git hook manager 1.1k6.8M370](/packages/captainhook-captainhook)[vaimo/composer-patches Applies a patch from a local or remote file to any package that is part of a given composer project. Patches can be defined both on project and on package level. Optional support for patch versioning, sequencing, custom patch applier configuration and patch command for testing/troubleshooting added patches. 2994.3M16](/packages/vaimo-composer-patches)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core)[nilportugues/php_backslasher Adds all PHP internal functions to its namespace by adding backslash to them. Improves the application's performance when OPCache is on. 889.3k18](/packages/nilportugues-php-backslasher)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)