Przegląd Artisan

W skrócie

NextPDF Artisan to mostek Chrome dla NextPDF. Przekazuje fragment Hypertext Markup Language (HTML) do bezgłowego procesu Chrome za pośrednictwem Chrome DevTools Protocol (CDP), odbiera wynik printToPDF i osadza go w docelowym dokumencie Portable Document Format (PDF) jako obiekt Form XObject. Osadzony tekst można nadal zaznaczać i przeszukiwać.

Przegląd koncepcyjny

Pakiet Artisan (nextpdf/artisan) rozszerza silnik open source NextPDF o mechanizm renderujący, który powierza układ przeglądarce Chrome. Natywny potok HTML silnika NextPDF obejmuje już szeroki podzbiór Cascading Style Sheets (CSS). Używaj mostka Artisan przy dokumentach wymagających układu na poziomie Chrome, w tym CSS flexbox i grid, własnych czcionek internetowych ładowanych ze źródeł data Uniform Resource Identifier (URI) oraz złożonych selektorów, przy jednoczesnym generowaniu tekstu wektorowego zamiast zrasteryzowanego zrzutu ekranu.

Mostek działa jako potok małych komponentów o pojedynczym przeznaczeniu. ChromeHtmlRenderer koordynuje renderowanie. ChromeSecurityPolicy weryfikuje dane wejściowe i opakowuje je w dokument HTML objęty restrykcyjnymi zabezpieczeniami. BrowserPool zarządza cyklem życia procesu Chrome. ViewportCalculator mapuje punkty PDF na piksele CSS. Czytnik NextPDF\Parser analizuje wynik Chrome, a PageImporter przekształca go w obiekt Form XObject. Każdy komponent jest oznaczony jako final, korzysta ze wstrzykiwania przez konstruktor i ma typowanie zgodne z poziomem 10 PHPStan.

Mostek wymaga zewnętrznych zależności. Wymaga biblioteki chrome-php/chrome (^1.15) oraz pliku binarnego Chrome lub Chromium, do którego ma dostęp proces PHP. Żaden z nich nie jest dołączony. Gdy brakuje biblioteki, mostek zgłasza ChromeNotAvailableException zamiast po cichu kończyć się niepowodzeniem; zobacz /integrations/artisan/failure-modes/ na stronie /integrations/artisan/troubleshooting/.

Mechanizm renderujący nigdy nie wysyła zawartości do przeglądarki Chrome, dopóki dane wejściowe nie przejdą ChromeSecurityPolicy::validate(). Dokument, który otrzymuje przeglądarka Chrome, jest zawsze objęty rygorystyczną polityką Content Security Policy (CSP) za pośrednictwem nagłówka Content-Security-Policy oraz wielowarstwową blokadą sieci CDP. Ponieważ mostek przetwarza potencjalnie niezaufany kod HTML, model transportu i izolacji opisano na stronie /integrations/artisan/security-and-operations/ zamiast streszczać go tutaj.

Ta strona opisuje zachowanie pakietu w dostarczanej postaci, zweryfikowane na podstawie src/Artisan/ oraz zestawu tests/Unit/Artisan/. Nie jest to deklaracja zgodności piksel w piksel z interaktywną przeglądarką Chrome: animacje są przechwytywane w ostatniej klatce, układ nie opiera się na JavaScript, a importowana jest tylko pierwsza strona Chrome.

Architektura

Diagram

Zakresy odpowiedzialności komponentów

Komponent	Odpowiedzialność	Źródło
ChromeHtmlRenderer	Koordynuje pojedyncze renderowanie; zwraca ChromeRenderResult	src/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfig	Niemutowalny obiekt wartości konfiguracji	src/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicy	Walidacja danych wejściowych + bezpieczne opakowanie HTML	src/Artisan/ChromeSecurityPolicy.php
BrowserPool	Cykl życia procesu Chrome i polityka ponownego uruchamiania	src/Artisan/BrowserPool.php
ViewportCalculator	Konwersja 72 pt/inch ↔ 96 px/inch	src/Artisan/ViewportCalculator.php
ChromeRenderResult	Otypowane dane wyjściowe renderowania (ChromeRenderResultInterface)	src/Artisan/ChromeRenderResult.php
PageImporter	Przeanalizowana strona Chrome → ImportedFormXObject	src/Artisan/PageImporter.php
EInvoiceServiceFactory	Fabryka kontraktów e-faktury Premium działająca bez kontenera	src/Artisan/EInvoiceServiceFactory.php

Przypadki brzegowe i pułapki

• Historia wersji. Opublikowany artefakt Composer jest oznaczony tagiem v0.1.0. Bloki dokumentacji w kodzie źródłowym zawierają @since 1.7.0 (mostek Chrome) oraz @since 1.1.0 (fabryka e-faktury); oba znaczniki odziedziczono z linii wersji nextpdf/core sprzed zmiany nazwy. Pakiet zmienił nazwę na nextpdf/artisan we wpisie CHANGELOG dla 2.0.0. Tag Composer traktuj jako miarodajną wersję instalacyjną, a znaczniki @since jako historię wersji silnika.
• Tylko pierwsza strona. PageImporter::import() domyślnie używa indeksu strony 0. Zawartość, która wychodzi poza pierwszą stronę Chrome, jest przycinana, chyba że podasz jawną wysokość, co opisano na stronie /integrations/artisan/production-usage/.
• Brak kontenera wstrzykiwania zależności (DI). Artisan działa bez kontenera. EInvoiceServiceFactory zapewnia środowiskom bez kontenera spójny sposób tworzenia instancji usług; zobacz /integrations/artisan/boot-and-discovery/.

Wydajność

Każde renderowanie wiąże się z kosztem wczytania strony Chrome oraz jednokrotnego printToPDF dla wywołania. BrowserPool utrzymuje proces Chrome aktywny między renderowaniami i uruchamia go ponownie co 100 renderowań, aby ograniczyć przyrost pamięci. W zachowaniu Big-O dominuje praca nad układem wykonywana przez Chrome, nie sam mostek. Zmierzony budżet referencyjnego przepływu dla tej strony znajdziesz w performance_budget w sekcji frontmatter oraz na stronie /integrations/artisan/production-usage/.

Uwagi dotyczące bezpieczeństwa

Mostek renderuje potencjalnie niezaufany kod HTML wewnątrz przeglądarki Chrome. Dane wejściowe są walidowane pod kątem rozmiaru i zawartości, zanim trafią do przeglądarki Chrome. Dokument po opakowaniu zawiera default-src 'none'. Blokada na poziomie CDP zatrzymuje każde żądanie podzasobu. Pełny model transportu i izolacji, w tym jawne ograniczenia flagi piaskownicy Chrome, znajduje się na stronie /integrations/artisan/security-and-operations/. Nie traktuj tej sekcji jako pełnego obrazu zabezpieczeń.

Kontekst komercyjny

Mostek open source renderuje HTML do PDF. Plany Premium dodają do wyrenderowanego dokumentu zgodne osadzanie e-faktury (Pro) oraz walidację (Enterprise). Gdy te plany nie są zainstalowane, EInvoiceServiceFactory zwraca null, więc ścieżka open source pozostaje bez nich w pełni funkcjonalna.

Zobacz także

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