Versioning Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require demroos/versioning-bundle
   

   Ensure Demroos\VersioningBundle\DemroosVersioningBundle::class is added to config/bundles.php.

2. Configuration Override default settings in config/packages/demroos_versioning.yaml:

   demroos_versioning:
       provider: git_repository  # or 'version_file', 'revision_file', 'initial'
       version_file_path: '%kernel.project_dir%/VERSION'  # if using version_file
       default_version: '1.0.0'  # fallback if no provider matches
   

3. First Use Case Access the version in Twig:

   <p>App Version: {{ app.version }}</p>
   

   Or in PHP:

   $version = $this->getParameter('app.version');
   

Implementation Patterns

Core Workflows

1. Git-Based Versioning (Recommended)

   • Tag releases in Git (e.g., git tag v1.0.0).
   • Bundle auto-detects the latest tag via git describe.
   • Useful for CI/CD pipelines to auto-update versions.

2. Manual Version File

   • Create a VERSION file in project root (e.g., 1.2.3).
   • Update manually or via scripts (e.g., echo "1.2.3" > VERSION).
   • Ideal for non-Git environments or legacy systems.

3. Capistrano/Revision File

   • Deployments with Capistrano generate a REVISION file.
   • Bundle reads this file for versioning (e.g., REVISION=abc123).
   • Useful for tracking deployments without Git tags.

Integration Tips

• Twig Globals: Automatically injects app.version into all templates.
• Environment Variables: Expose version via .env:

  APP_VERSION=%app.version%
  

• API Responses: Add version to JSON responses:

  return $this->json(['version' => $this->getParameter('app.version')]);
  

• Database Migrations: Tag migrations with versions (e.g., 2023_01_01_000000_create_users_table.php → 1.0.0).

Extending Providers

1. Custom Provider: Create a service implementing Demroos\VersioningBundle\Provider\VersionProviderInterface:

   namespace App\Versioning;
   
   use Demroos\VersioningBundle\Provider\VersionProviderInterface;
   
   class CustomProvider implements VersionProviderInterface
   {
       public function getVersion(): string
       {
           return file_get_contents('/custom/path/to/version');
       }
   }
   

2. Register Provider: Add to config/packages/demroos_versioning.yaml:

   demroos_versioning:
       providers:
           custom: App\Versioning\CustomProvider
       provider: custom
   

Gotchas and Tips

Pitfalls

1. Git Provider Quirks:

   • Requires Git tags to follow SemVer (e.g., v1.0.0, not release-1).
   • If no tags exist, falls back to default_version (configurable).
   • Fix: Ensure tags are pushed to remote:

     git push --tags
     

2. File Permissions:

   • VERSION or REVISION files must be readable by the web server user.
   • Fix: Set permissions:

     chmod 644 VERSION
     

3. Caching Issues:

   • Version providers may cache results. Clear cache after manual updates:

     php bin/console cache:clear
     

4. Symfony Flex Conflicts:

   • If using Symfony Flex, ensure the bundle is enabled in config/bundles.php (not config/packages/).

Debugging

• Check Active Provider:

  php bin/console debug:config demroos_versioning
  

• Log Provider Output: Temporarily enable debug mode in config/packages/dev/demroos_versioning.yaml:

  demroos_versioning:
      debug: true
  

  Logs provider calls to var/log/dev.log.

Extension Points

1. Custom Formatters: Override the default SemVer formatter by creating a VersionFormatter service:

   services:
       app.version_formatter:
           class: App\Versioning\CustomFormatter
           tags: ['demroos_versioning.formatter']
   

2. Dynamic Version Logic: Combine multiple providers (e.g., Git tag + build number):

   // In a custom provider
   $gitVersion = $this->gitProvider->getVersion();
   $buildNumber = $this->getBuildNumberFromEnv();
   return "$gitVersion+$buildNumber";
   

3. Environment-Specific Versions: Use different providers per environment:

   # config/packages/dev/demroos_versioning.yaml
   demroos_versioning:
       provider: initial  # Use 0.1.0 in dev
   
   # config/packages/prod/demroos_versioning.yaml
   demroos_versioning:
       provider: git_repository
   

Pro Tips

• CI/CD Integration: Auto-generate tags in GitHub Actions/GitLab CI:

  # .github/workflows/release.yml
  - name: Tag Release
    run: |
      git tag -a v${{ github.ref_name }} -m "Release ${{ github.ref_name }}"
      git push origin v${{ github.ref_name }}
  

• Frontend Versioning: Use the version to bust caches:

  <script src="/js/app.{{ app.version }}.js"></script>
  

• Security: Avoid exposing raw Git hashes (e.g., REVISION) in production logs. Use hashed versions instead.