Symfony Version Enforcer Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dontdrinkandroot/symfony-version-enforcer
   

   Register the service provider in config/app.php under providers:

   DontDrinkAndRoot\SymfonyVersionEnforcer\SymfonyVersionEnforcerServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="DontDrinkAndRoot\SymfonyVersionEnforcer\SymfonyVersionEnforcerServiceProvider" --tag="config"
   

   Edit config/symfony-version-enforcer.php to define your enforced Symfony version (e.g., "^6.4").

3. First Use Case Run the enforcer to validate your project’s Symfony dependencies:

   php artisan symfony:enforce
   

   This checks composer.json and updates symfony/* packages to match the enforced version.

Implementation Patterns

Workflows

1. Enforcement in CI/CD Integrate the enforcer into your pipeline (e.g., GitHub Actions) to block PRs with incompatible Symfony versions:

   - name: Enforce Symfony Version
     run: php artisan symfony:enforce --fail
   

2. Custom Validation Extend the enforcer for project-specific rules (e.g., blocking Symfony 7.x):

   // app/Providers/SymfonyEnforcerServiceProvider.php
   use DontDrinkAndRoot\SymfonyVersionEnforcer\Enforcer;
   
   public function boot(Enforcer $enforcer)
   {
       $enforcer->addRule(function ($version) {
           return version_compare($version, '7.0.0', '<') || true;
       }, 'Block Symfony 7.x');
   }
   

3. Dynamic Versioning Use environment variables to override the enforced version (e.g., for local dev):

   // config/symfony-version-enforcer.php
   'version' => env('SYMFONY_VERSION', '^6.4'),
   

Integration Tips

• Composer Scripts: Hook the enforcer into composer install/update:

  {
    "scripts": {
      "post-install-cmd": [
        "Illuminate\\Foundation\\ComposerScripts::postInstall",
        "@symfony:enforce"
      ]
    }
  }
  

• Laravel Mix: Add a custom webpack rule to fail builds with mismatched versions:

  // webpack.mix.js
  mix.webpackConfig({
    plugins: [
      new webpack.EnvironmentPlugin({
        SYMFONY_VERSION: process.env.SYMFONY_VERSION || '^6.4',
      }),
    ],
  });
  

Gotchas and Tips

Pitfalls

1. False Positives The enforcer may flag symfony/* dev dependencies (e.g., symfony/var-dumper in tests). Exclude them in config:

   'ignore' => [
       'symfony/var-dumper',
       'symfony/debug-bundle',
   ],
   

2. Lockfile Conflicts Running composer update after enforcement may cause lockfile conflicts. Use --no-update first:

   php artisan symfony:enforce --no-update
   composer update
   

3. Circular Dependencies If your project depends on a package that enforces a different Symfony version, conflicts may arise. Use --force sparingly:

   php artisan symfony:enforce --force
   

Debugging

• Dry Run: Test changes without modifying composer.json:

  php artisan symfony:enforce --dry-run
  

• Verbose Output: Enable debug mode for detailed logs:

  php artisan symfony:enforce --verbose
  

Extension Points

1. Custom Enforcers Create a trait to reuse enforcement logic across projects:

   // app/Traits/EnforceSymfony.php
   use DontDrinkAndRoot\SymfonyVersionEnforcer\Enforcer;
   
   trait EnforceSymfony
   {
       protected function enforceSymfony(Enforcer $enforcer)
       {
           $enforcer->setVersion('^6.4');
           $enforcer->enforce();
       }
   }
   

2. Event Listeners Listen for enforcement events to trigger side effects (e.g., notifications):

   // app/Listeners/SymfonyVersionEnforced.php
   use DontDrinkAndRoot\SymfonyVersionEnforcer\Events\VersionEnforced;
   
   public function handle(VersionEnforced $event)
   {
       Log::info("Symfony version enforced to {$event->version}");
   }
   

3. API Integration Expose enforcement status via an API route:

   // routes/api.php
   Route::get('/symfony/status', function () {
       return response()->json([
           'enforced' => app(DontDrinkAndRoot\SymfonyVersionEnforcer\Enforcer::class)->isEnforced(),
       ]);
   });