設定 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 會在之後把游標往下移， 就像按下 Enter 一樣。
• 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 區塊。六行 [OK]，分別名為 curl、gd、 intl、mbstring、openssl 與 zlib，代表您的安裝已為後續的每一篇教學做好準備。

報告也會列出引擎的各項能力。在免費的 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 安裝上屬於預期之內，此處無需採取任何行動。

至於其他任何情況，請從 疑難排解知識庫開始。若某段指令稿拋出例外，請在 錯誤參考中查閱它的類別；大多數新手會遇到的錯誤都收錄在一般錯誤之下。

下一步

您已擁有一個可運作的安裝，以及您第一份算繪出來的檔案。請接著閱讀 文字、字型與頁面基礎， 學會控制頁面大小、內建字型、色彩與對齊方式。