Sử dụng cơ bản

Trang này hướng dẫn các thành phần cơ bản của mọi tài liệu TCPDF-Next: tạo document, thêm trang, viết văn bản, nhúng hình ảnh và tạo output.

Tạo Document

Factory method Document::create() là điểm bắt đầu duy nhất cho mọi PDF:

use Yeeefang\TcpdfNext\Core\Document;

$doc = Document::create();

Tất cả tham số đều tùy chọn — mặc định cho bạn document A4 dọc tính bằng milimet. Xem trang Cấu hình để biết danh sách đầy đủ.

Thêm trang

Document bắt đầu trống. Gọi addPage() ít nhất một lần trước khi viết nội dung:

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

// Thêm trang với thiết lập mặc định
$doc->addPage();

// Thêm trang Letter ngang với margin tùy chỉnh
$doc->addPage(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Kích thước trang có sẵn

PageSize là backed enum bao gồm tất cả kích thước ISO và Bắc Mỹ:

Giá trị Enum	Kích thước
PageSize::A3	297 × 420 mm
PageSize::A4	210 × 297 mm
PageSize::A5	148 × 210 mm
PageSize::Letter	215.9 × 279.4 mm
PageSize::Legal	215.9 × 355.6 mm

Kích thước tùy chỉnh được hỗ trợ qua PageSize::custom(width, height).

Đặt Font

TCPDF-Next đi kèm font PDF base chuẩn và họ font Unicode DejaVu Sans.

// Font base có sẵn
$doc->setFont('Helvetica', size: 12);

// Font Unicode có sẵn
$doc->setFont('DejaVuSans', size: 10);

// Biến thể Bold / Italic
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 14);
$doc->setFont('Helvetica', style: FontStyle::BoldItalic, size: 14);

Font tùy chỉnh

Đăng ký font TrueType hoặc OpenType, rồi dùng bằng alias:

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);

Xuất văn bản

TCPDF-Next cung cấp bốn method để đặt văn bản lên trang. Mỗi method phục vụ nhu cầu layout khác nhau.

cell()

In cell một dòng. Phù hợp cho label, ô bảng và văn bản ngắn:

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

multiCell()

In văn bản tự động xuống dòng trong chiều rộng cho trước. Con trỏ di chuyển xuống sau mỗi lần gọi:

$doc->multiCell(
    width: 0,        // 0 = toàn bộ chiều rộng có sẵn
    height: 7,
    text: 'Đây là đoạn văn dài sẽ tự động xuống dòng '
        . 'dựa trên chiều rộng có sẵn và kích thước font hiện tại.',
);

text()

Đặt văn bản tại vị trí (x, y) tuyệt đối. Không di chuyển con trỏ:

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

write()

Viết văn bản inline tại vị trí con trỏ hiện tại. Hỗ trợ link và chảy tự nhiên trong đoạn văn:

$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.');

Hình ảnh

Từ đường dẫn file

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

Từ chuỗi hoặc resource

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

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

Định dạng hỗ trợ: PNG, JPEG, GIF, SVG, WebP.

Lưu và xuất

TCPDF-Next cung cấp nhiều cách để lấy PDF cuối cùng.

Lưu ra đĩa

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

Gửi đến trình duyệt

use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

// Hiển thị inline (Content-Disposition: inline)
$doc->output('invoice.pdf', OutputDestination::Inline);

// Buộc tải về (Content-Disposition: attachment)
$doc->output('invoice.pdf', OutputDestination::Download);

Lấy dữ liệu PDF thô

$pdfBytes = $doc->getPdfData();

// Dùng với PSR-7 response, queue job, upload S3, v.v.

Enum OutputDestination

Giá trị	Hành vi
OutputDestination::Inline	Gửi đến trình duyệt để xem inline
OutputDestination::Download	Gửi đến trình duyệt dạng tải file
OutputDestination::File	Ghi ra file (dùng nội bộ bởi save())
OutputDestination::String	Trả về chuỗi binary thô (dùng nội bộ bởi getPdfData())

API Fluent

Hầu hết setter trả về $this, cho phép viết kiểu chuỗi:

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');

Ví dụ đầy đủ

Kết hợp tất cả lại:

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();

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

// Body
$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.',
);

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

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

Bước tiếp theo

• Cấu hình — tinh chỉnh mặc định, mã hóa và trợ năng.
• Cấu hình — hiểu cách Core, Pro và Artisan kết hợp nhau.
• FAQ — câu hỏi thường gặp.