README

Symfony bundle which provides a way to version your application using various versioning strategies.

Features

Stores the application's version and release date in a compliant YAML Symfony container configuration file
Automatically imports the file containing the parameters into Symfony's container
Supports multiple versioning strategies and the ability to create custom ones
Includes a console command for incrementing the version using the configured versioning strategy
Automatically commits the version file and optionally creates a tag if a VCS handler is configured
Supports Git VCS and allows creating custom VCS handlers

Requirements

PHP 8.1 or higher
Symfony 6.4 or Symfony 7.4 or higher

Installation

Require the bundle using Composer:

composer require bizkit/versioning-bundle

If your project doesn't use Symfony Flex, continue with the following steps:

Create a configuration file at config/packages/bizkit_versioning.yaml. Here's a reference configuration:

bizkit_versioning:

    # The prefix added to the version parameters.
    parameter_prefix:     application # Example: my_app

    # The versioning strategy used.
    strategy:             incrementing

    # The name of the file containing the version information.
    filename:             version

    # The path to the file containing the version information.
    filepath:             '%kernel.project_dir%/config'

    # The format used for the version file.
    format:               yaml # One of "yaml"

    # Configuration for the VCS integration,
    # set to false to disable the integration.
    vcs:

        # The handler used for the VCS integration,
        # set to null to disable the integration.
        handler:              git

        # The message to use for the VCS commit.
        commit_message:       'Update application version to %s'

        # The mode for applying tags to version commits:
        # - 'always': automatically add a tag without prompting
        # - 'ask': prompt before tagging when incrementing versions
        # - 'never': do not add a tag
        tagging_mode:         ask # One of "always"; "ask"; "never"

        # The message to use for the VCS tag.
        tag_message:          'Update application version to %s'

        # The name used for the VCS commit information,
        # set to null to use the default VCS configuration.
        name:                 null

        # The email used for the VCS commit information,
        # set to null to use the default VCS configuration.
        email:                null

        # The path to the VCS executable,
        # set to null for autodiscovery.
        path_to_executable:   null

Enable the bundle in config/bundles.php by adding it to the array:

Bizkit\VersioningBundle\BizkitVersioningBundle::class => ['all' => true],

Usage

The bundle creates a compliant Symfony Dependency Injection Container configuration file with the following parameters:

application.version - the application's version (the format depends on the configured versioning strategy)
application.version_hash - an MD5 digest of the version
application.release_date - an RFC 3339-formatted date on which the version was last incremented

NOTE: The parameter names may vary depending on the parameter_prefix configuration option.

It automatically adds the parameters into Symfony's container by registering the file as an import.

To learn more about parameters, see Symfony's official documentation. The following example shows how to use it with Sentry's Monolog handler:

monolog:
    sentry:
        type: sentry
        dsn: '%sentry_dsn%'
        release: '%application.version%'

Incrementing the version

To increment the version using the configured strategy, run the following command:

bin/console bizkit:versioning:increment

If a VCS handler is configured, the command will automatically commit the version file and optionally create a tag with the new version.

Versioning strategies

The bundle comes with the following version strategies:

incrementing - defines the version as an incrementing number
semver - uses the Semantic Versioning system

Custom strategies

To implement a custom strategy, create a service that implements the StrategyInterface interface.

namespace App;

use Bizkit\VersioningBundle\Strategy\StrategyInterface;

class MyStrategy implements StrategyInterface
{
    public function __invoke(StyleInterface $io, ?Version $version = null): Version
    {
        if (null === $version) {
            // return initial version
        }

        // return incremented version
    }
}

Use the FQCN of the service in the configuration:

bizkit_versioning:
    strategy: App\MyStrategy

If you are not using Symfony's autoconfigure feature or wish to use an alias in the configuration, tag the service with the bizkit_versioning.strategy tag:

App\MyStrategy:
    tags:
        - { name: 'bizkit_versioning.strategy', alias: 'my_strategy' }

bizkit_versioning:
    strategy: my_strategy

VCS handlers

The bundle includes a handler for the Git VCS. To disable the VCS feature, set the vcs configuration option to false:

bizkit_versioning:
    vcs: false

Custom VCS handlers

To implement a custom VCS handler, create a service that implements the VCSHandlerInterface interface:

namespace App;

use Bizkit\VersioningBundle\VCS\VCSHandlerInterface;

class MyVCSHandler implements VCSHandlerInterface
{
    public function commit(StyleInterface $io, Version $version): void
    {
        // commit the file
    }

    public function tag(StyleInterface $io, Version $version): void
    {
        // create a tag
    }
}

Use the FQCN of the service in the configuration:

bizkit_versioning:
    vcs:
        handler: App\MyVCSHandler

If you are not using Symfony's autoconfigure feature or want to use an alias, tag the service with the bizkit_versioning.vcs_handler tag:

App\MyVCSHandler:
    tags:
        - { name: 'bizkit_versioning.vcs_handler', alias: 'my_vcs' }

bizkit_versioning:
    vcs:
        handler: my_vcs

Versioning

This project follows Semantic Versioning 2.0.0.

Reporting Issues

Use the issue tracker to report any issues you encounter.

License

See the LICENSE file for details (MIT).

bizkit / versioning-bundle

Maintainers

Details