업그레이드 가이드

번역일: 2026년 6월 20일

업그레이드 가이드

9.x에서 10.0으로 업그레이드

영향도 높은 변경 사항

의존성 업데이트
최소 안정성 설정 업데이트

영향도 중간 변경 사항

데이터베이스 표현식
모델 "Dates" 프로퍼티
Monolog 3
Redis 캐시 태그
서비스 모킹
언어 디렉토리

영향도 낮은 변경 사항

클로저 유효성 검사 규칙 메시지
Form Request after 메서드
Public 경로 바인딩
Query 예외 생성자
Rate Limiter 반환 값
Redirect::home 메서드
Bus::dispatchNow 메서드
registerPolicies 메서드
ULID 컬럼

9.x에서 10.0으로 업그레이드

예상 소요 시간: 약 10분

NOTE

이 가이드에서는 가능한 모든 호환성 변경 사항을 다루고 있습니다. 다만 일부 변경 사항은 프레임워크의 특정 부분에만 해당하므로, 실제로 여러분의 애플리케이션에 영향을 미치는 항목은 그 중 일부일 수 있습니다. 업그레이드 작업을 자동화하고 싶다면 Laravel Shift를 활용해 보세요.

의존성 업데이트

영향도: 높음

PHP 8.1.0 이상 필요

Laravel 10은 PHP 8.1.0 이상을 요구합니다.

Composer 2.2.0 이상 필요

Laravel 10은 Composer 2.2.0 이상을 요구합니다.

Composer 의존성

composer.json 파일에서 아래 패키지 버전을 다음과 같이 업데이트하세요:

laravel/framework를 ^10.0으로
laravel/sanctum을 ^3.2으로
doctrine/dbal을 ^3.0으로
spatie/laravel-ignition을 ^2.0으로
laravel/passport를 ^11.0으로 (업그레이드 가이드)
laravel/ui를 ^4.0으로

Sanctum 2.x에서 3.x로 업그레이드하는 경우, Sanctum 업그레이드 가이드를 반드시 먼저 확인하세요.

PHPUnit 10을 사용하려면 phpunit.xml의 <coverage> 섹션에서 processUncoveredFiles 속성을 제거한 후, 아래 패키지도 함께 업데이트하세요:

nunomaduro/collision을 ^7.0으로
phpunit/phpunit을 ^10.0으로

마지막으로, 프로젝트에서 사용 중인 서드파티 패키지들이 Laravel 10을 지원하는 버전인지도 확인하세요.

최소 안정성 설정

composer.json의 minimum-stability 설정을 stable로 변경하세요. 기본값이 이미 stable이므로, 해당 항목을 아예 삭제해도 무방합니다:

"minimum-stability": "stable",

애플리케이션

Public 경로 바인딩

영향도: 낮음

컨테이너에 path.public을 바인딩하여 public 경로를 커스터마이징하고 있었다면, 대신 Illuminate\Foundation\Application 객체의 usePublicPath 메서드를 사용하도록 코드를 수정하세요:

app()->usePublicPath(__DIR__.'/public');

인가(Authorization)

`registerPolicies` 메서드

영향도: 낮음

AuthServiceProvider의 registerPolicies 메서드는 이제 프레임워크가 자동으로 호출합니다. 따라서 AuthServiceProvider의 boot 메서드에서 해당 메서드를 직접 호출하는 코드를 제거해도 됩니다.

캐시

Redis 캐시 태그

영향도: 중간

Cache::tags()는 Memcached를 캐시 드라이버로 사용하는 애플리케이션에만 권장됩니다. Redis를 캐시 드라이버로 사용 중이라면, Memcached로 전환하거나 Laravel 12.30.0으로 업그레이드하는 것을 권장합니다.

데이터베이스

데이터베이스 표현식

영향도: 중간

DB::raw로 생성되는 데이터베이스 "표현식(expression)"이 Laravel 10.x에서 내부적으로 재작성되었습니다. 이로 인해 표현식의 원시 문자열 값을 얻으려면 (string)으로 캐스팅하거나 __toString()을 직접 호출하는 방식 대신, getValue(Grammar $grammar) 메서드를 사용해야 합니다.

일반적인 애플리케이션에는 영향이 없습니다. 다만, 표현식을 문자열로 직접 캐스팅하거나 __toString()을 호출하는 코드가 있다면 아래와 같이 getValue 메서드를 사용하도록 수정하세요:

use Illuminate\Support\Facades\DB;

$expression = DB::raw('select 1');

$string = $expression->getValue(DB::connection()->getQueryGrammar());

Query 예외 생성자

영향도: 매우 낮음

Illuminate\Database\QueryException의 생성자가 이제 첫 번째 인자로 문자열 형태의 커넥션 이름을 받습니다. 이 예외를 직접 던지는 코드가 있다면 인자 순서를 맞게 수정하세요.

ULID 컬럼

영향도: 낮음

마이그레이션에서 ulid 메서드를 인자 없이 호출하면 이제 컬럼 이름이 ulid로 생성됩니다. 이전 Laravel 버전에서는 인자 없이 호출할 경우 잘못된 이름인 uuid로 컬럼이 생성되었습니다:

$table->ulid();

컬럼 이름을 명시적으로 지정하려면 메서드에 이름을 직접 전달하세요:

$table->ulid('ulid');

Eloquent

모델 "Dates" 프로퍼티

영향도: 중간

Eloquent 모델의 $dates 프로퍼티가 완전히 제거되었습니다. 날짜 캐스팅이 필요하다면 $casts 프로퍼티를 사용하세요:

protected $casts = [
    'deployed_at' => 'datetime',
];

다국어(Localization)

언어 디렉토리

영향도: 없음

기존 애플리케이션에는 영향이 없습니다. 다만 새로운 Laravel 애플리케이션 뼈대(skeleton)에서는 lang 디렉토리가 기본으로 포함되지 않습니다. 새 프로젝트에서 언어 파일이 필요하다면 Artisan 명령어로 게시할 수 있습니다:

php artisan lang:publish

로깅

Monolog 3

영향도: 중간

Laravel의 Monolog 의존성이 Monolog 3.x로 업데이트되었습니다. 애플리케이션 내에서 Monolog를 직접 사용하고 있다면 Monolog의 업그레이드 가이드를 확인하세요.

BugSnag, Rollbar 등 서드파티 로깅 서비스를 사용 중이라면, 해당 패키지가 Monolog 3.x 및 Laravel 10.x를 지원하는 버전인지 확인하고 필요 시 업그레이드하세요.

큐(Queue)

`Bus::dispatchNow` 메서드

영향도: 낮음

더 이상 사용되지 않는 Bus::dispatchNow와 dispatch_now 헬퍼가 제거되었습니다. 각각 Bus::dispatchSync와 dispatch_sync로 대체하세요.

`dispatch()` 헬퍼 반환 값

영향도: 낮음

Illuminate\Contracts\Queue를 구현하지 않는 클래스에 dispatch를 사용할 경우, 이전에는 해당 클래스의 handle 메서드 반환 값을 돌려줬지만 이제는 Illuminate\Foundation\Bus\PendingBatch 인스턴스를 반환합니다. 이전 동작이 필요하다면 dispatch_sync()를 사용하세요.

라우팅

미들웨어 별칭

영향도: 선택 사항

새로운 Laravel 애플리케이션에서는 App\Http\Kernel 클래스의 $routeMiddleware 프로퍼티가 역할을 더 명확히 표현하는 $middlewareAliases로 이름이 변경되었습니다. 기존 애플리케이션에서도 이름을 변경할 수 있지만 필수는 아닙니다.

Rate Limiter 반환 값

영향도: 낮음

RateLimiter::attempt 메서드를 호출할 때, 전달한 클로저의 반환 값이 이제 메서드의 반환 값으로 그대로 전달됩니다. 클로저가 아무것도 반환하지 않거나 null을 반환하면, attempt 메서드는 true를 반환합니다:

$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

`Redirect::home` 메서드

영향도: 매우 낮음

더 이상 사용되지 않는 Redirect::home 메서드가 제거되었습니다. 이름이 지정된 라우트로 명시적으로 리다이렉트하도록 변경하세요:

return Redirect::route('home');

테스팅

서비스 모킹

영향도: 중간

더 이상 사용되지 않는 MocksApplicationServices 트레이트가 프레임워크에서 제거되었습니다. 이 트레이트는 expectsEvents, expectsJobs, expectsNotifications 등의 테스트 메서드를 제공했습니다.

이 메서드들을 사용 중이라면 각각 Event::fake, Bus::fake, Notification::fake로 전환하세요. 각 컴포넌트의 페이크(fake) 사용법은 해당 문서를 참고하세요.

유효성 검사(Validation)

클로저 유효성 검사 규칙 메시지

영향도: 매우 낮음

클로저 기반의 커스텀 유효성 검사 규칙에서 $fail 콜백을 두 번 이상 호출하면, 이제 이전 메시지를 덮어쓰는 대신 배열에 메시지가 누적됩니다. 대부분의 애플리케이션에는 영향이 없습니다.

또한, $fail 콜백이 이제 객체를 반환합니다. 유효성 검사 클로저의 반환 타입을 명시적으로 선언했다면 타입 힌트를 수정해야 할 수 있습니다:

public function rules()
{
    'name' => [
        function ($attribute, $value, $fail) {
            $fail('validation.translation.key')->translate();
        },
    ],
}

유효성 검사 메시지와 클로저 규칙

영향도: 매우 낮음

이전에는 클로저 기반 유효성 검사 규칙에서 $fail 콜백에 배열을 전달해 다른 키에 실패 메시지를 지정할 수 있었습니다. 이제는 첫 번째 인자로 키를, 두 번째 인자로 실패 메시지를 전달하는 방식으로 변경되었습니다:

Validator::make([
    'foo' => 'string',
    'bar' => [function ($attribute, $value, $fail) {
        $fail('foo', '오류가 발생했습니다!');
    }],
]);

Form Request `after` 메서드

영향도: 매우 낮음

Form Request에서 after 메서드는 이제 Laravel이 예약한 메서드입니다. Form Request에 after 메서드를 직접 정의해 사용하고 있었다면, 이름을 변경하거나 Laravel Form Request의 새로운 "유효성 검사 후(after validation)" 기능을 활용하도록 수정하세요.

기타 변경 사항

laravel/laravel GitHub 저장소의 변경 이력도 함께 확인하는 것을 권장합니다. 필수 변경 사항은 아니지만, 설정 파일이나 코드 구조를 최신 상태로 유지하는 데 도움이 됩니다.

GitHub 비교 도구를 사용하면 9.x와 10.x 사이의 변경 사항을 쉽게 확인하고, 필요한 항목만 선택적으로 적용할 수 있습니다. 다만 비교 결과 중 상당 부분은 PHP 네이티브 타입 도입에 따른 변경으로, 하위 호환성이 유지되므로 Laravel 10 마이그레이션 시 반드시 적용할 필요는 없습니다.