Vdm Version Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require 3slab/vdm-version-bundle
   

2. Enable Routing: Add to config/routes.yaml (or routing.yml in older Laravel versions):

   vdm_version:
     resource: "@VdmVersionBundle/Resources/config/routing.yml"
     prefix: /
   

3. Basic Configuration: Create config/packages/vdm_version.yaml (or add to config/vdm_version.php in Laravel):

   vdm_version:
     path: /version
     versions:
       app: '1.0.0'
       api: 'v2.3'
   

4. First Use Case: Access /version to get a JSON response:

   {"app":"1.0.0","api":"v2.3"}
   

Implementation Patterns

Version Management Workflows

1. Dynamic Version Fetching: Override the default versions by injecting a custom service:

   // src/Service/VersionProvider.php
   class VersionProvider implements VersionProviderInterface
   {
       public function getVersions(): array
       {
           return [
               'app' => $this->getAppVersion(),
               'database' => $this->getDbSchemaVersion(),
           ];
       }
   }
   

   Register it in config/packages/vdm_version.yaml:

   vdm_version:
     version_provider: App\Service\VersionProvider
   

2. Secret-Protected Endpoint: Enable secrets for detailed responses:

   vdm_version:
     secret: 'my_secure_secret'
   

   Query with:

   GET /version?secret=my_secure_secret
   

   Or via header:

   GET /version
   Headers: VDM-Version-Secret: my_secure_secret
   

3. Integration with CI/CD: Use the endpoint in deployment scripts to verify version consistency:

   VERSION_RESPONSE=$(curl -s http://localhost/version)
   if [[ "$VERSION_RESPONSE" != *"app:1.0.0"* ]]; then
       echo "Version mismatch!"
       exit 1
   fi
   

4. Custom Response Formatting: Extend the controller to modify output:

   // src/Controller/VersionController.php
   class VersionController extends AbstractVersionController
   {
       public function getVersionAction(): Response
       {
           $versions = $this->getVersions();
           return new Response(json_encode([
               'status' => 'success',
               'data' => $versions,
               'timestamp' => now()->toIso8601String(),
           ]));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Routing Conflicts: Ensure /version doesn’t clash with existing routes. Use a custom path if needed:

   vdm_version:
     path: /api/version
   

2. Secret Handling:

   • If secret is set but not provided, the endpoint returns an empty object {}.
   • Avoid hardcoding secrets in config. Use environment variables:

     vdm_version:
       secret: '%env(VDM_VERSION_SECRET)%'
     

3. Version Provider Overrides:

   • If both versions config and a custom version_provider are set, the provider takes precedence.
   • Clear the cache after changing the provider:

     php artisan cache:clear
     

Debugging

• Empty Response? Check if the version_provider service is correctly bound in the container. Run:

  php artisan debug:container | grep VersionProvider
  

• 404 on /version? Verify the bundle’s routing file is loaded. Check config/routes.yaml for the vdm_version resource.

Extension Points

1. Add Metadata: Extend the response with build info or Git hash:

   // In VersionProvider
   public function getVersions(): array
   {
       return [
           'app' => '1.0.0',
           'build' => file_get_contents('/build/version.txt'),
       ];
   }
   

2. Rate Limiting: Protect the /version endpoint with Laravel’s middleware:

   # config/packages/vdm_version.yaml
   vdm_version:
     middleware: ['throttle:60,1']
   

3. Caching: Cache the version response for performance (e.g., 1 hour):

   // In VersionController
   public function getVersionAction(): Response
   {
       return Response::cache(3600)->json($this->getVersions());
   }
   

Config Quirks

• Boolean Values: The secret parameter must be explicitly set to null to disable it:

  vdm_version:
    secret: null  # Disables secret protection
  

  Omitting it entirely defaults to null.

• Array Syntax: Use YAML block style for multi-line versions:

  vdm_version:
    versions:
      services:
        - name: frontend
          version: 1.0
        - name: backend
          version: 1.1