> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 套件的版本相容性管理

> 從 composer.json 的更新到 GitHub Actions 的測試 matrix 設定，實務地說明因應 Laravel 與 PHP 主版本更新時的套件維護策略。

Laravel 每年 2 至 3 月左右進行主版本升級。對於套件開發者而言，快速完成新版本的支援是對整個生態系的貢獻，也是提升自身套件可靠度的重要活動。

<Info>
  本頁為[套件開發基礎](/zh-TW/advanced/package-development)的姊妹頁。以套件開發的基本知識（服務提供者、`composer.json` 的結構等）為前提。
</Info>

## 對 Laravel 主版本更新的因應

### 因應流程

<Steps>
  <Step title="更新 composer.json 的 require">
    將新版本加入相依範圍。若要繼續支援舊版本，可以 `||` 並列。

    ```json theme={null}
    "require": {
        "php": "^8.2",
        "illuminate/support": "^12.0||^13.0"
    }
    ```

    若新版本的因應完成、要終止舊版本支援，則刪除舊有約束。

    ```json theme={null}
    "require": {
        "php": "^8.3",
        "illuminate/support": "^13.0||^14.0"
    }
    ```

    <Tip>
      透過相依 `illuminate/support` 等所需元件而非整個 `illuminate/framework`，可讓相依樹保持較小。
    </Tip>
  </Step>

  <Step title="於新版本執行測試">
    於 local 或 CI 環境使用新的 Laravel 版本執行測試。

    ```shell theme={null}
    composer update
    vendor/bin/pest
    ```

    測試通過即可確認基本相容性。若未通過，需修正被變更的 API 或已刪除的方法。
  </Step>

  <Step title="於 GitHub Actions 測試 matrix 中加入新版本">
    於 CI 的測試 matrix 中加入 Laravel 的新版本，持續確認相容性。詳情請參考[測試 matrix 的設定範例](#測試-matrix-的設定範例)。
  </Step>

  <Step title="發布新版本因應">
    包含 `composer.json` 變更的新版本以 tag 發布。使用者只需 `composer update` 就能安裝於新的 Laravel 版本上。
  </Step>
</Steps>

### 參考官方套件

若對因應方式有疑問，參考 Laravel 官方套件的 `composer.json` 最為可靠。

* [laravel/socialite](https://github.com/laravel/socialite)
* [laravel/horizon](https://github.com/laravel/horizon)
* [laravel/telescope](https://github.com/laravel/telescope)

這些套件由 Laravel 團隊管理，對新版本的因應最快，`illuminate/*` 的相依版本寫法也可供參考。

## PHP 版本要求的更新

Laravel 的版本升級有時也會提升 PHP 的最低要求。於套件的 `composer.json` 一併更新 PHP 要求。

| Laravel    | 最低 PHP 要求 |
| ---------- | --------- |
| Laravel 11 | PHP 8.2   |
| Laravel 12 | PHP 8.2   |
| Laravel 13 | PHP 8.3   |
| Laravel 14 | PHP 8.4   |

```json theme={null}
"require": {
    "php": "^8.2",
    "illuminate/support": "^11.0||^12.0||^13.0"
}
```

### 若希望積極使用新的 PHP 功能

若要使用 PHP 8.3 以後的功能（型別化常數、新的隨機函式等），需判斷是否提升最低要求。提升最低要求在語意化版本上屬於破壞性變更，因此應於主版本升級時進行。

```json theme={null}
"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0||^13.0"
}
```

<Warning>
  若提升 PHP 最低要求，使用舊 PHP 的使用者將無法更新套件。務必於 README 或 CHANGELOG 明確標示以事先告知。
</Warning>

## 舊版本支援的終止策略

長期維持舊版本會增加維護成本。制定明確的支援政策，定期終止舊版本支援，有助於健康的套件營運。

### 終止支援的時機

一般做法是**配合 Laravel 的支援期間**。Laravel 對各版本提供 18 個月的 bug 修正、2 年的安全性修正支援。若套件也採相同政策，對使用者較易理解。

| 判斷基準           | 說明                        |
| -------------- | ------------------------- |
| Laravel 官方支援結束 | 於該 Laravel 版本支援結束時停止對應    |
| 使用情況           | Packagist 的下載統計顯示舊版使用者減少時 |
| 功能追加的障礙        | 為對應舊版本使新功能實作複雜化時          |

### 在 README 中明確標示支援政策

為使用者可以正確持有期待值，於 `README.md` 記載支援政策。

```markdown theme={null}
## 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.
```

### 維持舊版本的成本

持續支援舊版本會產生下列成本。

* **bug 修正的雙重處理** — 同一 bug 需在多個 branch 修正
* **分支程式碼增加** — 依版本以條件分支吸收不同實作的複雜性
* **測試 matrix 肥大化** — CI 執行時間變長
* **安全性 patch 的複雜化** — 需安全地 backport 至舊版本

於整體生態系不斷升級的過程中，適當終止舊版本支援對促使使用者遷移至最新環境亦有效果。

## 早期因應的好處

若能於 Laravel 發布同時完成因應，使用者可立刻遷移至新版本。這是套件可靠度的重要訊號。

### 以開發版事前驗證

Laravel 不公開 beta/RC，但可透過指定 `dev-master` 或 `@dev` 安裝開發中的下一版。於主版本發布前確認運作，可實現 Zero-day 因應。

```shell theme={null}
# 以 dev-master 安裝下一版
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest
```

或者也可以用 `@dev` 約束安裝。

```shell theme={null}
composer require laravel/framework:^14.0@dev --no-update
composer update
vendor/bin/pest
```

透過將 `minimum-stability` 設為 `dev`，可解析與開發版的相依關係。

```json theme={null}
{
    "minimum-stability": "dev",
    "prefer-stable": true
}
```

<Tip>
  指定 `prefer-stable: true` 後，若存在穩定版則會以穩定版優先。在以開發版測試的同時，仍能保證會自動切換至穩定版。
</Tip>

### 第一步只要變更 composer.json 即可

即便在完整相容性確認前，只要更新 `composer.json` 的相依範圍並發布，使用者就能夠安裝套件。

```json theme={null}
"illuminate/support": "^12.0||^13.0"
```

小的 bug 可以於發布後以 patch 版本修正。與其等待完美的因應，不如優先讓其能夠安裝。

### 掌握 Release 資訊的方法

以下是及時掌握新版本 Release 資訊的方法。

| 資訊來源                                                                                | 內容                                                                |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| GitHub Watch 功能                                                                     | 於儲存庫「Watch → Custom → Releases」接收 mail 通知。framework 以外主要套件也一併登錄較好 |
| [Laravel 官方部落格](https://laravel.com/blog)                                           | 主版本 Release 的公告與新功能解說                                             |
| [Laravel 官方文件 升級指南](https://laravel.com/docs/upgrade)                               | 破壞性變更的清單                                                          |
| [laravel/framework commit log](https://github.com/laravel/framework/commits/master) | 若要先行掌握下一版變更，可直接追 commit log                                       |

## 測試 matrix 的設定範例

以下為以 GitHub Actions 自動測試多個 Laravel 與 PHP 版本組合的 workflow 範例。

```yaml theme={null}
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 執行即可掌握是哪個版本組合出問題。

### 測試 matrix 的階段性更新

當新 Laravel 版本發布時，將其加入 matrix。當終止舊版本支援時，將其從 matrix 移除。

```yaml theme={null}
# 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` 完整範例。

```json theme={null}
{
    "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
}
```

## 版本升級因應 Checklist

<AccordionGroup>
  <Accordion title="Laravel 新版本發布前">
    * [ ] 以開發版（`dev-master` / `@dev`）進行運作確認
    * [ ] 以官方升級指南確認破壞性變更
    * [ ] 於測試環境實作對新版本的因應
    * [ ] 於測試 matrix 中加入新版本並於 CI 確認
  </Accordion>

  <Accordion title="Release 後的初期因應">
    * [ ] 於 `composer.json` 的 `illuminate/*` 要求加入新版本
    * [ ] 視需要更新 PHP 要求
    * [ ] `require-dev` 的 `orchestra/testbench` 也更新為對應版本
    * [ ] 為新版本打 tag 並反映至 Packagist
    * [ ] 更新 README 的版本相容性表格
  </Accordion>

  <Accordion title="終止舊版本支援時">
    * [ ] 於 CHANGELOG/README 明確標示支援終止
    * [ ] 從 `composer.json` 刪除舊版本的約束
    * [ ] 從測試 matrix 移除舊版本
    * [ ] 整理舊版本用的條件分支程式碼
  </Accordion>
</AccordionGroup>

## 相關頁面

<Columns cols={2}>
  <Card title="套件開發基礎" icon="box" href="/zh-TW/advanced/package-development">
    說明以服務提供者為核心的 Laravel 套件開發方式。
  </Card>

  <Card title="使用 Pest 進行進階測試" icon="flask-conical" href="/zh-TW/advanced/testing-pest">
    說明使用 Pest 的 Expectation API 與 dataset 撰寫套件測試的方式。
  </Card>
</Columns>


## Related topics

- [套件的 CHANGELOG 與發布管理](/zh-TW/advanced/package-changelog.md)
- [以 Orchestra Testbench 測試 Laravel 套件](/zh-TW/advanced/package-testing.md)
- [GitHub Actions 的 Pinning 與安全性](/zh-TW/advanced/github-actions-pinning.md)
- [延遲服務提供者](/zh-TW/advanced/deferred-provider.md)
- [以 Testbench Workbench 推進套件開發](/zh-TW/advanced/package-workbench.md)