Laravel 10 Upgrade Guide: How to Migrate from Laravel 5.5 and Older Versions

The official Laravel 10 upgrade guide is located at laravel.com/docs/10.x/upgrade, and migration requires updating your composer.json to "laravel/framework": "^10.0", reconciling breaking changes in configuration files like config/hashing.php, and clearing cached configs with php artisan config:cache.

Upgrading from legacy versions like Laravel 5.5 to Laravel 10 involves navigating significant architectural changes across the framework's core components. This guide leverages the actual source code from the laravel/framework repository to provide a definitive migration path, covering everything from Composer dependency resolution to foundation class modifications.

Where to Find the Official Laravel 10 Upgrade Guide

The most authoritative source for migration steps is the official Laravel documentation. The Laravel 10 upgrade guide at laravel.com/docs/10.x/upgrade provides the canonical reference for breaking changes, deprecated features, and mandatory configuration updates when migrating from Laravel 5.5, 6.x, 7.x, 8.x, or 9.x.

According to the laravel/framework source code, major version upgrades introduce changes to the foundation classes that bootstrap the application. These modifications are documented in the official guide and reflected in files like src/Illuminate/Foundation/Application.php, which handles service provider registration and the request lifecycle.

Key Architectural Changes in Laravel 10

Composer Dependency Updates

The upgrade process begins in your project's composer.json file. You must update the framework constraint to pull in the new version:

{
    "require": {
        "php": "^8.1",
        "laravel/framework": "^10.0"
    }
}

Running composer update resolves the new dependency graph, pulling in the latest service container, routing engine, and middleware implementations from the laravel/framework repository.

Configuration File Migrations

Laravel 10 introduces new configuration options and modifies defaults in core config files. After updating Composer dependencies, you must reconcile changes in files like config/hashing.php.

The framework source at config/hashing.php demonstrates new options for graceful hash upgrades:

return [
    'driver' => 'bcrypt',
    
    'bcrypt' => [
        'rounds' => env('BCRYPT_ROUNDS', 12),
        'verify' => true, // Allows automatic re-hashing when algorithm changes
    ],
    
    'argon2id' => [
        'memory' => 65536,
        'threads' => 1,
        'time' => 4,
    ],
];

Run php artisan config:cache to ensure your application uses the refreshed configuration values and clears any legacy cached settings.

Foundation Class Modifications

The core Application class in src/Illuminate/Foundation/Application.php orchestrates the service container, bootstrapping, and request handling. Upgrades often modify how service providers are registered or how the kernel resolves routes.

Additionally, deprecation handling changes are visible in files like src/Illuminate/Database/LostConnectionDetector.php, where @deprecated annotations indicate APIs removed or modified in newer versions.

Step-by-Step Laravel 10 Migration Workflow

Follow this structured workflow to migrate from Laravel 5.5 to Laravel 10:

1. Review the official upgrade guide – Consult laravel.com/docs/10.x/upgrade to identify breaking changes specific to your current version.

2. Create a backup – Commit your current state: git commit -am "pre-upgrade backup".

3. Update PHP version – Ensure your server runs PHP 8.1 or higher, as required by Laravel 10.

4. Update Composer dependencies – Modify composer.json to require "laravel/framework": "^10.0" and run composer update.

5. Publish and merge config files – Run php artisan vendor:publish --tag=laravel-config if needed, then manually merge changes into existing config files.

6. Clear cached configurations – Execute php artisan config:clear && php artisan config:cache.

7. Update service providers – Adjust any custom provider registrations in config/app.php to match new class signatures.

8. Run the test suite – Execute php artisan test to verify application logic remains intact.

9. Deploy to production – Push changes and run php artisan migrate --force if database migrations are required.

Summary

• The definitive Laravel 10 upgrade guide resides at laravel.com/docs/10.x/upgrade and provides version-specific breaking changes.
• Migration requires updating composer.json to "laravel/framework": "^10.0" and resolving new dependencies.
• Configuration files like config/hashing.php introduce new options that require manual merging and caching via php artisan config:cache.
• Core foundation classes in src/Illuminate/Foundation/Application.php may modify service provider registration behavior.
• Always validate your migration by running php artisan test before deploying to production.

Frequently Asked Questions

Can I upgrade directly from Laravel 5.5 to Laravel 10?

No, you should upgrade incrementally through intermediate versions. Laravel does not support direct jumps across multiple major versions. Migrate from 5.5 to 6.x, then to 7.x, 8.x, 9.x, and finally to 10.x, following the specific upgrade guide for each version to address breaking changes sequentially.

What PHP version is required for Laravel 10?

Laravel 10 requires PHP 8.1 or higher. This is a significant bump from Laravel 5.5, which supported PHP 7.0. You must upgrade your server environment before updating Composer dependencies, or the installation will fail with version constraint errors.

Why do I need to clear the config cache after upgrading?

Laravel caches configuration values in serialized files to improve performance. After upgrading, old cached configs may contain deprecated keys or missing new required options introduced in Laravel 10. Running php artisan config:clear removes stale caches, and php artisan config:cache regenerates them with the updated schema from files like config/hashing.php.

Where are breaking changes documented in the source code?

Breaking changes and deprecations are annotated directly in the framework source. Look for @deprecated tags in files like src/Illuminate/Database/LostConnectionDetector.php and review src/Illuminate/Foundation/Application.php for changes to provider registration and container binding logic. The official documentation at laravel.com/docs/10.x/upgrade aggregates these changes into actionable migration steps.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}