PHPackages sojeda/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. sojeda/conventional-commits ActiveLibrary[Utility & Helpers](/categories/utility) sojeda/conventional-commits =========================== A PHP library for creating and validating commit messages according to the Conventional Commits specification. Includes a CaptainHook action! 1.5.3(2y ago)012.3k↓11.1%MITPHPPHP ^8.1 Since Apr 3Pushed 2y agoCompare [ Source](https://github.com/sojeda/conventional-commits)[ Packagist](https://packagist.org/packages/sojeda/conventional-commits)[ GitHub Sponsors](https://github.com/ramsey)[ RSS](/packages/sojeda-conventional-commits/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (28)Versions (4)Used By (0) 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) [![Psalm Type Coverage](https://camo.githubusercontent.com/ae653e90a721af05b44574d7aa0ad5e23ed0d212a1fd7fb715e0032d2c1fd9fe/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742d7371756172652675726c3d687474707325334125324625324673686570686572642e64657625324667697468756225324672616d736579253246636f6e76656e74696f6e616c2d636f6d6d697473253246636f766572616765)](https://shepherd.dev/github/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": "\\Sojeda\\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": "\\Sojeda\\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": "\\Sojeda\\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": "\\Sojeda\\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": "\\Sojeda\\CaptainHook\\ValidateConventionalCommit", "options": { "configFile": "./conventional-commits.json" } } ] }, "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Sojeda\\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 30 — LowBetter than 64% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity25 Limited adoption so far Community11 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 75.8% 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 ~0 days Total 3 Last Release 774d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/43c1b01d111613ace208748153922a7e78e62534255b18b787ac041a7eff7ca0?d=identicon)[soj3da](/maintainers/soj3da) --- Top Contributors [![ramsey](https://avatars.githubusercontent.com/u/42941?v=4)](https://github.com/ramsey "ramsey (100 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (22 commits)")[![hussainweb](https://avatars.githubusercontent.com/u/1040271?v=4)](https://github.com/hussainweb "hussainweb (4 commits)")[![sojeda](https://avatars.githubusercontent.com/u/17851841?v=4)](https://github.com/sojeda "sojeda (4 commits)")[![Lewiscowles1986](https://avatars.githubusercontent.com/u/2605791?v=4)](https://github.com/Lewiscowles1986 "Lewiscowles1986 (2 commits)") --- Tags plugingitHOOKcommitconventional-commitscommit-msgconventionalcaptainhook ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/sojeda-conventional-commits/health.svg) ``` [![Health](https://phpackages.com/badges/sojeda-conventional-commits/health.svg)](https://phpackages.com/packages/sojeda-conventional-commits) ``` ### Alternatives [ramsey/conventional-commits A PHP library for creating and validating commit messages according to the Conventional Commits specification. Includes a CaptainHook action! 1931.2M122](/packages/ramsey-conventional-commits)[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) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)