PHP 8.4 基础

Spec Spec: ISO 32000-2, §7.5.2 ISO 32000-2 §7.5.2 Evidence { } Code-backed Evidence: Code-backed PHP 限制 ≥8.4 <9.0 PHP 限制: ≥8.4 <9.0

概览

NextPDF 需要 PHP 8.4。本页说明引擎实际依赖哪些 8.4 语言特性、为什么该版本是硬性底线而不是一句委婉建议，以及一套独立的降版构建如何在不削弱你正在阅读的代码的前提下，保留在旧运行环境上运行的选项。

为何这很重要

一个 PDF 引擎要把含糊不清的输入转换成字节精确的文件格式。PDF 是一种历史悠久的格式，规则稳固、固定，而且严格到只要猜错一次，代价就很高。引擎所使用的编程语言，正是拦下这些猜测，或让它们未经检查就被放行的第一道关卡。版本底线并不是为了限制而限制。它是一条界线；一旦低于这条线，引擎就再也无法提供其余设计所依赖的类型保证。

如果这条底线含糊不清，就会带来两种代价。代码库会塞满掩盖真实逻辑的兼容性垫片（shim）。类型系统也会失去承载力，而这正是文档处理管线无法承受的损失。

简短版本

• 核心包声明了 "php": ">=8.4 <9.0"。这才是真正的限制，已在 composer.json 中验证，而不是文档里的期望。
• 8.4 之所以是底线，是因为引擎把 8.4（以及近期的 8.x）语言特性作为结构性保证来使用：非对称可见性、带行为的回溯枚举（backed enum）、具类型的类常量、readonly 状态，以及公开 API 中作为一等接口的具名参数。
• 通过一套独立的降版构建（即 backport），仍然可以在 PHP 8.1–8.3 上运行。它是构建工具，而不是运行期依赖包。它并不会改变你在核心仓库中读到的代码。
• 上界 <9.0 是刻意设定的：一个全新的 PHP 主版本被视为需要验证的对象，而非可以直接假设可用。

NextPDF 如何看待这件事

底线由代码实际做了什么来决定。因此，诚实的说明方式是展示这些特性在代码中的样子，而不是抽象地把它们列成清单。

非对称可见性让状态可以对外公开读取，却只能在内部私有写入，而不必为每个字段手写一个 getter。渲染上下文（rendering context）直接运用了它：

declare(strict_types=1);

final class RenderingContext
{
    // Readable everywhere, writable only inside the class.
    public private(set) float $x = 0.0;
    public private(set) float $y = 0.0;
    public private(set) int $currentPageIndex = -1;
    public private(set) string $currentContentStream = '';
}

仅这一项语言特性，就消除了一整类意外的外部变更。游标无法从引擎外部移动。这项保证由运行环境强制执行，而不是依赖审查者记住某条约定。

带行为的回溯枚举用一个既有类型、又能回答自身相关问题的值，取代了散落各处的布尔标志与字符串常量。文档符合性鉴别器就是一个回溯枚举，它的方法决定规范层级的结果：

declare(strict_types=1);

enum ConformanceMode: string
{
    case Plain  = 'plain';
    case PdfUa2 = 'pdfua2';
    case PdfA4  = 'pdfa4';
    case PdfA4f = 'pdfa4f';

    public function isTagged(): bool
    {
        return match ($this) {
            self::Plain => false,
            default     => true,
        };
    }

    /** @return 2|3|4|null */
    public function pdfaPart(): ?int
    {
        return match ($this) {
            self::PdfA4, self::PdfA4f => 4,
            default                   => null,
        };
    }
}

这个枚举是「这份文档是否经过规范标记？」以及「适用哪个 ISO 部分？」的单一事实来源。当这些问题用松散的布尔值来表达时，多个地方都可能给出不一致的答案。

具类型的类常量让连常量都成为类型契约的一部分。HTML 引擎的硬性上限就是以具类型常量声明的：

private const int MAX_NESTING_DEPTH = 100;
private const int MAX_ELEMENT_COUNT = 50_000;

具名参数是公开 API 接口的一部分，而不是内部的小技巧。示例程序会在供读者照抄的调用点传入它们：

$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);

这些都不是为了装饰而使用新语法。每一项都把原本需要审查者手动执行的约定，转换成运行环境会强制执行的特性。

证据怎么说

本页是 Evidence { } Code-backed Evidence: Code-backed 。上述每一项主张都对应核心仓库中的具体文件，而不是一份特性清单：

• 版本限制就是核心 composer.json 中的 require.php 值 ">=8.4 <9.0"。
• 非对称可见性的示例就是 src/Core/RenderingContext.php 中实际的声明风格（public private(set) 字段）。
• 枚举示例反映的是 src/Conformance/ConformanceMode.php，一个回溯 enum … : string，其基于 match 的方法驱动了符合性决策。
• 具类型的常量就是 src/Html/HtmlParser.php（private const int MAX_NESTING_DEPTH、MAX_ELEMENT_COUNT）。
• 具名参数的调用出自随附的 examples/ 程序。

这条底线也有标准层面的意义。引擎的工作是输出符合下列标准的文件： Spec Spec: ISO 32000-2, §7.5.2 ISO 32000-2 §7.5.2 。 一个符合规范的 PDF 2.0 写入器必须在文件头或目录（catalog）中，将文档版本声明为 2.0。当语言层面让写入器从一开始就难以构造出不一致状态时， 要履行这样精确的义务会容易许多。版本底线与格式的严格性是一致的。

实际示例

最小的正确程序已经用到了这条底线。它在 PHP 8.4 上运行，使用了一个具名参数，并生成一个符合规范的文件：

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->save(__DIR__ . '/hello.pdf');

这里没有任何特别之处。重点在于：那套让引擎内部值得信赖的严格类型、枚举与非对称可见性机制，在这段五行程序底下早已启用。你不需要主动选择加入。

常见的误解

最常见的误读，是把「需要 PHP 8.4」理解成「除非你升级到 8.4，否则无法运作」。它的意思是核心源代码以 8.4 为目标。对于被锁定在 PHP 8.1–8.3 的团队，另有一套独立的降版构建可用。

对那套构建究竟是什么，必须说清楚。它是一条以 Rector 为基础的降版管线，会把 8.4 源代码转换成较旧语法的输出。它是构建基础设施，而不是你加进应用程序依赖包中的运行期库。它并不会引入一份并行的、类型更弱的代码库。这些页面中所审视的代码，与实际出货的代码是同一份代码。backport 是套用于它的一道转换，而不是它的替代品。

Human-factors note: Human-factors note

本页刻意展示四段简短、真实的代码样貌，而不是一份冗长的语言特性散文清单。 相关概念被有意归成一组，并保持精简。 相比一份巨细靡遗的目录清单，一小组具体示例更容易记住，也更容易在日后辨识出来。 这与下列思路一致： 让引擎自身的类型接口保持精简而明确，而不是宽泛而隐晦。

限制与边界

本页说明 8.4 为何是底线，以及 backport 保留了什么。它并不记录如何运行降版管线、其支持的目标版本，或其操作注意事项。那些内容属于 backport 构建自己的文档。那套工具的内部包布局不在本页范围内。这里展示的特性用法只是说明引擎风格的例子。它们并不是代码库所使用的每一项 8.x 特性的完整清单。确切的 API 由参考文档定义，而不是由本说明定义。此版本限制在本页审阅日期当天是准确的。具权威性的值，始终是核心 composer.json 中的 require 区块。

版本对语言底线没有任何影响。每一个版本都是从同一份 PHP 8.4 源代码构建而成：

PHP 8.4 source floor — edition availability

Edition	Availability
Core	○ 核心是针对 PHP 8.4 编写的。
Pro	○ Pro 构建于同一条 8.4 源代码底线之上。
Enterprise	○ Enterprise 构建于同一条 8.4 源代码底线之上。

相关文档

• 处处皆严格类型 — 静态分析纪律如何把语言底线变成一项保证。
• 管线模型 — 那些语言特性共同支撑的架构。
• NextPDF 设计理念 — 为何引擎偏好明确、由运行环境强制的契约。

词汇表

• 版本底线 — 核心源代码所锁定的最低 PHP 版本（>=8.4）。低于它，引擎的类型保证就无法被表达。
• 非对称可见性 — 一项 PHP 8.4 特性，允许属性可对外公开读取、但只能从较窄的范围写入（public private(set)）。
• 回溯枚举 — 一个 PHP 枚举，其各个 case 带有标量值，并且可以承载行为（方法），在此用作单一的具类型事实来源。
• Backport — 一套独立、以 Rector 为基础的降版构建，会把 8.4 源代码转换成可在较旧 PHP 上运行的输出。它是构建工具，而非运行期依赖包。
• 符合性模式 — 引擎用以鉴别一份文档必须满足哪个 ISO 符合性契约的具类型鉴别器。