HTML sang PDF, con đường dễ dàng

Cho đến giờ trong lộ trình này, bạn đã xây dựng các trang theo từng lệnh gọi một. Nhiều tài liệu lại được mô tả nhanh hơn dưới dạng markup, định dạng văn bản dựa trên thẻ được dùng cho các trang web. Trong hướng dẫn này, bạn đưa cho NextPDF một chút ngôn ngữ đánh dấu siêu văn bản (HTML), và engine sẽ vẽ trang cho bạn.

Những gì bạn sẽ xây dựng

Một báo cáo một trang được kết xuất từ một chuỗi HTML duy nhất. Nó gồm một tiêu đề có màu, một đoạn văn ngắn và một bảng có một hàng tổng cộng. Bạn định kiểu cho nó bằng bảng định kiểu xếp tầng (CSS), ngôn ngữ gồm các quy tắc điều khiển cách markup hiển thị. Trong các hướng dẫn trước, bạn đã dùng giao diện lập trình ứng dụng (API) fluent, tức các lệnh gọi phương thức được xâu chuỗi. Còn ở đây, bạn mô tả bố cục bằng markup, và cùng một engine sẽ kết xuất nó.

Bước 1: Kết xuất một báo cáo có định dạng từ HTML

Tạo một tệp tên là 01-html.php trong thư mục dự án của bạn, bên cạnh vendor. Dán đoạn script hoàn chỉnh này vào:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

Chạy script từ thư mục dự án:

php 01-html.php

Bạn sẽ thấy một dòng kết quả:

Wrote out/reading-report.pdf

Mở out/reading-report.pdf trong bất kỳ trình xem định dạng tài liệu di động (PDF) nào. Tiêu đề có màu xanh dương đậm, và hàng đầu đề của bảng được tô cùng màu.

Chuyện gì vừa xảy ra

@mkdir(__DIR__ . '/out'); tạo thư mục đầu ra. Dấu @ ẩn cảnh báo khi thư mục đã tồn tại, để những lần chạy lặp lại vẫn im lặng.
Document::createStandalone(), setTitle() và addPage() hoạt động chính xác như trong các hướng dẫn trước. Việc chuyển sang markup không thay đổi gì trong cách thiết lập tài liệu.
writeHtml() đọc chuỗi của bạn một lần, từ trên xuống dưới, và vẽ từng phần tử tại vị trí hiện tại. Các tiêu đề và đoạn văn trở thành văn bản có định dạng. Bảng trở thành các hàng được đo kích thước với các ô có viền.
Các thuộc tính style nội tuyến mang theo CSS. Engine hiểu các thuộc tính phổ biến như color, background-color, text-align và width.
Không có trình duyệt nào và không có phần mềm bổ sung nào tham gia. Pipeline là PHP thuần bên trong engine, vì vậy script chạy ở bất cứ đâu mà bản cài đặt Composer của bạn chạy được.

Engine hỗ trợ một tập con thiết thực của HTML và CSS, không phải mọi thứ mà trình duyệt chấp nhận. Bất kỳ thứ gì nằm ngoài tập con đó đều được bỏ qua một cách âm thầm thay vì phát sinh lỗi. Ma trận hỗ trợ CSS ghi lại chính xác những gì được hỗ trợ. Để tìm hiểu sâu hơn về pipeline này, xem Kết xuất HTML thành một trang PDF.

Khi nào dùng HTML và khi nào dùng API fluent

Cả hai con đường đều chạy trên cùng một engine, vì vậy hãy chọn con đường nào phù hợp với tài liệu.

Chọn writeHtml() khi tài liệu trông giống như một trang web: tiêu đề, đoạn văn, danh sách và bảng. Markup viết nhanh hơn và dễ chỉnh sửa hơn cho các đồng đội.
Chọn API fluent khi bạn cần đặt vị trí chính xác, chẳng hạn như các vị trí cố định hoặc các ô được đo chính xác. Markup mang lại cho bạn dòng chảy; các lệnh gọi fluent mang lại cho bạn sự kiểm soát.
Hãy kiểm tra ma trận hỗ trợ CSS trước khi dựa vào một thuộc tính. Khi một kiểu định dạng không được hỗ trợ, hãy xây dựng phần đó bằng các lệnh gọi fluent để thay thế.

Ranh giới an toàn

HTML thực tế thường đến từ bên ngoài mã của bạn, ví dụ từ một biểu mẫu hoặc một cơ sở dữ liệu. Hãy coi nó là dữ liệu đầu vào không đáng tin cậy và xác thực hoặc làm sạch nó trước khi kết xuất. Theo mặc định, pipeline tích hợp sẵn không chạy script nào và không tải về tài nguyên từ xa nào. Mặc định đó giữ cho bộ kết xuất thận trọng ngay cả khi markup thì không. Nếu bạn cần các tùy chọn kết xuất ở cấp độ trình duyệt, xem Chọn con đường của bạn.

Nếu có gì đó không ổn

Failed to open stream: No such file or directory thường có nghĩa là script không thể tìm thấy vendor/autoload.php. Hãy chạy nó từ thư mục nơi bạn đã chạy Composer.
Một kiểu định dạng bị thiếu thường là một thuộc tính nằm ngoài tập con được hỗ trợ. Engine bỏ qua những gì nó không hỗ trợ thay vì thất bại. Hãy so sánh markup của bạn với ma trận hỗ trợ CSS.
Một exception trong khi kết xuất sẽ nêu tên vấn đề chính xác. Hãy tra cứu nó trong tài liệu tham khảo lỗi kết xuất và nhập/xuất.

Đối với bất kỳ điều gì khác, hãy bắt đầu với hướng dẫn khắc phục sự cố.

Giờ bạn có thể xây dựng tài liệu theo từng lệnh gọi và từ markup. Hãy hoàn thành lộ trình với Đi đâu tiếp theo. Nó phác họa cookbook, tài liệu tham khảo và các hướng dẫn mà bạn sẽ dùng sau lộ trình này.