Upgrade Helper Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to your composer.json:

   composer require chameleon-system/upgrade-helper
   

   Enable the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   return [
       // ...
       ChameleonSystem\UpgradeHelperBundle\ChameleonSystemUpgradeHelperBundle::class => ['all' => true],
   ];
   

2. First Run Execute the command with your Laravel project's root directory (adjust path as needed):

   php artisan ch:upgr /path/to/your/laravel/project/app
   

   (Note: Laravel users may need to alias the Symfony command via artisan or create a custom artisan command wrapper.)

3. Expected Output The tool scans for:

   • Implicit calls (e.g., $container->get($serviceVar) where $serviceVar is dynamic).
   • Non-public service access (e.g., $container->get('non.public.service')).

First Use Case: Pre-Upgrade Audit

Before upgrading to Chameleon System 7.1, run the helper to identify:

• Deprecated service access patterns (e.g., ServiceLocator usage).
• Non-public services that need to be made public or refactored.
• False positives (manual review required for implicit calls).

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add the command to your pre-upgrade checks (e.g., GitHub Actions):

   - name: Run Upgrade Helper
     run: php artisan ch:upgr app
   

   Fail the build if warnings are found (customize exit codes if needed).

2. Local Development Run during feature branches or before major upgrades:

   php artisan ch:upgr app --format=json > upgrade_report.json
   

   (Use --format=json for programmatic parsing.)

3. Service Locator Replacement If using ServiceLocator, the helper flags non-public services. Refactor to:

   // Before (flagged)
   $service = $locator->get('non.public.service');
   
   // After (public service or DI)
   $service = app()->make(PublicService::class);
   

Laravel-Specific Patterns

1. Service Container Access Laravel’s app() helper or Illuminate\Container\Container is scanned. Example:

   // Flagged: Non-public service
   $userRepo = app('user.repository');
   
   // Fixed: Use binding or public service
   $userRepo = app()->make(UserRepository::class);
   

2. Dynamic Service Names Implicit calls (e.g., $container->get($dynamicKey)) require manual review. Mitigate by:

   • Using type-hinted dependencies in constructors.
   • Creating public facade methods for dynamic services.

3. Custom Artisan Command (Optional) Extend the bundle’s command for Laravel:

   // app/Console/Commands/UpgradeHelper.php
   namespace App\Console\Commands;
   use Symfony\Component\Console\Application;
   class UpgradeHelper extends Command {
       protected $signature = 'upgrade:helper {path}';
       public function handle() {
           $symfonyApp = new Application();
           $symfonyApp->add(new \ChameleonSystem\UpgradeHelperBundle\Command\UpgradeHelperCommand());
           $symfonyApp->run();
       }
   }
   

Gotchas and Tips

Pitfalls

1. False Positives

   • Implicit calls (e.g., $container->get($var)) may not be actionable. Verify manually.
   • Dynamic service names (e.g., config-driven) cannot be statically analyzed.

2. Laravel-Specific Quirks

   • The bundle targets Symfony, so Laravel’s app() helper may not map 1:1 to Symfony’s ContainerInterface.
   • Service providers are not scanned by default. Focus on controllers/services using $container directly.

3. Exit Codes The command exits with 0 (success) even if warnings exist. Override in Laravel:

   // In your custom command
   if ($this->hasErrors()) {
       return 1; // Fail build
   }
   

Debugging Tips

1. Verbose Output Use -v or -vv for detailed paths:

   php artisan ch:upgr app -vv
   

2. JSON Output Parse warnings programmatically:

   php artisan ch:upgr app --format=json | jq '.warnings[] | select(.type == "non_public")'
   

3. Exclude Directories Ignore tests or third-party code:

   php artisan ch:upgr app --exclude="tests,vendor"
   

Extension Points

1. Custom Service Whitelisting Extend the bundle to ignore known-safe services (e.g., config('services.allowed')).

2. Post-Processing Scripts Use the JSON output to auto-fix simple cases (e.g., replace app('service') with app()->make(Service::class)).

3. Symfony Event Listeners Hook into kernel.terminate to log warnings to a database or Slack.

Note: The package is Symfony-focused but can be adapted for Laravel with minor wrappers. Prioritize manual review for implicit calls.