eliashaeussler/version-bumper

Composer plugin to bump project versions during release preparations

1.2.0 2024-10-03 18:33 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• composer-plugin-api: ^2.0
• cuyz/valinor: ^1.0
• czproject/git-php: ^4.3
• symfony/console: ^5.4 || ^6.4 || ^7.0
• symfony/filesystem: ^5.4 || ^6.4 || ^7.0
• symfony/yaml: ^5.4 || ^6.4 || ^7.0

Requires (Dev)

• armin/editorconfig-cli: ^1.8 || ^2.0
• composer/composer: ^2.2
• eliashaeussler/php-cs-fixer-config: ^2.0
• eliashaeussler/phpstan-config: ^2.0
• eliashaeussler/rector-config: ^3.0
• ergebnis/composer-normalize: ^2.30
• phpstan/extension-installer: ^1.2
• phpstan/phpstan-phpunit: ^1.1
• phpstan/phpstan-symfony: ^1.4
• phpunit/phpunit: ^10.2 || ^11.0

GPL-3.0-or-later

• Elias Häußler

README

Version Bumper

A Composer plugin to bump project versions during release preparations. Provides a Composer command bump-version and offers an easy-to-use PHP API for integration in other frameworks.

🔥 Installation

composer require --dev eliashaeussler/version-bumper

⚡ Usage

Console command bump-version

$ composer bump-version <range> [-c|--config CONFIG] [-r|--release] [--dry-run] [--strict]

Pass the following options to the console command:

• <range>: Version range to be bumped, can be one of:
  • major/maj: Bump version to next major version (1.2.3 -> 2.0.0)
  • minor/min: Bump version to next minor version (1.2.3 -> 1.3.0)
  • next/n/patch/p: Bump version to next patch version (1.2.3 -> 1.2.4)
  • Explicit version, e.g. 1.3.0
• -c/--config: Path to config file, defaults to auto-detection in current working directory, can be configured in composer.json as well (see config section below).
• -r/--release: Create a new Git tag after versions are bumped.
• --dry-run: Do not perform any write operations, just calculate and display version bumps.
• --strict: Fail if any unmatched file pattern is reported.

PHP API

The main entrypoint of the plugin is the Version\VersionBumper class.

use EliasHaeussler\VersionBumper;

// Define files and patterns in which to bump new versions
$filesToModify = [
    new VersionBumper\Config\FileToModify(
        'package.json',
        [
            '"version": "{%version%}"',
        ],
    ),
    new VersionBumper\Config\FileToModify(
        'src/Version.php',
        [
            'public const VERSION = \'{%version%}\';',
        ],
    ),
];

// Define package root path and version range
$rootPath = dirname(__DIR__);
$versionRange = VersionBumper\Enum\VersionRange::Minor;

// Bump versions within configured files
$versionBumper = new VersionBumper\Version\VersionBumper();
$results = $versionBumper->bump(
    $filesToModify,
    $rootPath,
    $versionRange,
);

// Display results
foreach ($results as $result) {
    // File: package.json
    echo sprintf('File: %s', $result->file()->path());
    echo PHP_EOL;

    foreach ($result->groupedOperations() as $operations) {
        foreach ($operations as $operation) {
            // Modified: 1.2.3 => 1.3.0
            echo sprintf(
                '%s: %s => %s',
                $operation->state()->name,
                $operation->source(),
                $operation->target(),
            );
            echo PHP_EOL;
        }
    }
}

A release can be created by the Version\VersionReleaser class:

use EliasHaeussler\VersionBumper;

$options = new VersionBumper\Config\ReleaseOptions(
    tagName: 'v{%version%}', // Create tag with "v" prefix
    signTag: true, // Sign new tags
);

$versionReleaser = new VersionBumper\Version\VersionReleaser();
$result = $versionReleaser->release($results, $rootPath, $options);

echo sprintf(
    'Committed "%s" and tagged "%s" with %d file(s).',
    $result->commitMessage(),
    $result->tagName(),
    count($result->committedFiles()),
);
echo PHP_EOL;

Tip

You can use the method argument $dryRun in both VersionBumper and VersionReleaser classes to skip any write operations (dry-run mode).

📝 Configuration

When using the console command, it is required to configure the write operations which are to be performed by the version bumper.

Formats

The following file formats are supported currently:

• json
• yaml, yml

Schema

The config file must follow a given schema:

filesToModify:
  - path: relative/or/absolute/path/to/file
    patterns:
      # Each pattern must contain a {%version%} placeholder
      - '"version": "{%version%}"'
    reportUnmatched: true
releaseOptions:
  commitMessage: '[RELEASE] Release of my-fancy-library {%version%}'
  overwriteExistingTag: true
  signTag: true
  tagName: 'v{%version%}'
# Relative (to config file) or absolute path to project root
rootPath: ../

Tip

Have a look at the shipped JSON schema.

Files to modify

Release options

Root path

Configuration in composer.json

The config file path can be passed as -c/--config command option or, alternatively, as configuration in composer.json:

{
    "extra": {
        "version-bumper": {
            "config-file": "path/to/version-bumper.json"
        }
    }
}

When configured as relative path, the config file path is calculated based on the location of the composer.json file.

Auto-detection

If no config file is explicitly configured, the config reader tries to auto-detect its location. The following order is taken into account during auto-detection:

1. version-bumper.json
2. version-bumper.yaml
3. version-bumper.yml

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 3.0 (or later).