메인 콘텐츠로 건너뛰기

시작하며

Laravel 10은 2023년 2월 14일에 릴리스되었습니다. 이 가이드에서는 Laravel 9.x에서 10.x로의 업그레이드 절차를 설명합니다.
업그레이드에 필요한 예상 시간은 약 10분입니다. 다만 파괴적 변경이 애플리케이션에 미치는 영향은 규모나 사용하고 있는 기능에 따라 다릅니다.

Laravel Shift를 사용한 자동 업그레이드

Laravel Shift를 사용하여 업그레이드를 자동화할 수도 있습니다. Shift는 애플리케이션의 의존관계나 설정 파일을 자동으로 갱신해 줍니다.

영향도별 변경점

영향도: 높음

  • 의존관계 갱신
  • minimum-stability 갱신

영향도: 중간

  • 데이터베이스 식 변경
  • 모델의 $dates 프로퍼티 삭제
  • Monolog 3
  • Redis 캐시 태그
  • 서비스 모킹의 변경
  • 언어 디렉터리

영향도: 낮음

  • 클로저 유효성 검증 룰의 메시지
  • 폼 리퀘스트의 after 메서드
  • 퍼블릭 패스 바인딩
  • QueryException 생성자
  • 레이트 리미터의 반환값
  • Redirect::home 메서드의 삭제
  • Bus::dispatchNow 메서드의 삭제
  • registerPolicies 메서드
  • ULID 컬럼

업그레이드 절차

의존관계 갱신

영향도: 높음 composer.json의 이하 의존관계를 갱신해 주세요.
{
  "require": {
    "laravel/framework": "^10.0",
    "laravel/sanctum": "^3.2",
    "doctrine/dbal": "^3.0",
    "spatie/laravel-ignition": "^2.0"
  }
}
패키지를 사용하고 있는 경우에는 함께 갱신해 주세요.
{
  "require": {
    "laravel/passport": "^11.0",
    "laravel/ui": "^4.0"
  }
}
PHPUnit 10을 사용하는 경우에는 이하도 갱신해 주세요.
{
  "require-dev": {
    "nunomaduro/collision": "^7.0",
    "phpunit/phpunit": "^10.0"
  }
}
PHPUnit 10을 사용하는 경우에는 phpunit.xml<coverage> 섹션에서 processUncoveredFiles 속성을 삭제해 주세요.
갱신 후, 이하 명령으로 의존관계를 설치합니다.
composer update
Sanctum 2.x에서 3.x로의 업그레이드에는 Sanctum 3.x 업그레이드 가이드도 참고해 주세요.

minimum-stability 갱신

영향도: 높음 composer.jsonminimum-stabilitystable로 갱신해 주세요. 기본값이 stable이므로 이 설정을 삭제해도 상관없습니다.
"minimum-stability": "stable"

PHP 버전 요구사항

영향도: 높음 Laravel 10에서는 PHP 8.1.0 이상Composer 2.2.0 이상이 필요합니다.

파괴적 변경 (Breaking Changes)

애플리케이션

퍼블릭 패스 바인딩

영향도: 낮음 path.public을 컨테이너에 바인딩하여 퍼블릭 패스를 커스터마이즈하고 있는 경우에는, Illuminate\Foundation\ApplicationusePublicPath 메서드를 사용하도록 변경해 주세요.
app()->usePublicPath(__DIR__.'/public');

인가

registerPolicies 메서드

영향도: 낮음 AuthServiceProviderregisterPolicies 메서드는 프레임워크가 자동으로 호출하도록 되었습니다. boot 메서드에서 이 메서드의 호출을 삭제할 수 있습니다.

캐시

Redis 캐시 태그

영향도: 중간 Cache::tags()는 Memcached를 사용하는 애플리케이션에만 권장됩니다. Redis를 캐시 드라이버로서 사용하고 있는 경우에는 Memcached로의 마이그레이션을 검토해 주세요.

데이터베이스

데이터베이스 식 변경

영향도: 중간 DB::raw로 생성되는 데이터베이스 식이 다시 작성되었습니다. 식의 생 문자열 값을 취득하려면 getValue(Grammar $grammar) 메서드를 사용할 필요가 있습니다. (string)으로의 캐스트는 사용할 수 없게 되었습니다.
use Illuminate\Support\Facades\DB;

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

// 변경 전
$string = (string) $expression;

// 변경 후
$string = $expression->getValue(DB::connection()->getQueryGrammar());
최종 사용자의 애플리케이션에는 통상 영향을 주지 않지만, 데이터베이스 식을 문자열로 캐스트하고 있는 경우에는 갱신이 필요합니다.

QueryException 생성자

영향도: 매우 낮음 Illuminate\Database\QueryException의 생성자의 첫 번째 인자에 문자열의 접속명이 추가되었습니다. 이 예외를 수동으로 던지고 있는 경우에는 코드를 수정해 주세요.

ULID 컬럼

영향도: 낮음 마이그레이션에서 인자 없이 ulid 메서드를 호출한 경우, 컬럼 이름은 ulid가 됩니다. 이전 릴리스에서는 인자 없이 호출한 경우, 잘못하여 uuid라는 이름의 컬럼이 작성되고 있었습니다.
// 컬럼 이름이 "ulid"가 됨
$table->ulid();

// 컬럼 이름을 명시적으로 지정하는 경우
$table->ulid('ulid');

Eloquent

모델의 $dates 프로퍼티

영향도: 중간 Eloquent 모델의 비권장 프로퍼티 $dates가 삭제되었습니다. $casts 프로퍼티를 사용해 주세요.
// 변경 전
protected $dates = ['deployed_at'];

// 변경 후
protected $casts = [
    'deployed_at' => 'datetime',
];

로컬라이제이션

언어 디렉터리

영향도: 없음 기존 애플리케이션에는 영향을 주지 않지만, 신규 Laravel 애플리케이션의 스켈레톤에는 기본으로 lang 디렉터리가 포함되지 않게 되었습니다. 필요한 경우 Artisan 명령으로 공개할 수 있습니다.
php artisan lang:publish

로그

Monolog 3

영향도: 중간 Laravel의 Monolog 의존관계가 Monolog 3.x로 갱신되었습니다. 애플리케이션 내에서 Monolog를 직접 사용하고 있는 경우에는 Monolog의 업그레이드 가이드를 확인해 주세요. BugSnag이나 Rollbar 등의 서드파티 로깅 서비스를 사용하고 있는 경우에는 Monolog 3.x와 Laravel 10.x를 지원하는 버전으로의 업그레이드가 필요한 경우가 있습니다.
Monolog 3.x의 변경점은 Monolog 3.x 업그레이드 가이드에서 확인할 수 있습니다.

Bus::dispatchNow 메서드의 삭제

영향도: 낮음 비권장의 Bus::dispatchNowdispatch_now 메서드가 삭제되었습니다. Bus::dispatchSyncdispatch_sync 메서드를 사용해 주세요.
// 변경 전
Bus::dispatchNow(new MyJob());
dispatch_now(new MyJob());

// 변경 후
Bus::dispatchSync(new MyJob());
dispatch_sync(new MyJob());

라우팅

미들웨어 별칭

영향도: 임의 신규 Laravel 애플리케이션에서는 App\Http\Kernel 클래스의 $routeMiddleware 프로퍼티가 $middlewareAliases로 개명되었습니다. 기존 애플리케이션으로의 적용은 임의입니다.

레이트 리미터의 반환값

영향도: 낮음 RateLimiter::attempt 메서드를 호출한 경우, 제공한 클로저의 반환값이 그대로 반환되도록 되었습니다. 아무것도 반환하지 않거나 null을 반환한 경우에는 true가 반환됩니다.
$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Redirect::home 메서드의 삭제

영향도: 매우 낮음 비권장의 Redirect::home 메서드가 삭제되었습니다. 명시적으로 이름 있는 라우트로 리다이렉트하도록 변경해 주세요.
// 변경 전
return Redirect::home();

// 변경 후
return Redirect::route('home');

테스트

서비스 모킹

영향도: 중간 비권장의 MocksApplicationServices 트레이트가 프레임워크에서 삭제되었습니다. 이 트레이트는 expectsEvents, expectsJobs, expectsNotifications 등의 테스트 메서드를 제공하고 있었습니다. 이 메서드들을 사용하고 있는 경우에는 각각 Event::fake, Bus::fake, Notification::fake로 이관해 주세요.
// 변경 전
$this->expectsEvents(OrderShipped::class);

// 변경 후
Event::fake();
// ... 테스트 코드 ...
Event::assertDispatched(OrderShipped::class);

유효성 검증

클로저 유효성 검증 룰의 메시지

영향도: 매우 낮음 클로저 기반 커스텀 유효성 검증 룰에서 $fail 콜백을 여러 번 호출한 경우, 메시지가 덮어써지는 것이 아니라 배열에 추가되도록 되었습니다. 또한 $fail 콜백이 오브젝트를 반환하도록 되었습니다. 유효성 검증 클로저의 반환값을 타입 힌트하고 있는 경우에는 갱신이 필요합니다.
public function rules()
{
    return [
        'name' => [
            function ($attribute, $value, $fail) {
                $fail('validation.translation.key')->translate();
            },
        ],
    ];
}

폼 리퀘스트의 after 메서드

영향도: 매우 낮음 폼 리퀘스트 내의 after 메서드가 Laravel에 의해 예약되었습니다. 폼 리퀘스트에서 after 메서드를 정의하고 있는 경우에는, 새로운 “유효성 검증 후” 기능을 활용하도록 리네임 또는 변경해 주세요.

정리

Laravel 10은 비교적 작은 변경으로 구성되어 있어, 업그레이드는 짧은 시간에 완료할 수 있습니다.
변경점영향도대응
composer.json의 의존관계 갱신높음laravel/framework ^10.0으로 변경
PHP 8.1 / Composer 2.2 필수높음버전 확인 · 갱신
데이터베이스 식 변경중간(string) 캐스트를 getValue()로 변경
모델의 $dates 프로퍼티 삭제중간$casts로 이관
Monolog 3중간직접 사용하고 있는 경우는 업그레이드 가이드 확인
Redis 캐시 태그중간Memcached로의 마이그레이션 검토
MocksApplicationServices 삭제중간Event::fake 등으로 이관
Bus::dispatchNow 삭제낮음Bus::dispatchSync로 변경
ULID 컬럼명낮음마이그레이션의 ulid() 호출 확인
Redirect::home 삭제매우 낮음Redirect::route('home')으로 변경

참고 자료

마지막 수정일 2026년 7월 13일