Versioning Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require shivas/versioning-bundle
   

   Add to config/bundles.php:

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

2. Configure Edit config/packages/versioning.yaml (auto-generated):

   shivas_versioning:
       handler: git  # or 'manual'/'initial'
       version: '0.1.0'  # fallback if handler fails
   

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

   use Shivas\VersioningBundle\Versioning\VersionManager;
   
   class AppController extends AbstractController {
       public function index(VersionManager $versionManager) {
           $version = $versionManager->getVersion();
           return $this->render('index.html.twig', ['version' => $version]);
       }
   }
   

   Display in Twig:

   <div>App Version: {{ version }}</div>
   

Implementation Patterns

Core Workflows

1. Git-Based Versioning (Recommended)

   • Auto-detects version from Git tags (e.g., v1.2.3).
   • Configure in versioning.yaml:

     shivas_versioning:
         handler: git
     

   • Trigger: Run git tag -a vX.Y.Z -m "Release" before deployment.

2. Manual Version Bumping

   • Use CLI to increment versions:

     php bin/console app:version:bump [major|minor|patch]
     

   • Example: php bin/console app:version:bump minor → 0.2.0.

3. Fallback to Initial Version

   • If Git tags are missing, defaults to 0.1.0 (configurable).

Integration Tips

• Deployment Hooks Integrate with Capifony or Deployer:

  # In deploy.php
  $deploy->run("php bin/console app:version:bump patch");
  

• API Versioning Use the version in API responses:

  return $this->json(['data' => $data, 'version' => $versionManager->getVersion()]);
  

• Environment-Specific Versions Override version in versioning.yaml per environment:

  # config/packages/dev/versioning.yaml
  shivas_versioning:
      version: 'dev-{{ date('YmdHis') }}'
  

Gotchas and Tips

Common Pitfalls

1. Git Tag Format

   • Ensure tags follow vX.Y.Z (e.g., v1.0.0). The bundle strips the v prefix.
   • Fix: Use git tag -a v1.0.0 instead of 1.0.0.

2. Caching Issues

   • The version is loaded once at bootstrap. Clear cache after manual bumps:

     php bin/console cache:clear
     

3. Handler Priority

   • If handler: git fails (e.g., no tags), it falls back to the version config. Test with:

     php bin/console debug:config shivas_versioning
     

Debugging

• Check Current Version

  php bin/console debug:config shivas_versioning
  

• Validate Git Tags

  git tag -l 'v*'  # List all version tags
  

Extension Points

1. Custom Handlers Create a new handler (e.g., for SVN or custom logic):

   // src/Handler/CustomHandler.php
   namespace App\Handler;
   
   use Shivas\VersioningBundle\Versioning\HandlerInterface;
   
   class CustomHandler implements HandlerInterface {
       public function getVersion(): string {
           return file_get_contents('/path/to/version.txt');
       }
   }
   

   Register in versioning.yaml:

   shivas_versioning:
       handler: custom
   

   Bind the service in services.yaml:

   Shivas\VersioningBundle\Versioning\HandlerInterface: '@App\Handler\CustomHandler'
   

2. Override Version Parameter Dynamically set the version in a service:

   // src/EventListener/VersionListener.php
   namespace App\EventListener;
   
   use Shivas\VersioningBundle\Versioning\VersionManager;
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   class VersionListener {
       public function onKernelRequest(RequestEvent $event, VersionManager $versionManager) {
           if ($event->isMainRequest()) {
               $versionManager->setVersion('1.2.3-custom'); // Override
           }
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\VersionListener:
           tags:
               - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }