你的第一份 PDF

概览

在本教程中，你会生成两份 PDF 文件。第一份文件会用流畅的核心应用程序接口（Application Programming Interface，API）直接写入文本。第二份则把一段以 markup（标记语言）写成的 HTML（HyperText Markup Language）内容，连同层叠样式表（Cascading Style Sheets，CSS）一起渲染成一页。完成后，你会得到一个可运行的脚本，并能将它改写成实际文档。你也会了解 Framework（框架）变体与 server（服务器）变体各自的位置。

这两种做法都运行在同一套引擎上。因此，你在这里学到的内容都能沿用到每一种发行版本。

下方图表展示了这两种编写做法，以及可以复用它们的三个部署面。

From your code to a PDF file

开始之前

你需要两样东西：已安装的核心引擎，以及一个能运行 PHP 脚本的环境。

1. 确认 PHP 8.4 是当前生效的运行环境：

   php --version

2. 若项目中尚未安装核心引擎，请先安装：

   composer require nextpdf/core

3. 在项目根目录创建一个工作文件，命名为 first-pdf.php。

标准 14 种字体无需设置即可使用

默认的正文字体会 resolve（解析）为 ISO 32000-2 所列标准 14 种 Type 1 字体中的一种。因此，你的第一份文档不需要任何字体文件。等到设计有需要时，再注册并嵌入自定义字体。

从 PHP 生成 PDF

先从流畅 API 开始。Document::createStandalone() 会返回一份可直接使用的文档。你加上一页、设置字体、写入单元格，然后保存。每个编写方法都会返回该文档，因此这些调用从上到下顺序阅读即可。

1. 把这段代码放进 first-pdf.php。这个脚本声明严格类型、加载自动加载器，并构建一份单页文档：

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. 运行这个脚本：

   php first-pdf.php

3. 确认输出结果。你应该会在标准输出中看到这一行，并在脚本旁边看到一个名为 first-pdf.pdf 的新文件：

   Wrote first-pdf.pdf

现在你已经生成了一份有效的 PDF 2.0 文件。用任意查看器打开它，就会看到那个标题以及下方那一行文本。

save 与 output 的区别

save() 会把文档写入指定文件路径。若要改成把字节流式传输到浏览器，请调用 output()。若要把字节捕获到内存中，请调用 getPdfData()。文档是一次性使用的——写出一份之后，下一份文档请创建全新的实例，不要复用原本那份。

把 HTML 渲染成 PDF

写入单元格能给你精确的控制。不过，大多数文档用 HTML 与 CSS 表达会更快。核心引擎内含一条纯 PHP 的 HTML 管线。它的 writeHtml() 方法会把一段片段渲染到当前页面。它不使用浏览器，也不依赖任何外部服务。

1. 创建第二个文件 html-pdf.php，用于渲染一段 HTML 片段：

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. 运行它：

   php html-pdf.php

3. 确认输出那一行以及新文件：

   Wrote html-pdf.pdf

把 HTML 输入视为不可信

当 HTML 来自用户、表单或任何外部来源时，你必须先验证并净化它，才能传给 writeHtml()。把 HTML 渲染成 PDF 页面这篇 recipe（示例）涵盖完整的安全防护态势与流式传输模型。

引擎只渲染 HTML 与 CSS 的一个受支持子集。在依赖某个属性之前，请先对照 CSS 支持对照表检查它。当版面需要完整的浏览器一致性时——例如 flexbox、grid 或网页字体——请安装 Artisan renderer（渲染器），并改为调用 writeHtmlChrome()。该方法会让文本保持可选取。

从 Framework 控制器生成

你的应用程序可能已经运行在某个框架中，或是以 server 形式运行。同样那两个调用可以搬进相应环境里。引擎保持不变，只有接线方式改变。

Laravel

这个 Pdf facade 会在每次调用时解析出一份全新的文档。PdfResponse 会把一份文档转成下载响应：

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

请参阅 Laravel 快速入门。

Symfony

这个 bundle 对外提供一个 PdfFactory 服务。在控制器中以类型提示注入 NextPDF\Symfony\Service\PdfFactory，以同样方式构建文档，再把它当作 HTTP 响应返回。请参阅 Symfony 快速入门。

Server（服务器，REST）

在 NextPDF Server 运行的情况下，你 POST 一个有序的操作数组，服务器就会返回 PDF 字节：

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

当响应为 200 时，响应主体就是该 PDF。请参阅 Connect 快速入门。

后续步骤

你现在已经用三种方式生成了 PDF。以下是每一种方式接下来可以前往的方向。

把 HTML 渲染成 PDF 页面 完整的 HTML recipe：支持的元素、流式传输模型，以及安全防护态势。

选择你的路径 在核心、Framework、server 之间做出抉择，并决定要使用哪一种 HTML renderer。

核心引擎参考 每一个 Document 方法、参数与返回值。

Cookbook（示例指南） 以任务为核心的 recipe，涵盖样式、表格、分页等更多主题。