시작하며
Laravel 11은 2024년 3월에 릴리스되었습니다. 이 가이드에서는 Laravel 10.x에서 11.x로의 업그레이드 절차를 설명합니다.업그레이드에 필요한 예상 시간은 약 15분입니다. 다만 파괴적 변경이 애플리케이션에 미치는 영향은 규모나 사용하고 있는 기능에 따라 다릅니다.
Laravel Shift를 사용한 자동 업그레이드
Laravel Shift를 사용하여 업그레이드를 자동화할 수도 있습니다. Shift는 애플리케이션의 의존관계나 설정 파일을 자동으로 갱신해 줍니다.영향도별 변경점
영향도: 높음
- 의존관계 갱신
- 애플리케이션 구조의 변경
- 부동소수점형의 변경
- 컬럼 변경 시 속성 보존
- SQLite 최소 버전
- Sanctum 갱신
영향도: 중간
- Carbon 3
- 패스워드의 재해시
- 초 단위 레이트 리밋
- Spatie Once 패키지
영향도: 낮음
- Doctrine DBAL 삭제
- Eloquent 모델의
casts메서드 - 공간형의 변경
Enumerable컨트랙트UserProvider컨트랙트Authenticatable컨트랙트
업그레이드 절차
의존관계 갱신
영향도: 높음composer.json의 이하 의존관계를 갱신해 주세요.
doctrine/dbal을 수동으로 추가하고 있었던 경우에는 삭제할 수 있습니다. Laravel 11에서는 이 패키지로의 의존이 없어졌습니다.
PHP 버전 요구사항
영향도: 높음 Laravel 11에서는 PHP 8.2.0 이상이 필요합니다. 또한 Laravel의 HTTP 클라이언트에는 curl 7.34.0 이상이 필요합니다.애플리케이션 구조의 변경
영향도: 높음 Laravel 11에서는 기본 애플리케이션 구조가 간소화되었습니다. 서비스 프로바이더, 미들웨어, 설정 파일의 수가 대폭 삭감되어 있습니다. 다만, Laravel 10의 애플리케이션을 Laravel 11로 업그레이드할 때, 애플리케이션 구조의 마이그레이션을 시도하는 것은 권장하지 않습니다. Laravel 11은 Laravel 10의 애플리케이션 구조도 지원하도록 설계되어 있습니다. 주요 구조적 변경점:bootstrap/app.php에서 미들웨어, 예외 핸들러, 라우팅을 직접 설정하도록 변경app/Http/Kernel.php가 폐지되고bootstrap/app.php에 통합- 기본 서비스 프로바이더 수가 삭감되어
bootstrap/providers.php에서 관리 config/디렉터리의 파일 수가 삭감 (필요에 따라php artisan config:publish로 공개 가능)
파괴적 변경 (Breaking Changes)
인증
패스워드 재해시
영향도: 중간 Laravel 11에서는 인증 시 해시 알고리즘의 “워크 팩터”가 변경되어 있는 경우 자동으로 패스워드를 재해시합니다.User 모델의 패스워드 필드 이름이 password 이외인 경우, 모델의 authPasswordName 프로퍼티로 지정해 주세요.
config/hashing.php에 이하를 추가해 주세요.
UserProvider 컨트랙트
영향도: 낮음
Illuminate\Contracts\Auth\UserProvider 컨트랙트에 rehashPasswordIfRequired 메서드가 추가되었습니다. 이 인터페이스를 구현하고 있는 클래스가 있는 경우에는 메서드를 추가해 주세요.
Authenticatable 컨트랙트
영향도: 낮음
Illuminate\Contracts\Auth\Authenticatable 컨트랙트에 getAuthPasswordName 메서드가 추가되었습니다. 이 인터페이스를 구현하고 있는 클래스가 있는 경우에는 메서드를 추가해 주세요.
데이터베이스
SQLite 최소 버전
영향도: 높음 SQLite를 사용하고 있는 경우에는 SQLite 3.26.0 이상이 필요합니다. 또한 Laravel 11의 신규 프로젝트에서는 기본 데이터베이스 드라이버가 SQLite로 변경되었습니다.컬럼 변경 시의 속성 보존
영향도: 높음 컬럼을 변경할 때, 변경 후에도 유지하고 싶은 모든 수식자를 명시적으로 지정해야 합니다. 지정되지 않은 속성은 삭제됩니다.부동소수점형의 변경
영향도: 높음double과 float의 마이그레이션 컬럼 타입이 전 데이터베이스에서 통일되었습니다.
unsignedDecimal, unsignedDouble, unsignedFloat 메서드는 삭제되었습니다. 계속해서 unsigned 속성을 사용하는 경우에는 메서드 체인으로 지정해 주세요.
Eloquent 모델의 casts 메서드
영향도: 낮음
기저 Eloquent 모델 클래스에 casts 메서드가 정의되었습니다. 애플리케이션의 모델에서 casts라는 릴레이션을 정의하고 있는 경우에는 이름이 경합하므로 변경이 필요합니다.
MariaDB 전용 드라이버
영향도: 매우 낮음 Laravel 11에서는 MariaDB용 전용 데이터베이스 드라이버가 추가되었습니다. MariaDB에 접속하는 경우에는 설정에서mariadb 드라이버를 사용할 수 있습니다.
공간형의 변경
영향도: 낮음 공간 컬럼 타입이 전 데이터베이스에서 통일되었습니다.point, lineString, polygon 등의 메서드 대신에 geometry 또는 geography를 사용해 주세요.
subtype과 srid를 전달해 주세요.
Doctrine DBAL 삭제
영향도: 낮음 Laravel은 Doctrine DBAL로의 의존을 없앴습니다. 이하의 클래스나 메서드가 삭제되었습니다.Schema\Builder::useNativeSchemaOperationsIfPossible()Connection::getDoctrineConnection()Connection::getDoctrineSchemaManager()Connection::registerDoctrineType()DatabaseManager::registerDoctrineType()Schema\Grammars\ChangeColumn클래스Schema\Grammars\RenameColumn클래스
Schema::getTables(), Schema::getColumns(), Schema::getIndexes(), Schema::getForeignKeys() 등의 새로운 네이티브 메서드를 사용해 주세요.
날짜
Carbon 3
영향도: 중간 Laravel 11은 Carbon 2와 Carbon 3 양쪽을 지원합니다. Carbon 3으로 업그레이드할 경우,diffIn* 메서드가 부동소수점 수를 반환하게 되고, 음수 값으로 시간의 방향을 나타내는 것에 주의해 주세요.
레이트 리밋
초 단위 레이트 리밋
영향도: 중간 Laravel 11에서는 분 단위가 아니라 초 단위의 레이트 리밋이 지원되었습니다.GlobalLimit, Limit 클래스의 생성자가 초 단위를 받도록 되었습니다.
Limit 클래스의 decayMinutes 프로퍼티는 decaySeconds로 개명되어 초 단위가 되었습니다.
ThrottlesExceptions와 ThrottlesExceptionsWithRedis의 생성자도 초 단위를 받도록 되었습니다.
패키지
서비스 프로바이더의 퍼블리시
영향도: 매우 낮음 Laravel 11의 신규 애플리케이션에는config/app.php의 providers 배열이 없습니다. 패키지에서 서비스 프로바이더를 퍼블리시하고 있는 경우에는 ServiceProvider::addProviderToBootstrapFile 메서드를 사용해 주세요.
Sanctum
Sanctum 업데이트
영향도: 높음 Laravel 11은 Sanctum 3.x를 지원하지 않습니다.composer.json의 Sanctum 의존관계를 ^4.0으로 갱신해 주세요.
Sanctum 4.0은 마이그레이션을 자동으로 로드하지 않게 되었습니다. 이하 명령으로 퍼블리시해 주세요.
config/sanctum.php의 미들웨어 설정을 갱신해 주세요.
Spatie Once 패키지
영향도: 중간 Laravel 11은 독자적인once 함수를 제공하도록 되었습니다. spatie/once 패키지를 사용하고 있는 경우에는 경합을 피하기 위해 composer.json에서 삭제해 주세요.
정리
Laravel 11은 큰 구조 변경을 포함하는 버전이지만, Laravel 10의 애플리케이션 구조는 그대로 동작하므로, 단계적으로 마이그레이션할 수 있습니다.| 변경점 | 영향도 | 대응 |
|---|---|---|
composer.json의 의존관계 갱신 | 높음 | laravel/framework ^11.0으로 변경 |
| PHP 8.2 필수 | 높음 | PHP 버전 확인 |
| 컬럼 변경 시의 속성 보존 | 높음 | change() 사용 부분 확인 |
| 부동소수점형의 변경 | 높음 | double/float 컬럼의 정의 확인 |
| SQLite 3.26.0+ 필수 | 높음 | SQLite 버전 확인 |
Sanctum ^4.0 | 높음 | 마이그레이션을 퍼블리시 |
| Carbon 3 | 중간 | diffIn* 메서드의 반환 값 확인 |
| 초 단위 레이트 리밋 | 중간 | decayMinutes를 decaySeconds로 변경 |
| Doctrine DBAL 삭제 | 낮음 | 네이티브 스키마 메서드로 이관 |
참고 자료
- 공식 업그레이드 가이드 (영어)
- laravel/laravel 리포지토리의 차분 (10.x → 11.x)
- Laravel Shift — 업그레이드를 자동화하는 커뮤니티 서비스
- Carbon 3 변경 로그