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

> Follow this comprehensive Laravel 10 upgrade guide to smoothly migrate from older versions like Laravel 5.5. Learn essential steps for updated dependencies and breaking changes.

- Repository: [Laravel/framework](https://github.com/laravel/framework)
- Tags: migration-guide
- Published: 2026-02-16

---

**The official Laravel 10 upgrade guide is located at `laravel.com/docs/10.x/upgrade`, and migration requires updating your [`composer.json`](https://github.com/laravel/framework/blob/main/composer.json) to `"laravel/framework": "^10.0"`, reconciling breaking changes in configuration files like [`config/hashing.php`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/composer.json) file. You must update the framework constraint to pull in the new version:

```json
{
    "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`](https://github.com/laravel/framework/blob/main/config/hashing.php).

The framework source at [`config/hashing.php`](https://github.com/laravel/framework/blob/main/config/hashing.php) demonstrates new options for graceful hash upgrades:

```php
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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/composer.json) to `"laravel/framework": "^10.0"` and resolving new dependencies.
- Configuration files like [`config/hashing.php`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/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`](https://github.com/laravel/framework/blob/main/src/Illuminate/Database/LostConnectionDetector.php) and review [`src/Illuminate/Foundation/Application.php`](https://github.com/laravel/framework/blob/main/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.