메인 콘텐츠로 건너뛰기
Laravel은 매년 2~3월 즈음에 메이저 버전 업그레이드를 합니다. 패키지 개발자에게, 새 버전에의 대응을 신속히 완료하는 것은 에코시스템 전체에의 공헌이며, 자기 패키지의 신뢰성을 높이는 중요한 활동입니다.
이 페이지는 패키지 개발의 기초의 자매 페이지입니다. 패키지 개발의 기본적인 지식(서비스 프로바이더, composer.json의 구성 등)을 전제로 하고 있습니다.

​
Laravel의 메이저 버전 업그레이드에의 대응

​
대응의 흐름

1

composer.json의 require를 갱신한다

새 버전을 의존 범위에 추가합니다. 오래된 버전의 서포트를 이어가는 경우에는 ||로 나열합니다.
"require": {
    "php": "^8.2",
    "illuminate/support": "^12.0||^13.0"
}
새 버전에의 대응이 완료되고, 오래된 버전의 서포트를 종료하는 경우에는 오래된 제약을 삭제합니다.
"require": {
    "php": "^8.3",
    "illuminate/support": "^13.0||^14.0"
}
illuminate/framework 전체가 아니라 illuminate/support 등 필요한 컴포넌트만에 의존함으로써, 의존 트리를 작게 유지할 수 있습니다.
2

테스트를 새 버전에서 실행한다

로컬 또는 CI 환경에서 새로운 Laravel 버전을 사용하여 테스트를 실행합니다.
composer update
vendor/bin/pest
테스트가 통과되면 기본적인 호환성은 확인되어 있습니다. 통과되지 않는 경우에는, 변경된 API나 삭제된 메서드를 수정합니다.
3

GitHub Actions의 테스트 매트릭스에 새 버전을 추가한다

CI의 테스트 매트릭스에 Laravel의 새 버전을 추가하여, 지속적으로 호환성을 확인합니다. 자세한 것은 테스트 매트릭스의 설정 예를 참조해 주세요.
4

새 버전 대응을 릴리스한다

composer.json의 변경을 포함한 새로운 버전을 태그를 붙여 릴리스합니다. 사용자는 composer update만으로 새로운 Laravel 버전에 설치할 수 있게 됩니다.

​
공식 패키지를 참고로 한다

대응 방법에 헤맬 때는, Laravel의 공식 패키지의 composer.json을 참조하는 것이 가장 확실합니다. 이러한 패키지는 Laravel 팀이 관리하고 있으며, 새 버전에의 대응이 가장 빠르고, illuminate/*의 의존 버전 쓰는 법도 참고가 됩니다.

​
PHP 버전 요건의 갱신

Laravel의 버전 업그레이드는 PHP의 최저 요건도 상향할 때가 있습니다. 패키지의 composer.json에서 PHP 요건도 함께 갱신합니다.
Laravel최저 PHP 요건
Laravel 11PHP 8.2
Laravel 12PHP 8.2
Laravel 13PHP 8.3
Laravel 14PHP 8.4
"require": {
    "php": "^8.2",
    "illuminate/support": "^11.0||^12.0||^13.0"
}

​
새로운 PHP 기능을 적극적으로 사용하는 경우

PHP 8.3 이후의 기능(타입 지정 상수, 새로운 랜덤 함수 등)을 사용하고 싶은 경우에는, 최저 요건을 상향하는 판단이 필요합니다. 최저 요건의 상향은 시맨틱 버저닝상은 파괴적 변경이므로, 메이저 버전 업그레이드 시에 하는 것이 적절합니다. 
"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0||^13.0"
}
PHP의 최저 요건을 상향하면, 오래된 PHP를 사용하고 있는 사용자가 패키지를 갱신할 수 없게 됩니다. README나 CHANGELOG에 명기하여 사전에 주지하는 것이 중요합니다.

​
구 버전 서포트의 종료 전략

구 버전을 언제까지고 유지하는 것은, 장기적으로는 유지보수 비용을 증대시킵니다. 명확한 서포트 정책을 정하고, 정기적으로 오래된 버전의 서포트를 종료하는 것이 건전한 패키지 운영으로 이어집니다.

​
서포트 종료의 타이밍

일반적인 접근 방식은, Laravel의 서포트 기간에 맞추는 것입니다. Laravel은 각 버전에 대해 버그 수정 18개월, 시큐리티 수정 2년의 서포트를 제공하고 있습니다. 패키지도 같은 정책을 채용하면 사용자에게 알기 쉬워집니다.
판단 기준설명
Laravel의 공식 서포트 종료해당 Laravel 버전의 서포트가 종료된 타이밍에 대응을 그만둠
이용 상황Packagist의 다운로드 통계로 구 버전 이용자가 적어진 타이밍
기능 추가의 장벽구 버전 대응을 위해 새 기능의 구현이 복잡해진 타이밍

​
서포트 정책을 README에 명기한다

사용자가 기댓값을 올바르게 가질 수 있도록, 서포트 정책을 README.md에 기재합니다. 
## Version Compatibility

| Package | Laravel | PHP  |
|---------|---------|------|
| 3.x     | 13.x    | ^8.2 |
| 2.x     | 11.x, 12.x | ^8.2 |
| 1.x     | 10.x    | ^8.1 |

Only the latest major version receives new features.
Security fixes are backported to the previous major version for 12 months.

​
구 버전 유지의 비용

구 버전 서포트를 이어가면 다음의 비용이 발생합니다.
  • 버그 수정의 이중 대응 — 같은 버그를 여러 브랜치에서 수정할 필요가 있음
  • 분기 코드의 증가 — 버전별로 다른 구현을 조건 분기로 흡수하는 복잡함
  • 테스트 매트릭스의 비대화 — CI 실행 시간이 길어짐
  • 시큐리티 패치의 복잡화 — 오래된 버전에도 안전하게 백포트할 필요가 있음
에코시스템 전체가 버전 업그레이드해 가는 가운데, 구 버전의 서포트를 적절히 종료하는 것은, 사용자에게 최신 환경에의 이관을 촉구하는 효과도 있습니다.

​
조기 대응의 메리트

Laravel의 릴리스와 동시에 대응이 완료되어 있으면, 사용자는 즉시 새 버전으로 이관할 수 있습니다. 이것은 패키지의 신뢰성을 나타내는 중요한 시그널입니다.

​
개발판에서 사전 검증한다

Laravel은 beta/RC를 공개하지 않는 대신, dev-master 또는 @dev를 지정함으로써 개발 중의 차기 버전을 설치할 수 있습니다. 메이저 릴리스 전에 동작 확인을 함으로써, 제로데이 대응이 가능해집니다. 
# dev-master で次期バージョンをインストール
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest
또는 @dev 제약으로 설치할 수도 있습니다. 
composer require laravel/framework:^14.0@dev --no-update
composer update
vendor/bin/pest
minimum-stability를 dev로 설정함으로써, 개발판과의 의존 관계를 해결할 수 있습니다. 
{
    "minimum-stability": "dev",
    "prefer-stable": true
}
prefer-stable: true를 지정하면, 안정판이 존재하는 경우에는 안정판이 우선됩니다. 개발판으로 테스트하면서도, 안정판으로의 자동 전환이 보증됩니다.

​
최초의 스텝은 composer.json의 변경만으로 좋다

완전한 호환성 확인 전이라도, composer.json의 의존 범위를 갱신하여 릴리스하는 것만으로, 사용자는 패키지를 설치할 수 있게 됩니다. 
"illuminate/support": "^12.0||^13.0"
작은 결함은 릴리스 후라도 패치 버전으로 수정할 수 있습니다. 완벽한 대응을 기다리기보다, 설치 가능한 상태로 하는 것을 우선합시다.

​
릴리스 정보의 팔로잉 방법

새 버전의 릴리스 정보를 시기 적절히 파악하기 위한 방법입니다.
정보원내용
GitHub Watch 기능리포지토리의 “Watch → Custom → Releases”에서 메일 통지를 받음. framework 이외의 주요 패키지도 등록해 두면 좋음
Laravel 공식 블로그메이저 릴리스의 발표와 새 기능 해설
Laravel 공식 문서 업그레이드 가이드파괴적 변경의 목록
laravel/framework 커밋 로그차기 버전의 변경을 선점하는 경우에는 커밋 로그를 직접 따라감

​
테스트 매트릭스의 설정 예

GitHub Actions에서 여러 Laravel 버전과 PHP 버전의 조합을 자동 테스트하는 워크플로우 예입니다. 
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]
        include:
          - laravel: "^13.0"
            testbench: "^10.0"
          - laravel: "^12.0"
            testbench: "^9.0"

    name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           "orchestra/testbench:${{ matrix.testbench }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest

​
fail-fast: false의 중요성

fail-fast: false를 설정함으로써, 하나의 조합이 실패해도 다른 조합의 테스트를 계속합니다. 어느 버전의 조합에서 문제가 발생하고 있는지를 한 번의 CI 실행으로 파악할 수 있습니다.

​
테스트 매트릭스의 단계적 갱신

새로운 Laravel 버전이 나오면, 매트릭스에 추가합니다. 오래된 버전의 서포트를 종료하면, 매트릭스에서 삭제합니다. 
# Laravel 14がリリースされたら追加
matrix:
  laravel: ["^13.0", "^14.0"]
  include:
    - laravel: "^14.0"
      testbench: "^11.0"
    - laravel: "^13.0"
      testbench: "^10.0"

​
composer.json의 샘플

여러 버전 대응의 composer.json의 완전한 예입니다. 
{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "pestphp/pest": "^3.0",
        "pestphp/pest-plugin-laravel": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ]
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

​
버전 업그레이드 대응 체크리스트

  • 개발판(dev-master / @dev)에서 동작 확인을 실시
  • 공식 업그레이드 가이드에서 파괴적 변경을 확인
  • 테스트 환경에서 새 버전에의 대응을 구현
  • 테스트 매트릭스에 새 버전을 추가하여 CI에서 확인
  • composer.json의 illuminate/* 요건에 새 버전을 추가
  • 필요에 따라 PHP 요건을 갱신
  • require-dev의 orchestra/testbench도 대응 버전으로 갱신
  • 새 버전을 태그 붙여 Packagist에 반영
  • README의 버전 호환성 표를 갱신
  • CHANGELOG/README에 서포트 종료를 명기
  • composer.json에서 구 버전의 제약을 삭제
  • 테스트 매트릭스에서 구 버전을 삭제
  • 구 버전용의 조건 분기 코드를 정리

​
관련 페이지

패키지 개발의 기초

서비스 프로바이더를 핵심으로 한 Laravel 패키지의 개발 방법을 해설합니다.

Pest를 이용한 고급 테스트

Pest의 Expectation API나 데이터셋을 사용한 패키지 테스트의 작성법을 해설합니다.
마지막 수정일 2026년 7월 13일

관련 항목

패키지의 CHANGELOG와 릴리스 관리Laravel 신규 코드 해석 에코시스템 — surveyor / ranger / roster패키지의 정적 해석 (PHPStan / Larastan)Orchestra Testbench로 Laravel 패키지를 테스트하기GitHub Actions의 핀 고정과 보안