安装 NextPDF 并渲染你的第一个 PDF

NextPDF 是一个用于创建 PDF（可移植文档格式，Portable Document Format）文件的 PHP 库。 在本教程中，你会把它安装到一个空文件夹里，并渲染你的第一个单页文档。你需要一个终端，以及大约十分钟时间。

你将构建什么

你将构建一个只包含一个脚本 01-hello.php 的小项目。 该脚本会渲染出一页内容，包含一行加粗标题和一个段落。 它会把结果保存为 out/hello.pdf。在这个过程中，你会学到两条用于确认安装是否正常的命令。

本页只介绍一条安装路径：一个空文件夹加上引擎包。 此外还有其他路径，比如框架适配器、基于浏览器的渲染器，以及 Python 客户端。这些内容在安装 和选择你的路径中介绍。今天你还用不到它们。

第 1 步：创建项目并安装 NextPDF

Composer 是 PHP 的包管理器。它会把库下载到你的项目中，并生成一个自动加载器（autoloader）。自动加载器是一个很小的 PHP 文件，它会替你找到库中的类，这样你就再也不必写一长串的 include。

打开一个终端，运行下面这三条命令：

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

在解析和下载包的过程中，Composer 会打印进度信息。具体输出的内容会因你的 Composer 版本和本地缓存而异。一次成功的安装不会出现报错信息，大致如下所示：

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

刚刚发生了什么

Composer 在你的文件夹里创建了三样东西。composer.json 记录了你的项目对该引擎的依赖。composer.lock 会锁定它所安装的确切版本， 这样以后再次安装时会解析出相同的代码。vendor/ 文件夹存放下载下来的包，其中包括 vendor/autoload.php。你的脚本只需加载这一个文件，所有引擎类就都可用了。

在安装期间，Composer 还检查了你的 PHP 配置。引擎会声明它所需要的 PHP 扩展。扩展是内建于 PHP 的可选模块。 如果缺少某个扩展，Composer 会停下来并指出它的名字，而不是留给你一个损坏的安装。

第 2 步：渲染你的第一个 PDF

在 composer.json 旁边创建一个名为 01-hello.php 的文件。 把下面这段完整的程序粘贴进去：

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

运行它：

php 01-hello.php

你应该只会看到一行输出：

Wrote out/hello.pdf

用任意 PDF 阅读器打开 out/hello.pdf。你会看到加粗的标题行， 下面是那个段落；大多数阅读器还会在窗口标题里显示 “Hello from NextPDF”。

刚刚发生了什么

从上到下逐句看这段脚本：

• require 加载 Composer 自动加载器，于是 Document 类得以解析。
• @mkdir 创建 out/ 文件夹。开头的 @ 会在文件夹已经存在时抑制报错， 这样你就可以反复运行它。
• Document::createStandalone() 返回一个全新的文档。它正是为这样简短的命令行脚本而设计的。
• setTitle() 设置文档标题，阅读器会把它显示在窗口标题里。
• addPage() 添加一个空白页，并把光标放在左上角。
• setFont() 选择一个字体族、一种样式，以及一个以磅（point）为单位的字号。磅是印刷中字号的标准单位。'B' 表示加粗，'' 表示常规。名为 helvetica 的字体族是内建的，因此你不需要任何字体文件。
• cell() 在光标处写入一行文本。宽度为 0 表示 “拉伸到右边距”。newLine: true 会在之后把光标向下移动， 就像按下回车键一样。
• save() 生成最终的 PDF 并把它写入磁盘。

一个文档产出一个文件。当你需要第二个 PDF 时，请创建一个全新的文档，而不是复用旧的那个。

第 3 步：验证你的安装

两项快速检查可以确认这套安装在这一个脚本之外也能持续正常工作。

首先，列出你的 PHP 所带的扩展：

php -m

在列表中查找 curl、gd、intl、mbstring、openssl 和 zlib。 引擎依赖这六个扩展。Composer 已在第 1 步检查过它们，因此它们应该都会出现。

其次，运行引擎自带的健康检查：

vendor/bin/nextpdf doctor

在 Windows 上，请改为调用 vendor\bin\nextpdf doctor。该命令会检查你的 PHP 版本、扩展、临时文件夹以及配置。每一项检查都会打印 [OK]、[WARN] 或 [FAIL]，最后给出一个总体结论。

刚刚发生了什么

先看 Extensions 这一块。curl、gd、 intl、mbstring、openssl 和 zlib 这六行都显示 [OK]，就意味着你的安装已经为后续的每一篇教程做好了准备。

报告还会列出引擎的各项能力。在免费的 Core 安装上，那些属于商业包的能力会打印 [FAIL]，并附带一条消息， 说明由哪个包提供这些能力。这是预期之内的；即便你的 Core 安装本身没有问题，它也可能把总体结论变成 UNHEALTHY。对这些教程而言，Extensions 这一块才是真正重要的信号。

如果出了问题

先把你遇到的现象和下面这些常见情况对照一下：

• composer: command not found 表示 Composer 缺失，或者不在你的 PATH 上。请从 getcomposer.org 安装它，然后重复第 1 步。
• Failed opening required '.../vendor/autoload.php' 表示脚本是在项目文件夹之外运行的，或者安装没有完成。请切换到第 1 步中的那个文件夹，并运行 composer install。
• 如果 Composer 在第 1 步中停下来并指出某个缺失的 PHP 扩展，请在你的 php.ini 中启用该扩展。用 php -m 确认后，再重复安装。
• doctor 的 Extensions 块中出现的 [FAIL] 行会指出某个缺失的 PHP 扩展。请在 php.ini 中启用它，用 php -m 确认，然后再次运行 doctor。那些指向商业包的能力 [FAIL] 行在 Core 安装上是预期之内的，这里无需处理。

至于其他情况，请从 疑难解答知识库开始。如果某个脚本抛出了异常，请到错误参考中查找它的类； 大多数新手错误都出现在 通用错误之下。

下一步

你已经拥有一套可用的安装，以及你渲染出的第一个文件。继续阅读 文本、字体与页面基础， 来控制页面尺寸、内建字体、颜色和对齐方式。