Upgrader Laravel Package

Getting Started

1. Install: composer require shalvah/upgrader
2. Publish config: php artisan vendor:publish --provider="Shalvah\Upgrader\UpgraderServiceProvider" (creates config/upgrader.php)
3. Create your first upgrade: Run php artisan make:upgrade AddUserPreferences — this generates a class in app/Upgrades/
4. Implement logic: Edit the up() method in the generated class to apply changes (e.g., populate a new column, seed config, cleanup stale data)
5. Run upgrades: php artisan upgrader:run — executes pending upgrades in version order

🔍 First use case: Migrating legacy data after adding a new required column — where Eloquent model validation/migrations alone can’t safely handle mass updates.

Implementation Patterns

• Version naming: Use semantic versions (e.g., 2024_03_15_120000_add_user_timezone) — lexicographic ordering ensures correct sequence
• Group logically: Bundle related changes (e.g., 2024_02_01_000000_migrate_old_settings_to_json.php + 2024_02_01_000001_populate_default_timezone.php)
• Complement migrations: Use migrations for schema; upgrader for data transitions (e.g., splitting a name column into first_name/last_name)
• Idempotent by design: Structure up() as a single atomic operation or a series of safe conditionals (if (!Schema::hasColumn('users', 'timezone')) { ... })
• Integrate into deploy: Add php artisan upgrader:run to your deployment script after migrations but before app restarts/caches clear
• Dry-run support: Temporarily override config('upgrader.dry_run', true) to preview which classes would run

Gotchas and Tips

• ⚠️ Revert responsibility: The package does not provide down() or rollback — plan ahead and log enough info to manually revert if needed
• 🐞 Silent failures: If up() throws an exception mid-execution, the upgrade is not marked as completed (safe), but you’ll need to inspect logs — ensure your up() is wrapped in try/catch for non-critical steps
• 🧱 Ordering dependency: Upgrades run in filename order — avoid ambiguous timestamps (e.g., 2024_03_01_999999 before 2024_03_02_000000)
• 🧪 Test upgrades locally: Create a sandbox DB, apply upgrader:run twice — verify no side effects on re-run
• 📊 Track progress: Call Upgrader::getCompleted() in your up() logic to conditionally handle edge cases
• 🧩 Extend safely: You can add helper traits/methods to your upgrade classes, but avoid DB connections not managed by Laravel (use injected DB facade or Eloquent)
• 🔒 Locking: The package uses Laravel’s cache for locking — ensure cache driver supports atomic operations (e.g., Redis, database), not file in clustered environments