PHPackages voral/version-increment - 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. voral/version-increment ActiveLibrary[Utility & Helpers](/categories/utility) voral/version-increment ======================= A tool for semantic versioning and changelog generation in Composer projects based on Git commits. 3.2.0(5mo ago)42317MITPHPPHP >=8.1CI passing Since Mar 19Pushed 5mo ago1 watchersCompare [ Source](https://github.com/Voral/vs-version-incrementor)[ Packagist](https://packagist.org/packages/voral/version-increment)[ Docs](https://github.com/Voral/vs-version-incrementor)[ RSS](/packages/voral-version-increment/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (5)Versions (12)Used By (7) Semantic Version Update ======================= [](#semantic-version-update) [RU](https://github.com/Voral/vs-version-incrementor/blob/master/README.ru.md) [![Scrutinizer Code Quality](https://camo.githubusercontent.com/bb2537f67eee25041b9480e6c3905630ccc5a255b095559a4a1ffadc06486273/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f566f72616c2f76732d76657273696f6e2d696e6372656d656e746f722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/51748a1fa6cd32456bf91314d1ad41d16feee02bfc249e98a79d524f087ad85b/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f566f72616c2f76732d76657273696f6e2d696e6372656d656e746f722f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/?branch=master)[![Code Intelligence Status](https://camo.githubusercontent.com/8afba630cdd8687d8d066aacf91f13a6dffa0e133c65ee6007485eff386ae68b/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f566f72616c2f76732d76657273696f6e2d696e6372656d656e746f722f6261646765732f636f64652d696e74656c6c6967656e63652e7376673f623d6d6173746572)](https://scrutinizer-ci.com/code-intelligence) [![PHP Tests](https://github.com/Voral/vs-version-incrementor/actions/workflows/php.yml/badge.svg)](https://github.com/Voral/vs-version-incrementor/actions/workflows/php.yml/badge.svg) This tool automates the process of version management in Composer-based projects by analyzing Git commits and generating a `CHANGELOG`. It adheres to [semantic versioning](https://semver.org/) and supports the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. The version follows the semantic rule `..`: - *Major*: Breaking changes that affect backward compatibility. - *Minor*: New features added without breaking existing functionality. - *Patch*: Bug fixes or minor improvements. Key Features ------------ [](#key-features) - **Version Management**: Automatically determines the next version based on commit analysis and updates `composer.json`. - **Git Integration**: Creates Git tags for releases and handles commits according to the project's versioning strategy. - **Customizable Commit Types**: Define custom commit types and their impact on version increments (`major`, `minor`, `patch`). - **Advanced CHANGELOG Generation**: - Supports custom formatting for the `CHANGELOG.md` file. - Option to hide duplicate entries within the same section for cleaner output. - Configurable scope preservation for specific commit types. - **Support for Squashed Commits**: Handles squashed commits (e.g., from `git merge --squash`) by parsing detailed descriptions. - **Configurable Rules**: Implement custom rules for categorizing commits into sections. - **Flexible Configuration**: - Customize the main branch name (e.g., `main` instead of `master`). - Configure release-related settings, such as release scope and section. - Ignore untracked files during version updates. - **Semantic Versioning Compliance**: Ensures strict adherence to semantic versioning principles. - **Optional Composer Versioning**: Disable version updates in `composer.json` if versioning is managed solely through Git tags. - **Extensibility**: - Use custom parsers, formatters, and VCS executors for advanced workflows. - Extend functionality with custom properties via the `Config` class. ### Why Use This Tool? [](#why-use-this-tool) - Simplifies version management by automating repetitive tasks. - Improves consistency in versioning and changelog generation. - Provides flexibility for custom workflows and project-specific requirements. - Reduces human error by relying on automated analysis of commit messages. Installation ------------ [](#installation) ``` composer require --dev voral/version-increment ``` ### Usage [](#usage) ``` # Automatic detection of release type ./vendor/bin/vs-version-increment # Incrementing the major version ./vendor/bin/vs-version-increment major # Incrementing the minor version ./vendor/bin/vs-version-increment minor # Incrementing the patch version ./vendor/bin/vs-version-increment patch ``` Utility help command ``` ./vendor/bin/vs-version-increment --help ``` Retrieving the list of registered commit types and registered scopes ``` ./vendor/bin/vs-version-increment --list ``` Execute all file updates (e.g., CHANGELOG.md, composer.json) but skip creating the final Git commit and version tag ``` ./vendor/bin/vs-version-increment --no-commit ``` The `--debug` flag allows you to preview the changes that will be made to the CHANGELOG and version without actually applying them ``` # Automatic detection of release type ./vendor/bin/vs-version-increment --debug # Incrementing the major version ./vendor/bin/vs-version-increment --debug major # Incrementing the minor version ./vendor/bin/vs-version-increment --debug minor # Incrementing the patch version ./vendor/bin/vs-version-increment --debug patch ``` To simplify usage, you can add scripts to `composer.json`: ``` { "scripts": { "vi:major": "php ./vendor/bin/vs-version-increment major", "vi:minor": "php ./vendor/bin/vs-version-increment minor", "vi:patch": "php ./vendor/bin/vs-version-increment patch", "vi:auto": "php ./vendor/bin/vs-version-increment", "vi:list": "php ./vendor/bin/vs-version-increment --list", "vi:debug:auto": "php ./vendor/bin/vs-version-increment --debug" }, "scripts-descriptions": { "vi:major": "Increment major version and update CHANGELOG.md", "vi:minor": "Increment minor version and update CHANGELOG.md", "vi:patch": "Increment patch version and update CHANGELOG.md", "vi:auto": "Auto-detect version increment based on commit analysis", "vi:list": "Display registered commit types and scopes", "vi:debug:auto": "Preview auto-detected changes without applying them" } } ``` Example of the output file: ``` # 1.0.1 (2023-10-01) ### Features - New endpoint user authentication - Added support dark mode ### Fixes - Fixed a bug with login form validation - Resolved issue with incorrect API response ### Other - Updated dependencies ``` Configuration ------------- [](#configuration) You can configure the script by placing a `.vs-version-increment.php` file in the project directory and making the following adjustments: - [Setting a Custom List of Change Types](docs/config.md#setting-a-custom-list-of-change-types) - [Configuring Change Types](docs/config.md#configuring-change-types) - [Configuring the Release Commit Type](docs/config.md#configuring-the-release-commit-type) - [Configuring the Main Repository Branch](docs/config.md#configuring-the-main-repository-branch) - [Configuring Types for Major Version Updates](docs/config.md#configuring-types-for-major-version-updates) - [Configuring Types for Minor Version Updates](docs/config.md#configuring-types-for-minor-version-updates) - [Release Scope Configuration](docs/config.md#release-scope-configuration) - [Custom Type Distribution Rules Setup](docs/config.md#custom-type-distribution-rules-setup) - [Ignoring Untracked Files](docs/config.md#ignoring-untracked-files) - [Configuring CHANGELOG Formatting](docs/config.md#configuring-changelog-formatting) - [Using a Scope-Preserving Formatter](docs/config.md#using-a-scope-preserving-formatter) - [Configuring Human-Readable Titles for Scopes](docs/config.md#configuring-human-readable-titles-for-scopes) - [Creating a Custom Formatter](docs/config.md#creating-a-custom-formatter) - [Configuring Squashed Commits](docs/config.md#configuring-squashed-commits) - [Default Squashed Commit](docs/config.md#default-squashed-commit) - [Defining Squashed Commits via a Group](docs/config.md#defining-squashed-commits-via-a-group) - [Combined Definition of a Squashed Commit](docs/config.md#combined-definition-of-a-squashed-commit) - [General Rules for Full Commit Descriptions](docs/config.md#general-rules-for-full-commit-descriptions) - [Configuring the Commit Description Parser](docs/config.md#configuring-the-commit-description-parser) - [Disabling Version Updates in composer.json](docs/config.md#disabling-version-updates-in-composerjson) - [Sets a custom property in the configuration](docs/config.md#sets-a-custom-property-in-the-configuration) - [Suppress Duplicate Lines in CHANGELOG](docs/config.md#suppress-duplicate-lines-in-changelog) Commit Descriptions ------------------- [](#commit-descriptions) For the tool to function correctly, commit descriptions must follow this format: ``` [(scope)][!]: [body] ``` - *type*: The commit type. It is recommended to use a predefined list for the project. Changes are grouped in the changelog by type. Unregistered types fall under the default category. The type configured as related to new functionality (default: `feat`) affects the minor version during automatic detection. - *scope* (optional): The project area to which the commit applies. - *!*: Indicates that the commit breaks backward compatibility. During automatic detection, this triggers a major version update. - *description*: A short description. - *body*: Detailed description (not used by the tool). Examples: ``` feat(router): New endpoint ``` ``` doc: Described all features ``` ``` feat!: Removed old API endpoints ``` Default Commit Types -------------------- [](#default-commit-types) TypePurpose`feat`Adding new functionality`fix`Fixing bugs`chore`Routine tasks (e.g., dependency updates)`docs`Documentation changes`style`Code formatting (indentation, spaces, etc.)`refactor`Refactoring code without adding new features or fixing bugs`test`Adding or modifying tests`perf`Performance optimization`ci`Continuous integration (CI) configuration`build`Changes related to project build`other`All other changes that do not fall under standard categoriesCI/CD Integration ----------------- [](#cicd-integration) The script can be integrated into CI/CD pipelines. In case of errors, it returns different exit codes: CodeDescription10Composer configuration error20Git branch is not the main branch30Uncommitted changes in the repository40No changes in the repository50Invalid configuration file60Error executing a Git command70Invalid version change type80Changelog File Error90Unknown config property100Configuration is not set110Failed to retrieve files since tag500Other errors≥5000User-defined custom errorsYou can use it in the command line, for example: ``` ./vendor/bin/vs-version-increment && echo 'Ok' || echo 'Error' ``` Example for GitHub Actions: ``` jobs: version-update: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v3 - name: Run version increment script run: ./vendor/bin/vs-version-increment ``` Event Handling with EventBus ---------------------------- [](#event-handling-with-eventbus) The module includes an `EventBus` for handling events that occur during the utility's operation. This allows developers to create custom event handlers and extend the tool's functionality. ### Key Features: [](#key-features-1) - **Event Subscription**: Developers can subscribe to various events, such as the start of a version update, successful completion, or error occurrence. - **Custom Event Handlers**: You can implement custom event handlers to perform additional actions, such as logging or sending notifications. The handler must implement the `\Vasoft\VersionIncrement\Contract\EventListenerInterface`interface. ### Example Usage: [](#example-usage) ``` use Vasoft\VersionIncrement\Events\EventType; use Vasoft\VersionIncrement\Config; use Vasoft\VersionIncrement\Contract\EventListenerInterface; use Vasoft\VersionIncrement\SemanticVersionUpdater; class Listener implements EventListenerInterface { public function handle(\Vasoft\VersionIncrement\Events\Event $event): void { print_r([ $event->getData(SemanticVersionUpdater::LAST_VERSION_TAG) ?? 'unknown', $event->eventType->name, ]); } } $listener = new Listener(); $config = new Config(); $eventBus = $config->getEventBus(); $eventBus->addListener(EventType::BEFORE_VERSION_SET, $listener); $eventBus->addListener(EventType::AFTER_VERSION_SET, $listener); $eventBus->addListener(EventType::ON_ERROR, $listener); ``` ### Available Event Types: [](#available-event-types) Event TypeDescription`BEFORE_VERSION_SET`Triggered before the version update begins.`AFTER_VERSION_SET_SUCCESS`Triggered after the version update completes successfully.`AFTER_VERSION_SET_ERROR`Triggered when an error occurs.### Recommendations: [](#recommendations) - Use `EventBus` to integrate third-party systems, such as monitoring or notification systems. - Ensure that your event handlers do not slow down the main execution process of the utility. Error Handling for Custom Extensions ------------------------------------ [](#error-handling-for-custom-extensions) When developing custom extensions or integrations for this tool, it is important to handle errors consistently and avoid conflicts with system-defined error codes. To achieve this, developers should use the `UserException` class for all custom error scenarios. ### Key Points: [](#key-points) - **Reserved Error Codes**: The `UserException` class ensures that all user-defined error codes are offset by `5000`. This guarantees that custom error codes do not overlap with system-defined codes (below `5000`). - **Usage Example**: ``` use Vasoft\VersionIncrement\Exceptions\UserException; throw new UserException( code: 100, // Your custom error code (will be converted to 5100) message: 'Custom error message describing the issue.' ); ``` - **Best Practices**: - Use descriptive error messages to help users understand the cause of the error. - Document the meaning of custom error codes in your extension's documentation. - Avoid using error codes below `5000`, as these are reserved for system-defined errors. By adhering to these guidelines, you can ensure seamless integration of your custom extensions with the tool while maintaining clarity and consistency in error handling. Configuration Examples ---------------------- [](#configuration-examples) To help you get started with the library more quickly, I provide ready-to-use configuration examples for various use cases. ### 1. Configuration for Keep a Changelog [](#1-configuration-for-keep-a-changelog) This configuration example is designed for projects that follow the [Keep a Changelog](https://keepachangelog.com/)standard. It organizes changes into categories (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`), making the changelog easy to read. - *File:* [`examples/keepachangelog.php`](https://github.com/Voral/vs-version-incrementor/blob/master/examples/keepachangelog.php) Useful Links ------------ [](#useful-links) - [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) - [Semantic Versioning](https://semver.org/) - [Project Repository](https://github.com/Voral/vs-version-incrementor) ### Health Score 41 — FairBetter than 89% of packages Maintenance69 Regular maintenance activity Popularity18 Limited adoption so far Community15 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~24 days Recently: every ~53 days Total 11 Last Release 178d ago Major Versions 1.3.0 → 2.0.02025-04-15 2.1.1 → 3.0.02025-05-15 ### Community Maintainers ![](https://www.gravatar.com/avatar/ce4dfd67b12e198becd71253723d0c83044cb4689b735f2fd4eee4ac191c41ec?d=identicon)[Voral](/maintainers/Voral) --- Top Contributors [![Voral](https://avatars.githubusercontent.com/u/327165?v=4)](https://github.com/Voral "Voral (129 commits)") --- Tags changelogchangelog-generatorcomposerconventional-changelogconventional-commitsgitphpsemantic-versioningsemverversion-incrementcomposergitcommit analysisPHP Librarychangelogversion controlconventional-commitssemantic versioningversion-managementdev-toolphp toolversion incrementchangelog generatorgit integrationautomated versioningrelease managementchangelog formattingautomation tool ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/voral-version-increment/health.svg) ``` [![Health](https://phpackages.com/badges/voral-version-increment/health.svg)](https://phpackages.com/packages/voral-version-increment) ``` ### 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)[pyrech/composer-changelogs Display changelogs after each composer update 5904.0M25](/packages/pyrech-composer-changelogs)[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)[balbuf/composer-git-merge-driver Custom git merge driver to minimize merge conflicts in composer.json and composer.lock files. 137268.0k](/packages/balbuf-composer-git-merge-driver)[salehhashemi/laravel-intelli-git An intelligent Git helper package for Laravel applications. It utilizes OpenAI's GPT to analyze your Git repository, providing features such as automatic generation of commit messages based on staged changes. 131.5k](/packages/salehhashemi-laravel-intelli-git) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)