Versioning Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bizkit/versioning-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Bizkit\VersioningBundle\BizkitVersioningBundle::class => ['all' => true],
   ];
   

2. Generate Version File Run the command to initialize versioning:

   php bin/console bizkit:versioning:init
   

   This creates config/versioning.yml (default location) with:

   version: 1.0.0
   release_date: '2024-01-01'
   strategy: semantic
   

3. First Use Case Access the version in a controller:

   use Bizkit\VersioningBundle\Versioning\VersionManager;
   
   class AppController extends AbstractController {
       public function showVersion(VersionManager $versionManager) {
           return $this->json($versionManager->getVersion());
       }
   }
   

Implementation Patterns

Core Workflow

1. Version Management

   • Use VersionManager service to fetch/retrieve version data:

     $version = $versionManager->getVersion(); // Returns "1.0.0"
     $date = $versionManager->getReleaseDate(); // Returns DateTime
     

2. Version Incrementation

   • Increment versions via CLI (supports semantic, calver, or custom strategies):

     # Semantic versioning (patch increment)
     php bin/console bizkit:versioning:increment semantic
     
     # Custom strategy (e.g., "custom-strategy")
     php bin/console bizkit:versioning:increment custom-strategy
     

3. Custom Strategies

   • Extend Bizkit\VersioningBundle\Versioning\Strategy\VersionStrategyInterface:

     namespace App\Versioning;
     
     use Bizkit\VersioningBundle\Versioning\Strategy\VersionStrategyInterface;
     
     class CustomStrategy implements VersionStrategyInterface {
         public function increment(string $currentVersion): string {
             // Custom logic (e.g., "dev-2024.05.01")
             return 'dev-' . date('Y.m.d');
         }
     }
     

   • Register in config/packages/bizkit_versioning.yaml:

     bizkit_versioning:
         strategies:
             custom_strategy: App\Versioning\CustomStrategy
     

4. Version-Aware Routing/Logic

   • Use dependency injection to inject VersionManager into services/controllers:

     public function __construct(private VersionManager $versionManager) {}
     

   • Example: Conditional feature flags based on version:

     if ($this->versionManager->isVersionGreaterThan('2.0.0')) {
         $this->enableNewFeature();
     }
     

5. VCS Integration (Git)

   • Configure Git in config/packages/bizkit_versioning.yaml:

     bizkit_versioning:
         vcs:
             type: git
             repository: /path/to/repo
     

   • The increment command will auto-commit changes and tag releases (if enabled).

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • The bundle defaults to config/versioning.yml, but this can be overridden in config/packages/bizkit_versioning.yaml:

     bizkit_versioning:
         file: '%kernel.project_dir%/custom/version.yml'
     

   • Tip: Always verify the config path after installation.

2. Strategy Mismatches

   • If the configured strategy doesn’t exist, the increment command throws:

     [ErrorException] Strategy "nonexistent" not found.
     

   • Fix: Check config/packages/bizkit_versioning.yaml for typos or missing strategy definitions.

3. VCS Permissions

   • Git operations (commit/tag) require write access to the repository. If the command fails silently, check:
     • File permissions (chmod -R 755 /path/to/repo).
     • User executing the command has Git access.

4. Version File Locking

   • The bundle locks the version file during writes to prevent race conditions. If you manually edit versioning.yml, ensure the file isn’t locked by a running process.

5. Symfony Cache Invalidation

   • After changing the version, clear the Symfony cache:

     php bin/console cache:clear
     

   • Tip: Use the --no-debug flag in production to avoid cache rebuilds.

Debugging Tips

1. Dry Run Mode

   • Test version increments without committing:

     php bin/console bizkit:versioning:increment semantic --dry-run
     

2. Logging

   • Enable debug mode to log versioning operations:

     bizkit_versioning:
         debug: true
     

3. Custom VCS Handlers

   • Extend Bizkit\VersioningBundle\Vcs\VcsHandlerInterface for non-Git systems (e.g., SVN):

     class SvnHandler implements VcsHandlerInterface {
         public function commit(string $message): bool { /* ... */ }
         public function tag(string $version): bool { /* ... */ }
     }
     

   • Register in config:

     bizkit_versioning:
         vcs:
             type: svn
             handler: App\Vcs\SvnHandler
     

4. Version Validation

   • Validate versions before incrementing (e.g., reject 1.0.0-alpha for semantic):

     if (!$versionManager->isValidSemanticVersion($currentVersion)) {
         throw new \RuntimeException("Invalid version format");
     }
     

5. Environment-Specific Versions

   • Use environment variables to override versions (e.g., for staging):

     bizkit_versioning:
         version: '%env(VERSION_OVERRIDE)%'
     

   • Set in .env:

     VERSION_OVERRIDE=1.0.0-staging
     

Extension Points

1. Event Listeners

   • Listen for version changes via VersioningEvents:

     use Bizkit\VersioningBundle\Event\VersioningEvents;
     use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
     
     #[AsEventListener(event: VersioningEvents::VERSION_UPDATED)]
     public function onVersionUpdated(VersioningEvent $event) {
         // Log or trigger side effects (e.g., deploy hooks)
     }
     

2. Custom Version Storage

   • Override the default YAML storage by implementing Bizkit\VersioningBundle\Storage\VersionStorageInterface:

     class DatabaseStorage implements VersionStorageInterface {
         public function load(): array { /* ... */ }
         public function save(array $data): void { /* ... */ }
     }
     

   • Register in config:

     bizkit_versioning:
         storage: App\Storage\DatabaseStorage
     

3. API Endpoints

   • Expose version data via API:

     #[Route('/api/version', name: 'app_version', methods: ['GET'])]
     public function getVersion(VersionManager $versionManager): JsonResponse {
         return $this->json([
             'version' => $versionManager->getVersion(),
             'release_date' => $versionManager->getReleaseDate()->format('Y-m-d'),
         ]);
     }