你的第一份 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 指令稿的環境。

確認 PHP 8.4 是目前啟用的執行環境：
Terminal window
```
php --version
```
若專案中尚未安裝核心引擎，請先安裝：
Terminal window
```
composer require nextpdf/core
```
在專案根目錄建立一個工作檔案，命名為 first-pdf.php。

從 PHP 產生 PDF

先從流暢 API 開始。Document::createStandalone() 會回傳一份可直接使用的文件。你加入一頁、設定字型、寫入儲存格，然後存檔。每個編寫方法都會回傳該文件，因此這些呼叫可以由上而下依序閱讀。

把這段程式碼放進 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";

執行這支指令稿：
Terminal window
```
php first-pdf.php
```
確認輸出結果。標準輸出應該會出現這一行，指令稿旁也會出現一個名為 first-pdf.pdf 的新檔案：
```
Wrote first-pdf.pdf
```

你現在已經產生了一份有效的 PDF 2.0 檔案。用任何檢視器開啟它，就會看到那個標題，以及下方的那一行文字。

把 HTML 算繪成 PDF

寫入儲存格能給你精確的控制。不過，大多數文件用 HTML 與 CSS 表達會更快。核心引擎內建一條純 PHP 的 HTML 管線。它的 writeHtml() 方法會把一段片段算繪到目前的頁面。它不使用瀏覽器，也不依賴任何外部服務。

建立第二個檔案 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";

執行這支指令稿：
Terminal window
```
php html-pdf.php
```
確認輸出中的那一行以及新檔案：
```
Wrote html-pdf.pdf
```

引擎只會算繪 HTML 與 CSS 的受支援子集。在你依賴某個屬性之前，請先對照 CSS 支援對照表檢查它。當版面需要完整的瀏覽器一致性時，例如 flexbox、grid 或網頁字型，請安裝 Artisan renderer（渲染器），並改呼叫 writeHtmlChrome()。該方法會保留文字的可選取性。

從 Framework 控制器產生

你的應用程式可能已經在某個框架上執行，或是以 server 形式運作。同樣那兩個呼叫可以搬進該環境。引擎維持不變，只有接線方式改變。

每次呼叫這個 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 快速入門。

這個套件對外提供一個 PdfFactory 服務。在控制器中透過型別提示注入 NextPDF\Symfony\Service\PdfFactory，以同樣方式建構文件，再將它作為 HTTP 回應傳回。請參閱 Symfony 快速入門。

當 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，涵蓋樣式、表格、分頁等更多主題。