Przewodnik dla deweloperów Artisan

W skrócie

Pakiet Artisan ma dwa powiązane zadania: renderowanie dokumentów Hypertext Markup Language (HTML) za pomocą Chrome oraz importowanie wynikowej strony w formacie Portable Document Format (PDF) do dokumentu NextPDF. Podczas diagnozowania problemów rozdzielaj granice odpowiedzialności Chrome, parsera i importera.

Korzystaj z tego przewodnika, gdy tworzysz integracje renderera, długo działające procesy robocze, diagnostykę parsera lub testy dla nextpdf/artisan.

Granica architektoniczna

Warstwa	Należy do	Odpowiedzialność	Czego tu nie umieszczać
Aplikacja	Aplikacja	Autoryzacja generowania HTML i wybór konfiguracji renderera.	Zarządzanie procesem przeglądarki.
Polityka HTML	Aplikacja i pakiet	Odrzucanie niebezpiecznego lub zbyt dużego HTML przed renderowaniem.	Autoryzacja najemcy lub decyzje biznesowe.
Renderer Chrome	nextpdf/artisan	Renderowanie HTML do samodzielnego pliku PDF wygenerowanego przez Chrome.	Ogólne naprawianie PDF lub dowolna edycja PDF.
Parser/importer	nextpdf/artisan	Parsowanie wyrenderowanego PDF i import jednej strony w postaci form XObject.	Pełna walidacja zgodności z PDF.
Silnik podstawowy	nextpdf/nextpdf	Rozmieszczanie zaimportowanych obiektów formularzy i zapis końcowego dokumentu.	Cykl życia Chrome DevTools Protocol (CDP).

Cykl życia w czasie wykonywania

Etap	Zachowanie	Działanie dewelopera
Tworzenie konfiguracji	ChromeRendererConfig definiuje plik binarny, limit czasu, arkusze Cascading Style Sheets (CSS), rozmiar danych wejściowych oraz zachowanie piaskownicy.	Używaj konfiguracji właściwej dla danego środowiska zamiast sztywno zakodowanych założeń dotyczących środowiska uruchomieniowego.
Tworzenie renderera	ChromeHtmlRenderer zarządza BrowserPool.	Używaj renderera ponownie w obrębie procesu roboczego, a następnie zamknij go podczas wyłączania.
Walidacja HTML	Polityka bezpieczeństwa sprawdza rozmiar i obudowuje dokument domyślnym CSS.	Sprawdź autoryzację wywołującego przed tym etapem.
Drukowanie w Chrome	CDP renderuje samodzielny PDF.	Pozostaw zasoby zewnętrzne zablokowane, chyba że zatwierdzona polityka na nie zezwala.
Parsowanie PDF	PdfReader::parse() odczytuje dane xref, strony, obiekty, zasoby i rewizje.	Traktuj awarie parsera jak awarie renderowania, chyba że celem jest diagnostyka.
Import strony	PageImporter::import() wyodrębnia zawartość strony, media box, zasoby i osadzone obiekty.	Importuj stronę 0, chyba że przepływ pracy celowo wybiera inną stronę.

Zalecana struktura aplikacji

Ścieżka	Przeznaczenie
app/Pdf/Renderers/*	Wrapper aplikacji wokół ChromeHtmlRenderer.
app/Pdf/Templates/*	Renderowanie szablonów HTML i mapowanie data transfer object (DTO) do widoku.
app/Pdf/Policies/*	Polityka renderowania dla rozmiaru HTML, zasobów i najemcy.
tests/Pdf/Renderer/*	Testy dymne renderera z małymi fiksturami HTML.
tests/Pdf/Parser/*	Fikstury parsera dla importowanego wyjścia Chrome.

Oddzielaj renderowanie szablonów od renderowania w przeglądarce. Przekaż rendererowi gotowy HTML i znaną szerokość strony.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

$result = $renderer->render($html, widthPt: 595.28);

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

Wzorzec renderera

Twórz jeden renderer na proces roboczy albo zakres żądania. Używaj go ponownie, aby uniknąć kosztu wielokrotnego uruchamiania Chrome. Zamykaj go jawnie, aby zapobiec wyciekom procesów przy wyłączaniu procesu roboczego.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

Wzorzec diagnostyki parsera

Korzystaj z interfejsów programistycznych parsera application programming interfaces (API), gdy wyjście Chrome nie daje się zaimportować. Prowadź diagnostykę w trybie tylko do odczytu i unikaj zmieniania stanu parsera po udanym imporcie.

Pytanie diagnostyczne	API do użycia	Oczekiwany sygnał
Czy plik się parsuje?	PdfReader::parse()	Zgłasza wyjątek dla nieprawidłowej struktury PDF.
Czy strona 0 istnieje?	PdfReader::getPage(0)	Zwraca PdfObject.
Czy jest zawartość?	PdfReader::getPageContentStream($page)	Niepusty strumień zawartości.
Czy zasoby są obecne?	PdfReader::getPageResources($page)	Tablica ze słownikiem zasobów.
Czy są przyrostowe rewizje?	PdfReader::getRevisionCount()	Licznik większy niż jeden.
Który obiekt zawiódł?	PdfTokenizer::getOffset() oraz kontekst wyjątku parsera.	Przesunięcie bajtowe przydatne do redukcji fikstury.

Punkty rozszerzeń

Punkt rozszerzenia	Stosuj go do	Ograniczenie
ChromeRendererConfig::fromArray()	Mapowanie konfiguracji frameworka.	Nieznane lub błędnie wpisane opcje wracają do wartości domyślnych.
HtmlSecurityPolicyInterface	Polityka HTML na poziomie parsowania.	Nie zastępuje mechanizmów kontroli transportu, procesu ani autoryzacji.
LoggerInterface	Diagnostyka renderowania i przeglądarki.	Nie rejestruj domyślnie zawartości HTML.
BrowserPool	Ponowne wykorzystanie długo działającego procesu Chrome.	Musi zostać zamknięty przy wyłączaniu procesu roboczego.
PageImporter	Osadzanie sparsowanej strony zewnętrznej.	Reader musi być najpierw sparsowany.
Klasy parsera	Diagnostyka i importowane wyjście Chrome.	Nie jest to ogólny zestaw narzędzi do naprawy PDF.

Przepływ pracy podczas programowania

1. Odtwórz fragment HTML w minimalnym teście renderowania.
2. Sprawdź maxHtmlSize, domyślny CSS oraz ścieżkę do pliku binarnego Chrome.
3. Renderuj ze stałą szerokością w punktach.
4. Sparsuj zwrócone bajty PDF za pomocą PdfReader::parse().
5. Importuj stronę 0, chyba że przepływ pracy celowo wybiera inną stronę.
6. Dodaj testy fiksturowe dla najmniejszego HTML, który odtwarza każdą awarię.
7. Zamykaj renderer w procedurach wyłączania procesu roboczego.

Obsługa awarii

Awaria	Gdzie to obsłużyć	Zalecana reakcja
Brak pliku binarnego Chrome	Kontrola wdrożenia i ścieżka tworzenia renderera.	Zgłoś brak gotowości przed przyjęciem ruchu do renderowania.
Zbyt duży HTML	Polityka HTML.	Odrzuć przed uruchomieniem Chrome.
Limit czasu przeglądarki	Granica renderera.	Zgłoś awarię renderowania i zapisz nazwę szablonu, rozmiar, szerokość oraz limit czasu.
Awaria parsera	Granica importu.	Zapisz małą, oczyszczoną fiksturę do debugowania, gdy polityka na to zezwala.
Wyciek procesu przeglądarki	Cykl życia procesu roboczego.	Zamykaj przy wyłączaniu i restartuj po kontrolowanej liczbie renderowań.

Bezpieczne wartości domyślne

Zagadnienie	Wartość domyślna	Kiedy zmienić
Limit czasu renderowania	30 sekund.	Zwiększaj tylko dla zmierzonych dokumentów o ograniczonym rozmiarze.
Maksymalny rozmiar HTML	5,000,000 bajtów.	Obniż dla publicznych punktów końcowych.
Piaskownica	Włączona.	Wyłącz tylko wtedy, gdy wymagają tego ograniczenia kontenera, a host jest izolowany.
Wysokość	Automatyczna, gdy heightPt <= 0.	Używaj stałej wysokości dla ścisłych kontraktów układu.
Zasoby zewnętrzne	Zablokowane przez politykę renderera.	Zezwalaj tylko zgodnie z zatwierdzoną polityką zasobów.

Lista kontrolna testów

• Testy renderowania obejmują reprezentatywny HTML i CSS.
• Testy bezpieczeństwa obejmują zbyt duży HTML i próby zablokowanych zasobów.
• Testy importu sprawdzają, czy zwrócony obiekt formularza ma zawartość, media box i zasoby.
• Testy parsera obejmują tablicę cross-reference (xref), strumień xref, strumień obiektów oraz przypadki uszkodzonych fikstur.
• Testy procesów roboczych wywołują close() i weryfikują, że żaden proces przeglądarki nie pozostaje aktywny.
• Testy wydajności rejestrują czas renderowania według szablonu i rozmiaru zawartości.