Tổng quan về NextPDF Artisan

Nhìn nhanh

NextPDF Artisan là cầu nối Chrome cho NextPDF. Nó gửi một đoạn Hypertext Markup Language (HTML) tới một tiến trình Chrome headless qua Chrome DevTools Protocol (CDP), thu lấy đầu ra printToPDF, rồi nhúng kết quả vào tài liệu Portable Document Format (PDF) đích dưới dạng một Form XObject. Văn bản được nhúng vẫn có thể chọn và tìm kiếm được.

Tổng quan khái niệm

Gói Artisan (nextpdf/artisan) mở rộng engine NextPDF mã nguồn mở bằng một bộ kết xuất giao phần bố cục cho Chrome. Pipeline HTML gốc của NextPDF vốn đã bao phủ một tập con Cascading Style Sheets (CSS) rộng. Hãy dùng cầu nối Artisan cho những tài liệu cần bố cục ở cấp độ Chrome, bao gồm CSS flexbox và grid, phông chữ web tùy chỉnh được nạp từ nguồn data Uniform Resource Identifier (URI), và các bộ chọn phức tạp, trong khi vẫn tạo ra văn bản vector thay vì ảnh chụp màn hình đã raster hóa.

Cầu nối chạy như một pipeline gồm các thành phần nhỏ, mỗi thành phần có một mục đích riêng. ChromeHtmlRenderer điều phối một lần kết xuất. ChromeSecurityPolicy kiểm tra dữ liệu đầu vào và bọc dữ liệu đó trong một tài liệu HTML được khóa chặt. BrowserPool quản lý vòng đời của tiến trình Chrome. ViewportCalculator ánh xạ điểm PDF sang pixel CSS. Bộ đọc NextPDF\Parser phân tích đầu ra của Chrome, rồi PageImporter chuyển đầu ra đó thành một Form XObject. Mọi thành phần đều là final, được tiêm qua constructor, và được định kiểu ở PHPStan cấp 10.

Cầu nối phụ thuộc vào các thành phần bên ngoài. Nó cần thư viện chrome-php/chrome (^1.15) và một tệp nhị phân Chrome hoặc Chromium mà tiến trình PHP có thể truy cập. Cả hai đều không được đóng gói kèm. Khi thiếu thư viện, cầu nối phát sinh ChromeNotAvailableException thay vì lỗi âm thầm; xem /integrations/artisan/failure-modes/ trên trang /integrations/artisan/troubleshooting/.

Bộ kết xuất không bao giờ gửi nội dung tới Chrome trước khi dữ liệu đầu vào vượt qua ChromeSecurityPolicy::validate(). Tài liệu mà Chrome nhận luôn được bọc bằng một Content Security Policy (CSP) nghiêm ngặt thông qua header Content-Security-Policy và một lớp chặn mạng CDP để phòng thủ theo chiều sâu. Vì cầu nối xử lý HTML có thể không đáng tin cậy, trang /integrations/artisan/security-and-operations/ ghi lại mô hình truyền tải và cô lập của nó thay vì tóm tắt tại đây.

Trang này mô tả hành vi của gói tại thời điểm phát hành, được kiểm chứng dựa trên src/Artisan/ và bộ test tests/Unit/Artisan/. Đây không phải là khẳng định về sự đồng nhất từng pixel với một trình duyệt Chrome tương tác: hoạt ảnh được chụp ở khung hình cuối, bố cục không dựa vào JavaScript, và chỉ trang Chrome đầu tiên được nhập vào.

Kiến trúc

Diagram

Trách nhiệm của từng thành phần

Thành phần	Trách nhiệm	Nguồn
ChromeHtmlRenderer	Điều phối một lần kết xuất; trả về ChromeRenderResult	src/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfig	Đối tượng giá trị cấu hình bất biến	src/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicy	Kiểm tra dữ liệu đầu vào + lớp bọc HTML an toàn	src/Artisan/ChromeSecurityPolicy.php
BrowserPool	Vòng đời tiến trình Chrome và chính sách khởi động lại	src/Artisan/BrowserPool.php
ViewportCalculator	Chuyển đổi 72 pt/inch ↔ 96 px/inch	src/Artisan/ViewportCalculator.php
ChromeRenderResult	Đầu ra kết xuất có định kiểu (ChromeRenderResultInterface)	src/Artisan/ChromeRenderResult.php
PageImporter	Trang Chrome đã phân tích → ImportedFormXObject	src/Artisan/PageImporter.php
EInvoiceServiceFactory	Factory không cần container cho các contract hóa đơn điện tử Premium	src/Artisan/EInvoiceServiceFactory.php

Trường hợp đặc biệt & lưu ý

• Dòng phiên bản. Artifact Composer được phát hành mang tag v0.1.0. Các docblock trong mã nguồn mang @since 1.7.0 (cầu nối Chrome) và @since 1.1.0 (factory hóa đơn điện tử), cả hai đều kế thừa từ dòng phiên bản nextpdf/core trước khi đổi tên; gói đã được đổi tên thành nextpdf/artisan trong mục CHANGELOG 2.0.0. Hãy xem tag Composer là phiên bản cài đặt chính thức, còn các dấu @since là lịch sử phiên bản của engine.
• Chỉ trang đầu tiên. PageImporter::import() mặc định dùng chỉ số trang 0. Nội dung tràn sang trang Chrome thứ hai sẽ bị cắt trừ khi bạn cung cấp chiều cao tường minh, như được nêu trên trang /integrations/artisan/production-usage/.
• Không có container dependency injection (DI). Artisan không dùng container. EInvoiceServiceFactory cung cấp cho các môi trường không có service container một cách nhất quán để khởi tạo service; xem /integrations/artisan/boot-and-discovery/.

Hiệu năng

Mỗi lần kết xuất đều phải chịu chi phí nạp trang Chrome và chạy printToPDF một lần cho mỗi lệnh gọi. BrowserPool giữ cho tiến trình Chrome tiếp tục hoạt động giữa các lần kết xuất và khởi động lại nó sau mỗi 100 lần kết xuất để giới hạn mức tăng bộ nhớ. Công việc bố cục của Chrome, chứ không phải bản thân cầu nối, mới chi phối hành vi Big-O. Để biết ngân sách đo được cho luồng tham chiếu của trang này, hãy xem performance_budget trong frontmatter và trang /integrations/artisan/production-usage/.

Lưu ý về bảo mật

Cầu nối kết xuất HTML có thể không đáng tin cậy bên trong Chrome. Dữ liệu đầu vào được kiểm tra cả về kích thước lẫn nội dung trước khi Chrome nhìn thấy nó. Tài liệu đã được bọc mang default-src 'none'. Một lớp chặn ở cấp CDP ngăn mọi yêu cầu tài nguyên con. Mô hình truyền tải và cô lập đầy đủ, bao gồm cả các giới hạn tường minh của cờ sandbox của Chrome, nằm trên trang /integrations/artisan/security-and-operations/. Đừng xem phần này là toàn bộ thế trận bảo mật.

Bối cảnh thương mại

Cầu nối mã nguồn mở kết xuất HTML thành PDF. Các gói Premium bổ sung khả năng nhúng hóa đơn điện tử tuân thủ (Pro) và kiểm định (Enterprise) trên nền tài liệu đã kết xuất. Khi các gói đó không được cài đặt, EInvoiceServiceFactory trả về null, nên đường đi mã nguồn mở vẫn hoạt động đầy đủ mà không cần đến chúng.

Xem thêm

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/production-usage/