跳轉到

Backport — PHP 降版套件

NextPDF Backport

nextpdf/backport 讓 NextPDF Core 的使用者在 PHP 8.1 或 7.4 環境中也能使用 NextPDF 的完整功能。套件透過三條自訂 Rector 規則對 Core 的 PHP 8.5 語法進行 AST（抽象語法樹）降版轉換，生成的程式碼在目標 PHP 版本上行為完全一致。

重要：Backport 採用雙分支模型，PHP74 與 PHP81 是兩個永久並行的長效分支，對應不同的目標 PHP 版本。詳見 PHP 版本支援。

設計原則

Backport 使用靜態分析時期的轉換（非執行時 shim），確保：

  1. 零執行時成本：降版在部署前完成，不影響執行效能
  2. 型別安全保留：PHPDoc 型別標注在降版後完整保留
  3. 行為一致性：所有單元測試在 PHP 7.4、8.1、8.5 下通過

安裝

# PHP 8.1 目標環境
composer require nextpdf/backport:^1.0@php81

# PHP 7.4 目標環境
composer require nextpdf/backport:^1.0@php74

注意：nextpdf/backport 的 PHP81 與 PHP74 分支作為獨立版本發布，而非同一套件的不同 tag。請確認安裝符合目標 PHP 環境的版本。

快速開始

在 PHP 8.1 / 7.4 環境中，API 完全相同：

<?php
// PHP 7.4 / 8.1 相容程式碼（透過 nextpdf/backport）

declare(strict_types=1);

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->text('Hello from PHP 7.4!', x: 20, y: 30);
$document->save('/tmp/hello.pdf');

降版轉換範圍

Backport 處理 NextPDF Core 使用的以下 PHP 8.5 特性：

PHP 8.5 特性 降版目標 Rector 規則
public private(set) 非對稱存取修飾 private + getter 方法 AsymmetricVisibilityRector
readonly 類別（PHP 8.2+） readonly 屬性 + final 建構子 ReadonlyClassRector
Enum（PHP 8.1+）→ PHP 7.4 類別常數 + abstract 類別模擬 EnumToClassRector
array_is_list() 手動實作 polyfill 透過 symfony/polyfill-php81
Fiber（PHP 8.1+）→ PHP 7.4 非使用（Core 不用 Fiber） 不適用
Named arguments（PHP 8.0+）→ PHP 7.4 位置式參數 NamedArgumentToPositionalRector
Match 表達式（PHP 8.0+）→ PHP 7.4 switch / 三元運算子 透過 rector/rector 標準規則

執行降版轉換

# 從 nextpdf-backport 專案根目錄執行
composer run backport:php81    # 生成 PHP 8.1 相容版本
composer run backport:php74    # 生成 PHP 7.4 相容版本

降版流程：

  1. 從 nextpdf/core 取得最新原始碼
  2. 執行三條自訂 Rector 規則
  3. 執行標準 Rector PHP 7.4/8.1 降版規則集
  4. 執行 composer cs-fix 確保 PSR-12 合規
  5. 執行降版後測試套件（composer test）

分支模型

nextpdf (Core, PHP 8.5)
         │
         ├─▶ [Rector PHP 8.1 rules]
         │         └─▶ nextpdf-backport / PHP81 分支
         │
         └─▶ [Rector PHP 7.4 rules]
                   └─▶ nextpdf-backport / PHP74 分支

PHP74 與 PHP81 是永久長效分支，不合併至 main（Backport 倉庫無 main 分支）。詳見 PHP 版本支援。

限制

以下 NextPDF Core 功能在 Backport 中不可用：

功能 限制原因
Spectrum Rust FFI 加速器 FFI 需要 PHP 7.4+；Spectrum 使用 PHP 8.5 FFI 語法
#[Override] 屬性 PHP 8.3+，不降版（不影響功能，僅靜態分析）
非對稱存取修飾的完整語義 降版後為 private + getter，行為相容但 API 略有差異

參見