Visão geral do NextPDF Artisan

Em resumo

O NextPDF Artisan é a ponte Chrome do NextPDF. Ela envia um fragmento de Hypertext Markup Language (HTML) para um processo Chrome headless pelo Chrome DevTools Protocol (CDP), captura a saída de printToPDF e incorpora o resultado ao documento Portable Document Format (PDF) de destino como um Form XObject. O texto incorporado continua selecionável e pesquisável.

Visão geral conceitual

O pacote Artisan (nextpdf/artisan) estende o mecanismo open source NextPDF com um renderizador que delega o layout ao Chrome. O pipeline HTML nativo do NextPDF já cobre um amplo subconjunto de Cascading Style Sheets (CSS). Use a ponte Artisan para documentos que precisam de layout no nível do Chrome, incluindo flexbox e grid do CSS, fontes web personalizadas carregadas via data Uniform Resource Identifier (URI) e seletores complexos, sem deixar de produzir texto vetorial em vez de uma captura de tela rasterizada.

A ponte funciona como um pipeline de componentes pequenos e de propósito único. O ChromeHtmlRenderer orquestra cada renderização. O ChromeSecurityPolicy valida a entrada e a envolve em um documento HTML restrito. O BrowserPool gerencia o ciclo de vida do processo Chrome. O ViewportCalculator mapeia pontos do PDF para pixels do CSS. O leitor NextPDF\Parser faz o parsing da saída do Chrome, e o PageImporter a converte em um Form XObject. Todo componente é final, injetado via construtor e tipado no nível 10 do PHPStan.

A ponte é vinculada a dependências externas. Ela precisa da biblioteca chrome-php/chrome (^1.15) e de um binário do Chrome ou Chromium acessível ao processo PHP. Nenhum dos dois vem incluído. Quando a biblioteca está ausente, a ponte lança ChromeNotAvailableException em vez de falhar silenciosamente; consulte /integrations/artisan/failure-modes/ na página /integrations/artisan/troubleshooting/.

O renderizador nunca envia conteúdo ao Chrome antes que a entrada passe por ChromeSecurityPolicy::validate(). O documento que o Chrome recebe é sempre envolvido por uma Content Security Policy (CSP) estrita por meio do cabeçalho Content-Security-Policy e por um bloqueio de rede CDP em defesa em profundidade. Como a ponte processa HTML potencialmente não confiável, a página /integrations/artisan/security-and-operations/ documenta seu modelo de transporte e isolamento em vez de resumi-lo aqui.

Esta página descreve o comportamento do pacote conforme distribuído, verificado em relação a src/Artisan/ e à suíte tests/Unit/Artisan/. Ela não afirma paridade pixel a pixel com um navegador Chrome interativo: as animações são capturadas em seu quadro final, o layout não depende de JavaScript e apenas a primeira página do Chrome é importada.

Arquitetura

Diagram

Responsabilidades dos componentes

Componente	Responsabilidade	Origem
ChromeHtmlRenderer	Orquestra uma renderização única; retorna ChromeRenderResult	src/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfig	Value object de configuração imutável	src/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicy	Validação de entrada + envelope HTML seguro	src/Artisan/ChromeSecurityPolicy.php
BrowserPool	Ciclo de vida do processo Chrome e política de reinício	src/Artisan/BrowserPool.php
ViewportCalculator	Conversão de 72 pt/inch ↔ 96 px/inch	src/Artisan/ViewportCalculator.php
ChromeRenderResult	Saída de renderização tipada (ChromeRenderResultInterface)	src/Artisan/ChromeRenderResult.php
PageImporter	Página do Chrome após parsing → ImportedFormXObject	src/Artisan/PageImporter.php
EInvoiceServiceFactory	Factory sem container para contratos de e-invoice do Premium	src/Artisan/EInvoiceServiceFactory.php

Casos extremos & pontos de atenção

• Linhagem de versões. O artefato Composer publicado está marcado como v0.1.0. Os docblocks de origem trazem @since 1.7.0 (ponte Chrome) e @since 1.1.0 (factory de e-invoice), ambos herdados da linha de versões anterior à renomeação de nextpdf/core; o pacote foi renomeado para nextpdf/artisan na entrada de CHANGELOG da 2.0.0. Trate a tag do Composer como a versão de instalação autoritativa e os marcadores @since como histórico de versões do mecanismo.
• Apenas a primeira página. PageImporter::import() usa o índice de página 0 por padrão. O conteúdo que transborda para uma segunda página do Chrome é recortado, a menos que você forneça uma altura explícita, conforme detalhado na página /integrations/artisan/production-usage/.
• Sem container de injeção de dependências (DI). O Artisan não usa container. O EInvoiceServiceFactory oferece a ambientes sem um container de serviços uma forma consistente de instanciar serviços; consulte /integrations/artisan/boot-and-discovery/.

Desempenho

Cada renderização paga o custo de carregamento da página do Chrome e de printToPDF uma vez por chamada. O BrowserPool mantém o processo Chrome ativo entre renderizações e o reinicia a cada 100 renderizações para limitar o crescimento de memória. O trabalho de layout do Chrome, não a ponte em si, domina o comportamento Big-O. Para o orçamento medido do fluxo de referência desta página, consulte performance_budget no frontmatter e a página /integrations/artisan/production-usage/.

Notas de segurança

A ponte renderiza HTML potencialmente não confiável dentro do Chrome. A entrada é validada por tamanho e conteúdo antes de ser vista pelo Chrome. O documento envolvido carrega default-src 'none'. Um bloqueio no nível do CDP interrompe toda requisição de subrecurso. O modelo completo de transporte e isolamento, incluindo os limites explícitos da flag de sandbox do Chrome, está na página /integrations/artisan/security-and-operations/. Não trate esta seção como a postura de segurança completa.

Contexto comercial

A ponte open source renderiza HTML em PDF. Os níveis Premium adicionam incorporação de e-invoice em conformidade (Pro) e validação (Enterprise) sobre o documento renderizado. Quando esses níveis não estão instalados, EInvoiceServiceFactory retorna null, de modo que o caminho open source continua totalmente funcional sem eles.

Consulte também

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