Package Artisan

Artisan · LGPL-3.0

Package Artisan (yeeefang/tcpdf-next-artisan) cung cấp chuyển đổi HTML sang PDF pixel-perfect được hỗ trợ bởi Chrome DevTools Protocol (CDP). Nó render HTML với hỗ trợ CSS3 đầy đủ — bao gồm Flexbox, Grid, web font, media query và animation đóng băng tại thời điểm render.

Khi nào dùng Artisan

Tình huống	Khuyên dùng
Tạo PDF từ template HTML/CSS	Artisan
Xây dựng PDF lập trình (cell, vẽ)	Core
Email HTML sang PDF lưu trữ	Artisan
Hóa đơn từ dữ liệu có cấu trúc	Core hoặc Artisan
Layout CSS phức tạp (Grid, Flexbox)	Artisan
PDF ký/mã hóa	Core

Cách hoạt động

Artisan khởi chạy instance Chrome headless qua Chrome DevTools Protocol, tải nội dung HTML vào trang trình duyệt, và dùng chức năng print-to-PDF tích hợp của Chrome. Điều này nghĩa là mọi tính năng CSS mà Chrome hỗ trợ đều sẵn sàng cho PDF — không cần chiến đấu với CSS parser hạn chế.

HTML/CSS --> ChromeBridge --> Chrome CDP --> PDF binary --> save / stream

Cài đặt

bash

composer require yeeefang/tcpdf-next-artisan

Yêu cầu:

PHP 8.2+
chrome-php/chrome ^1.15 (cài tự động)
Chrome hoặc Chromium đã cài trên máy

bash

# Ubuntu/Debian
apt-get install -y chromium-browser

# macOS
brew install --cask chromium

# Windows (Chocolatey)
choco install googlechrome

# Đặt đường dẫn tùy chỉnh qua biến môi trường
export CHROME_PATH=/usr/bin/google-chrome

Khởi đầu nhanh

php

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

$renderer
    ->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
    ->save('/output/hello.pdf');

Từ URL

php

HtmlRenderer::create()
    ->loadUrl('https://example.com/report')
    ->save('/output/report.pdf');

Từ file

php

HtmlRenderer::create()
    ->loadFile('/templates/invoice.html')
    ->save('/output/invoice.pdf');

Nội dung Package

Class	Mục đích
`HtmlRenderer`	Điểm truy cập chính — tải HTML, cấu hình, render
`ChromeBridge`	Giao tiếp Chrome DevTools Protocol
`RenderOptions`	Cấu hình render (margin, scale, header)
`PageSetup`	Kích thước và hướng trang cho render
`PdfMerger`	Ghép nhiều trang đã render thành một PDF
`StyleInjector`	Chèn CSS stylesheet trước render
`ScreenshotCapture`	Chụp ảnh màn hình trang (PNG/JPEG)

Phân cấp Exception

Exception	Khi nào
`RenderException`	Lỗi render chung
`ChromeNotFoundException`	Không tìm thấy binary Chrome tại đường dẫn mong đợi
`TimeoutException`	Tải trang hoặc render vượt quá timeout đã cấu hình

Mọi exception nằm dưới namespace Yeeefang\TcpdfNext\Artisan\Exceptions và extend class base ArtisanException chung.

So sánh với Core HTML Parser

Package Core bao gồm module HtmlParser cho chuyển đổi HTML sang PDF cơ bản. Dùng nó khi bạn cần giải pháp không phụ thuộc bên ngoài. Dùng Artisan khi bạn cần render trung thực hoàn toàn.

Tính năng	Core HtmlParser	Artisan
Phụ thuộc bên ngoài	Không	Chrome/Chromium
CSS Flexbox / Grid	Không	Có
Web font (`@font-face`)	Không	Có
Media query	Không	Có
Thực thi JavaScript	Không	Có
CSS rule `@page`	Không	Có
Hiệu suất (doc đơn giản)	Nhanh hơn	Chậm hơn
Hiệu suất (CSS phức tạp)	N/A	Đáng tin cậy

Bước tiếp theo

HTML Renderer -- Tải và render nội dung HTML.
Render Option -- Cấu hình kích thước trang, margin, header và footer.
Tính năng nâng cao -- Ghép PDF, chèn CSS, chụp ảnh màn hình.
Thiết lập Docker -- Chạy Artisan trong container.

Package Artisan ​

Khi nào dùng Artisan ​

Cách hoạt động ​

Cài đặt ​

Khởi đầu nhanh ​

Từ URL ​

Từ file ​

Nội dung Package ​

Phân cấp Exception ​

So sánh với Core HTML Parser ​

Bước tiếp theo ​