Laravel 10 → 12 업그레이드 완전 가이드

1. 버전별 핵심 변경사항

Laravel은 2023년부터 연간 Major 릴리스 체계로 전환했습니다. 각 버전의 LTS 지원 기간과 PHP 요구사항을 먼저 파악하는 것이 업그레이드 계획의 출발점입니다.

2. Laravel 10 → 11 업그레이드

2-1. PHP & Composer 요구사항 확인

Laravel 11은 PHP 8.2 이상을 필수로 요구합니다. 로컬 환경과 서버 PHP 버전을 먼저 확인합니다.

php --version            # 8.2+ 확인
composer --version       # 2.6+ 권장

# composer.json 변경
"require": {
    "php": "^8.2",
    "laravel/framework": "^11.0"
}

2-2. AppServiceProvider 재구성

Laravel 11부터 App\Providers\RouteServiceProvider가 제거되고 라우팅 설정이 bootstrap/app.php로 이동합니다.

// bootstrap/app.php (Laravel 11+)
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'admin.auth' => \App\Http\Middleware\AdminAuth::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

2-3. Middleware 변경

기존 app/Http/Kernel.php가 삭제됩니다. 미들웨어는 bootstrap/app.php의 withMiddleware()에서 관리합니다. 커스텀 글로벌 미들웨어는 $middleware->append()로 추가합니다.

3. Laravel 11 → 12 업그레이드

3-1. 스타터킷 변경

Laravel 12는 Breeze/Jetstream 대신 React + Inertia 또는 Vue + Inertia 기반 Starter Kit을 기본 옵션으로 제공합니다. 기존 Breeze를 사용한다면 별도 마이그레이션이 필요합니다.

# Laravel 12 새 프로젝트 생성 시 스타터킷 선택
composer create-project laravel/laravel myapp
cd myapp
php artisan install:api       # API 라우트 설치
php artisan install:broadcasting  # WebSocket 브로드캐스팅 설치

3-2. 주요 Deprecation 정리

• Model::$dates 프로퍼티 제거 → casts 배열로 대체
• assertDatabaseMissing() 시그니처 변경
• Flysystem 3.x 기본 → S3/로컬 드라이버 설정 방식 변경

4. Webpack Mix → Vite 전환

Laravel 10에서 Vite가 기본 번들러로 전환되었습니다. Mix를 사용하는 프로젝트는 Vite로 마이그레이션이 필요합니다.

# 1. 패키지 교체
npm remove laravel-mix
npm install --save-dev vite laravel-vite-plugin

# 2. vite.config.js 생성
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/scss/app.scss', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
});

# 3. Blade 레이아웃 변경
{{-- 기존 Mix --}}
<link rel="stylesheet" href="{{ mix('css/app.css') }}">

{{-- Vite --}}
@vite(['resources/scss/app.scss', 'resources/js/app.js'])

5. 업그레이드 체크리스트