PHP 版本支援¶
nextpdf/backport 以雙分支模型支援兩個舊版 PHP 執行環境。每個分支獨立維護,對應不同的目標 PHP 版本,均通過完整測試套件驗證。
雙分支模型¶
GitHub Repository: nextpdf-labs/backport
├── PHP81(預設分支)— 目標:PHP 8.1.x
│ ├── composer.json (platform: {"php": "^8.1"})
│ ├── src/ (PHP 8.1 相容原始碼)
│ ├── tests/ (PHP 8.1 測試套件)
│ └── rector.php (PHP 8.1 降版規則)
│
└── PHP74 — 目標:PHP 7.4.x
├── composer.json (platform: {"php": "^7.4"})
├── src/ (PHP 7.4 相容原始碼)
├── tests/ (PHP 7.4 測試套件)
└── rector.php (PHP 7.4 降版規則)
重要:Backport 倉庫沒有 main 分支。PHP81 是 GitHub 預設分支。兩個分支均為受保護分支,變更需透過 PR 流程。
PHP 版本矩陣¶
| PHP 版本 | 支援分支 | 最低子版本 | 必要擴充套件 | 狀態 |
|---|---|---|---|---|
| PHP 8.5 | Core(非 Backport) | 8.5.0 | intl, mbstring, gd/imagick | 主要開發版本 |
| PHP 8.4 | — | — | — | 使用 Core 直接支援 |
| PHP 8.3 | — | — | — | 使用 Core 直接支援 |
| PHP 8.2 | — | — | — | 使用 Core 直接支援 |
| PHP 8.1 | PHP81 分支 | 8.1.0 | intl, mbstring, gd/imagick | 積極維護 |
| PHP 8.0 | — | — | — | 不支援(enum 需 8.1+) |
| PHP 7.4 | PHP74 分支 | 7.4.0 | intl, mbstring, gd/imagick, json | 積極維護(LTS) |
| PHP 7.3 以下 | — | — | — | 不支援 |
PHP 8.1 分支(PHP81)¶
PHP81 分支的目標是最大化與 Core API 的相容性,同時移除所有 PHP 8.2+ 的語法。
PHP 8.1 可用特性¶
// PHP 8.1 Enum(Core 使用 Enum,此處保留)
enum Orientation: string {
case Portrait = 'portrait';
case Landscape = 'landscape';
}
// PHP 8.1 readonly 屬性(單一屬性,非 readonly 類別)
final class PageSize
{
public function __construct(
public readonly float $width,
public readonly float $height,
) {}
}
// PHP 8.0 Named arguments(保留)
$config = Configuration::create(pageSize: PageSize::A4, margin: Margin::uniform(15.0));
// PHP 8.0 Match 表達式(保留)
$label = match($orientation) {
Orientation::Portrait => 'P',
Orientation::Landscape => 'L',
};
PHP 8.1 降版的轉換¶
// PHP 8.5 原始碼(Core)
final class RenderingContext
{
public int $currentPage { get; private set; } // 非對稱存取修飾
// ...
}
// PHP 8.1 降版結果(Backport PHP81 分支)
final class RenderingContext
{
private int $currentPage = 0;
public function getCurrentPage(): int // 自動生成的 getter
{
return $this->currentPage;
}
// ...
}
PHP 7.4 分支(PHP74)¶
PHP74 分支需要更多轉換,因為它還需要處理 PHP 8.0 和 8.1 的特性:
PHP 7.4 額外降版處理¶
// PHP 8.1 Enum → PHP 7.4 抽象類別 + 常數(EnumToClassRector)
abstract class Orientation
{
public const PORTRAIT = 'portrait';
public const LANDSCAPE = 'landscape';
/** @var string */
private string $value;
private function __construct(string $value) { $this->value = $value; }
public static function Portrait(): self { return new self(self::PORTRAIT); }
public static function Landscape(): self { return new self(self::LANDSCAPE); }
public function value(): string { return $this->value; }
}
// PHP 8.0 Named arguments → 位置式參數(NamedArgumentToPositionalRector)
// 原始:Configuration::create(pageSize: PageSize::A4, margin: Margin::uniform(15.0))
// 降版:Configuration::create(PageSize::A4, Margin::uniform(15.0))
CI 測試矩陣¶
每次推送到 PHP81 或 PHP74 分支時,CI 在對應 PHP 版本上執行完整測試套件:
| 分支 | PHP 版本 | 測試套件 | 覆蓋率 |
|---|---|---|---|
PHP81 | 8.1, 8.2, 8.3 | Unit(無 Integration) | PHPStan Level 9 |
PHP74 | 7.4, 8.0, 8.1 | Unit(無 Integration) | PHPStan Level 9 |
為何 PHPStan Level 9 而非 10? PHP 7.4 不支援
readonly的 PHPStan 嚴格檢查,因此 Backport 使用 Level 9 以避免誤報。
擴充套件需求¶
| 擴充套件 | PHP 8.1 | PHP 7.4 | 說明 |
|---|---|---|---|
ext-intl | 必要 | 必要 | Unicode、雙向文字、ICU |
ext-mbstring | 必要 | 必要 | 多位元組字串處理 |
ext-gd | 必要(二選一) | 必要(二選一) | 基本影像處理 |
ext-imagick | 必要(二選一) | 必要(二選一) | 進階影像處理 |
ext-json | 捆綁 | 需明確啟用 | JSON 序列化 |
ext-openssl | 必要 | 必要 | 加密功能 |
ext-zlib | 建議 | 建議 | FlateDecode 壓縮加速 |
ext-ffi | 不適用 | 不適用 | Backport 不支援 Spectrum FFI |
參見¶
- Backport 套件總覽 — 套件架構與限制說明
- Rector 規則 — 三條自訂降版規則的技術實作