基本用法

本頁將逐步介紹 TCPDF-Next 文件的基本構成要素：建立文件、新增頁面、輸出文字、嵌入圖片，以及產生最終的 PDF。

建立文件

Document::create() 靜態工廠方法是建立 PDF 的唯一進入點：

use Yeeefang\TcpdfNext\Core\Document;

$doc = Document::create();

所有參數皆為選用——預設會建立一份以公釐為單位的 A4 直式文件。完整參數列表請參閱設定頁面。

新增頁面

文件建立後不含任何頁面。在輸出內容之前，至少需呼叫一次 addPage()：

use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// 使用文件預設值新增頁面
$doc->addPage();

// 新增橫式 Letter 頁面，搭配自訂邊界
$doc->addPage(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

頁面尺寸

PageSize 是一個列舉，涵蓋所有標準 ISO 與北美尺寸：

列舉值	尺寸
PageSize::A3	297 x 420 mm
PageSize::A4	210 x 297 mm
PageSize::A5	148 x 210 mm
PageSize::Letter	215.9 x 279.4 mm
PageSize::Legal	215.9 x 355.6 mm

亦可透過 PageSize::custom(width, height) 指定自訂尺寸。

設定字型

TCPDF-Next 內建標準 PDF 基本字型，以及支援 Unicode 的 DejaVu Sans 字型家族。

// 內建基本字型
$doc->setFont('Helvetica', size: 12);

// 內建 Unicode 字型
$doc->setFont('DejaVuSans', size: 10);

// 粗體 / 斜體變體
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 14);
$doc->setFont('Helvetica', style: FontStyle::BoldItalic, size: 14);

自訂字型

註冊 TrueType 或 OpenType 字型後，即可透過別名使用：

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    $config->addFont('/fonts/Inter-Regular.ttf', alias: 'Inter');
});

$doc->setFont('Inter', size: 11);

文字輸出

TCPDF-Next 提供四種方法將文字放置到頁面上，各自適用於不同的排版需求。

cell()

印出單行儲存格。適合標籤、表格儲存格與短文字：

$doc->cell(
    width: 80,
    height: 10,
    text: 'Invoice #1042',
    border: true,
    align: Align::Center,
);

multiCell()

印出會自動換行的文字區塊，依指定寬度排列。每次呼叫後游標會自動往下移動：

$doc->multiCell(
    width: 0,        // 0 = 使用全部可用寬度
    height: 7,
    text: 'This is a longer paragraph that will wrap across multiple lines '
        . 'based on the available width and the current font size.',
);

text()

在絕對座標 (x, y) 位置放置文字。不會移動游標：

$doc->text(x: 105, y: 20, text: 'Centered Title', align: Align::Center);

write()

在目前游標位置寫入行內文字。支援超連結，適合在段落中自然串接：

$doc->write(height: 5, text: 'Visit the ');
$doc->write(height: 5, text: 'TCPDF-Next docs', link: 'https://tcpdf-next.dev');
$doc->write(height: 5, text: ' for more information.');

圖片

從檔案路徑載入

$doc->imageFromFile(
    path: '/images/logo.png',
    x: 15,
    y: 15,
    width: 40,
);

從字串或資源載入

$binary = file_get_contents('https://example.com/photo.jpg');

$doc->image(
    data: $binary,
    x: 15,
    y: 60,
    width: 50,
    type: 'JPEG',
);

支援格式：PNG、JPEG、GIF、SVG、WebP。

儲存與輸出

TCPDF-Next 提供多種方式取得最終的 PDF。

儲存至磁碟

$doc->save('/reports/invoice-1042.pdf');

傳送至瀏覽器

use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

// 在瀏覽器中直接顯示（Content-Disposition: inline）
$doc->output('invoice.pdf', OutputDestination::Inline);

// 強制下載（Content-Disposition: attachment）
$doc->output('invoice.pdf', OutputDestination::Download);

取得原始 PDF 資料

$pdfBytes = $doc->getPdfData();

// 可搭配 PSR-7 回應、佇列任務、S3 上傳等使用

OutputDestination 列舉

值	行為
OutputDestination::Inline	傳送至瀏覽器，以內嵌方式檢視
OutputDestination::Download	傳送至瀏覽器，以檔案下載方式處理
OutputDestination::File	寫入指定檔案路徑（save() 內部使用）
OutputDestination::String	回傳原始二進位字串（getPdfData() 內部使用）

鏈式 API

大多數 setter 方法皆回傳 $this，支援流暢的鏈式呼叫風格：

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;

$pdf = Document::create()
    ->setTitle('Monthly Report')
    ->setAuthor('Acme Corp')
    ->addPage(pageSize: PageSize::A4, orientation: Orientation::Portrait)
    ->setFont('Helvetica', style: FontStyle::Bold, size: 18)
    ->cell(width: 0, height: 15, text: 'Monthly Report — February 2026', align: Align::Center)
    ->ln()
    ->setFont('Helvetica', size: 11)
    ->multiCell(width: 0, height: 6, text: 'This report summarises key metrics...')
    ->save('/reports/monthly.pdf');

完整範例

將以上所有概念整合在一起：

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;
use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

$doc = Document::create();

$doc->setTitle('Hello World');
$doc->setAuthor('TCPDF-Next');

$doc->addPage();

// 標題
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 20);
$doc->cell(width: 0, height: 15, text: 'Hello, TCPDF-Next!', align: Align::Center);
$doc->ln(20);

// 內文
$doc->setFont('DejaVuSans', size: 12);
$doc->multiCell(
    width: 0,
    height: 7,
    text: 'TCPDF-Next is a modern, type-safe PDF generation library for PHP 8.5+. '
        . 'It provides a clean API, strict static analysis, and comprehensive Unicode support.',
);

// 商標圖片
$doc->imageFromFile(path: __DIR__ . '/logo.png', x: 15, y: 80, width: 30);

// 輸出
$doc->output('hello.pdf', OutputDestination::Download);

下一步

• 設定 — 微調預設值、加密與無障礙設定。
• 設定 — 了解 Core、Pro 與 Artisan 的模組關係。
• 常見問題 — 常見疑問與解答。