Upgrade Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the package via Composer:

   composer require filament/upgrade
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Filament\Upgrade\UpgradeServiceProvider"
   

2. First Use Case Run the upgrade command to analyze your Filament v4 codebase:

   php artisan filament:upgrade:analyze
   

   This generates a report (storage/logs/filament-upgrade-report.log) identifying deprecated or incompatible code.

3. Where to Look First

   • Check the generated report for high-priority issues (e.g., widget classes, form components, or policy changes).
   • Review the Filament v5 Migration Guide for manual adjustments not auto-detected.
   • Focus on:
     • Widgets (e.g., Widget, Card, Table → filament/widgets/ namespace).
     • Forms/Tables (e.g., Form, Table → filament/forms/ and filament/tables/).
     • Policies (e.g., Authorizable → filament/actions/).

Implementation Patterns

Usage Patterns

1. Analyze Before Upgrading Use filament:upgrade:analyze to scan your codebase for:

   • Deprecated classes/methods (e.g., Filament\Tables\Columns\TextColumn → Filament\Tables\Columns\TextColumn with updated traits).
   • Configuration changes (e.g., config/filament.php → v5 structure).
   • Plugin/extension compatibility.

2. Incremental Upgrades

   • Start with non-critical panels (e.g., admin dashboards) to test changes.
   • Use --dry-run flag to preview changes without modifying files:

     php artisan filament:upgrade:fix --dry-run
     

3. Automated Fixes Run the fixer to apply common upgrades:

   php artisan filament:upgrade:fix
   

   • Focuses on:
     • Namespace updates (e.g., Filament\Widgets\StatsOverviewWidget → App\Filament\Widgets\StatsOverviewWidget).
     • Method signatures (e.g., getTable() → getTableDefinition()).
     • Blade template paths (e.g., resources/views/filament/ → updated includes).

4. Manual Overrides For complex cases (e.g., custom widgets), manually:

   • Extend base classes (e.g., filament/forms/Components/TextInput).
   • Update Blade templates to use v5’s new directives (e.g., @form, @table).
   • Replace filament:table with filament:resource for resources.

5. Testing Workflow

   • Use php artisan filament:upgrade:test to validate fixes (if supported in future versions).
   • Test in a staging environment first due to potential breaking changes.

Integration Tips

• Laravel Version: Ensure your project meets Filament v5’s Laravel requirements (e.g., Laravel 9+).
• Dependencies: Update related packages (e.g., spatie/laravel-permission, livewire/livewire).
• CI/CD: Add upgrade checks to your pipeline:

  # Example GitHub Actions step
  - run: composer require filament/upgrade && php artisan filament:upgrade:analyze
  

• Database: Run migrations after upgrading to handle schema changes (e.g., filament/tables column updates).

Gotchas and Tips

Pitfalls

1. False Positives/Negatives

   • The analyzer may miss custom logic (e.g., dynamic widget registration).
   • Tip: Cross-reference with php artisan optimize:clear to refresh cached routes.

2. Namespace Collisions

   • If you renamed namespaces manually, the fixer may overwrite changes.
   • Tip: Backup files before running filament:upgrade:fix.

3. Blade Template Breaks

   • Old directives (e.g., @filamentTable) won’t work in v5.
   • Tip: Use php artisan filament:upgrade:fix --blade to update templates.

4. Policy/Authorization Changes

   • authorize() in v4 may not map 1:1 to v5’s canAccess().
   • Tip: Audit app/Policies/ for Filament-specific logic.

5. Plugin Incompatibility

   • Third-party Filament v4 plugins may not support v5.
   • Tip: Check the Filament Ecosystem for v5-compatible alternatives.

Debugging

• Log Files: Check storage/logs/filament-upgrade-*.log for errors.
• Verbose Mode: Run with -v for detailed output:

  php artisan filament:upgrade:fix -v
  

• Rollback: Commit changes before upgrading to revert if needed.

Config Quirks

• filament.php: V5 introduces new keys (e.g., panels, resources).

  // v4
  'widgets' => [...],
  
  // v5
  'panels' => [
      'default' => [
          'widgets' => [...],
      ],
  ],
  

• Service Providers: Register panels/resources in AppServiceProvider:

  public function boot(): void
  {
      Filament::registerPanel(
          Panel::make()
              ->id('admin')
              ->path('admin')
              ->login()
      );
  }
  

Extension Points

1. Custom Fixers Extend the upgrade logic by creating a custom fixer:

   // app/Providers/FilamentUpgradeServiceProvider.php
   public function boot(): void
   {
       Upgrade::extend(function (Upgrade $upgrade) {
           $upgrade->addFixer(new class {
               public function fix(string $file): void
               {
                   // Custom logic here
               }
           });
       });
   }
   

2. Pre/Post-Upgrade Hooks Use Laravel’s booted event to run logic after upgrades:

   public function booted(): void
   {
       if (app()->environment('production')) {
           // Post-upgrade checks
       }
   }
   

3. Community Patches Contribute fixes to the Filament Upgrade GitHub for shared improvements.