Version Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require corley/version-bundle
   

   Register the bundle in app/AppKernel.php:

   $bundles[] = new Corley\VersionBundle\CorleyVersionBundle();
   

2. First Use Case:

   • Initialize the version file (creates config/version.yml):

     app/console corley:version:init 0.0.1
     

   • Bump the version (e.g., patch increment):

     app/console corley:version:bump 0.0.1
     

   • Verify the version:

     app/console corley:version:show
     

3. Expose Version in Twig: Add to config/config.yml:

   imports:
       - { resource: version.yml }
   twig:
       globals:
           version: %version%
   

Implementation Patterns

Version Management Workflow

1. Version Bumping:

   • Use corley:version:bump with semantic versioning (e.g., 0.0.1 for patch, 0.1.0 for minor, 1.0.0 for major).
   • Example: Increment patch version:

     app/console corley:version:bump 0.0.1
     

2. Version in Templates: Access the version globally in Twig:

   <footer>
       App Version: {{ version.number }}
       Build: {{ version.build }}  <!-- Optional build metadata -->
   </footer>
   

3. Static Asset Versioning: Append version to cache-bust static files (CSS/JS):

   {% javascripts
       ['/js/app.js', '/js/vendor.js']
       {'filter': 'js_version_filter'}
   %}
   

   Define the filter in a Twig extension (see Gotchas).

4. CI/CD Integration:

   • Automate version bumps in deployment pipelines (e.g., GitHub Actions):

     - name: Bump version
       run: php bin/console corley:version:bump $NEW_VERSION
     

Integration Tips

• Environment-Specific Versions: Override version.yml per environment (e.g., config/version_dev.yml) using Symfony’s parameter system.
• Version in API Responses: Expose version via a controller:

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

• Database Version Tracking: Store the version in a versions table and sync with version.yml via a post-install command.

Gotchas and Tips

Pitfalls

1. File Permissions: Ensure config/version.yml is writable by the web server user. Run:

   chmod 644 config/version.yml
   

2. Twig Global Overrides: If version global isn’t working, clear the cache:

   php bin/console cache:clear
   

3. Static Asset Filtering: The bundle doesn’t provide a built-in Twig filter for versioning assets. Create a custom filter:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig_Extension
   {
       public function getFilters()
       {
           return [
               new \Twig_SimpleFilter('version', function ($path) {
                   return $path . '?v=' . $this->container->getParameter('version.number');
               }),
           ];
       }
   }
   

   Register the extension in services.yml:

   services:
       app.twig.extension:
           class: App\Twig\AppExtension
           arguments: ['@service_container']
           tags: ['twig.extension']
   

4. Version Format Validation: The bundle doesn’t validate version strings (e.g., 1.2 or abc). Stick to semantic versioning (e.g., 1.2.3).

Debugging

• Check version.yml: Verify the file exists and contains expected data:

  # config/version.yml
  number: 1.0.0
  build: 202305151200
  

• Command Output: Use --verbose for debug info:

  app/console corley:version:bump 1.0.0 --verbose
  

Extension Points

1. Custom Version Sources: Extend the bundle to read versions from other sources (e.g., Git tags, database) by overriding the VersionManager service.
2. Post-Bump Actions: Hook into version bumps via Symfony’s event system (e.g., trigger migrations or notifications).
3. Multi-Project Versions: For monorepos, manage versions per project by extending the bundle’s Version class to include a project field.