1weiho/laravel-upgrade-skill

Overview

This skill upgrades Laravel applications one major version at a time (9→10, 10→11, 11→12). It auto-detects the current Laravel version from composer.json, reads the appropriate upgrade reference, and applies targeted code and dependency fixes to complete the major-version bump.

How this skill works

The skill reads composer.json to detect the laravel/framework constraint and determines the next major target. It loads a version-specific reference file containing breaking changes and scan patterns. For each listed change it locates affected files, applies automated code fixes where safe, and updates composer.json dependencies. Finally it runs post-upgrade checks such as boot verification and test execution suggestions.

When to use it

• When you need to upgrade Laravel one major release at a time (9→10, 10→11, 11→12).
• Before performing a major upgrade to identify and apply breaking-change fixes automatically.
• When you want dependency and PHP requirement updates applied consistently with the upgrade guide.
• When you need a quick scan for common upgrade patterns and automatic fixes to migration, model, and config code.
• When preparing a codebase for CI test runs after a major framework bump.

Best practices

• Commit or snapshot the repository before running the upgrade to enable easy rollback.
• Run the skill one major version at a time, following the detected current → next target flow.
• Run the full test suite and manual smoke tests after the upgrade to catch runtime issues.
• Review automated fixes, especially for migrations and UUID behavior, before deploying to production.
• Update PHP and related package constraints in composer.json to match the new Laravel requirements.

Example use cases

• Upgrade an app from Laravel 10.x to 11.x: detect ^10.0 in composer.json, apply migration modifier fixes, update composer constraints.
• Migrate model date handling from $dates to $casts when moving 9.x to 10.x.
• Fix deprecated method calls and configuration changes when preparing an app for Laravel 12.
• Adjust HasUuids usage for projects that require UUIDv4 when upgrading 11→12.
• Automate bulk dependency updates and run composer update after code fixes.