Guia do desenvolvedor do Artisan

Visão geral

O pacote Artisan tem duas responsabilidades interligadas: renderizar Hypertext Markup Language (HTML) por meio do Chrome e importar a página Portable Document Format (PDF) resultante para um documento NextPDF. Ao depurar problemas, mantenha separadas as fronteiras do Chrome, do parser e do importador.

Use este guia ao escrever integrações de renderizador, workers de longa duração, diagnósticos de parser ou testes para nextpdf/artisan.

Fronteira de arquitetura

Camada	Responsável	Responsabilidade	Não coloque aqui
Aplicação	Aplicação	Autorizar a geração de HTML e escolher a configuração do renderizador.	Gerenciamento de processos do navegador.
Política de HTML	Aplicação e pacote	Rejeitar HTML inseguro ou grande demais antes de renderizar.	Autorização de tenant ou decisões de negócio.
Renderizador do Chrome	`nextpdf/artisan`	Renderizar HTML em um PDF independente produzido pelo Chrome.	Reparo genérico de PDF ou edição arbitrária de PDF.
Parser/importador	`nextpdf/artisan`	Fazer o parse do PDF renderizado e importar uma página como um form XObject.	Validação completa de conformidade com PDF.
Motor principal	`nextpdf/nextpdf`	Posicionar os objetos de formulário importados e gravar o documento final.	Ciclo de vida do Chrome DevTools Protocol (CDP).

Ciclo de vida em tempo de execução

Etapa	Comportamento	Ação do desenvolvedor
Criação da configuração	`ChromeRendererConfig` define o binário, o timeout, o comportamento de Cascading Style Sheets (CSS), o tamanho de entrada e o sandbox.	Use uma configuração específica do ambiente em vez de suposições fixas em tempo de execução.
Criação do renderizador	`ChromeHtmlRenderer` é responsável por um `BrowserPool`.	Reutilize o renderizador dentro de um worker e feche-o durante o encerramento.
Validação de HTML	A política de segurança verifica o tamanho e envolve o documento no CSS padrão.	Valide a autorização do chamador antes desta etapa.
Impressão do Chrome	O CDP renderiza um PDF independente.	Mantenha os recursos externos bloqueados, a menos que uma política revisada os permita.
Parse do PDF	`PdfReader::parse()` lê os dados de xref, páginas, objetos, recursos e revisões.	Trate falhas do parser como falhas de renderização, a menos que o objetivo seja diagnóstico.
Importação de página	`PageImporter::import()` extrai o conteúdo da página, a media box, os recursos e os objetos incorporados.	Importe a página `0`, a menos que o fluxo de trabalho escolha deliberadamente outra página.

Estrutura de aplicação recomendada

Caminho	Finalidade
`app/Pdf/Renderers/*`	Wrapper de aplicação em torno de `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	Renderização de templates HTML e mapeamento de data transfer object (DTO) para a view.
`app/Pdf/Policies/*`	Política de renderização de tamanho de HTML, recursos e tenant.
`tests/Pdf/Renderer/*`	Testes de fumaça do renderizador com pequenas fixtures de HTML.
`tests/Pdf/Parser/*`	Fixtures de parser para a saída importada do Chrome.

Mantenha a renderização de templates separada da renderização do navegador. Passe ao renderizador o HTML final e uma largura de página conhecida.

<?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);

Padrão de renderizador

Crie um renderizador por processo de worker ou por escopo de requisição. Reutilize-o para evitar o custo recorrente de inicialização do Chrome. Feche-o explicitamente para evitar vazamentos de processo durante o encerramento do worker.

<?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();
    }
}

Padrão de diagnóstico do parser

Use as application programming interfaces (APIs) do parser quando a saída do Chrome não puder ser importada. Mantenha os diagnósticos como somente leitura e evite alterar o estado do parser após uma importação bem-sucedida.

Pergunta de diagnóstico	API a usar	Sinal esperado
O arquivo faz parse?	`PdfReader::parse()`	Lança exceção para estrutura de PDF inválida.
A página `0` existe?	`PdfReader::getPage(0)`	Retorna um `PdfObject`.
Há conteúdo?	`PdfReader::getPageContentStream($page)`	Fluxo de conteúdo (content stream) não vazio.
Há recursos disponíveis?	`PdfReader::getPageResources($page)`	Array de dicionário de recursos.
Há revisões incrementais?	`PdfReader::getRevisionCount()`	Contagem maior que um.
Qual objeto falhou?	`PdfTokenizer::getOffset()` e o contexto da exceção do parser.	Deslocamento em bytes (byte offset) para redução da fixture.

Pontos de extensão

Ponto de extensão	Use-o para	Restrição
`ChromeRendererConfig::fromArray()`	Mapeamento de configuração do framework.	Valores opcionais desconhecidos ou com tipo incorreto retornam aos padrões.
`HtmlSecurityPolicyInterface`	Política de HTML na camada de parse.	Não substitui controles de transporte, processo ou autorização.
`LoggerInterface`	Diagnósticos de renderização e do navegador.	Não registre conteúdo HTML em log por padrão.
`BrowserPool`	Reutilização de processo do Chrome de longa duração.	Deve ser fechado no encerramento do worker.
`PageImporter`	Incorporação de uma página externa já analisada.	O reader deve ser analisado primeiro.
Classes de parser	Diagnósticos e saída importada do Chrome.	Não é um kit de reparo geral de PDF.

Fluxo de trabalho de desenvolvimento

Reproduza o fragmento de HTML em um teste de renderização mínimo.
Valide maxHtmlSize, o CSS padrão e o caminho do binário do Chrome.
Renderize com uma largura fixa em pontos.
Faça o parse dos bytes de PDF retornados com PdfReader::parse().
Importe a página 0, a menos que o fluxo de trabalho escolha deliberadamente outra página.
Adicione testes de fixture para o menor HTML que reproduz cada falha.
Feche o renderizador nos hooks de encerramento do worker.

Tratamento de falhas

Falha	Onde deve ser tratada	Resposta recomendada
Binário do Chrome ausente	Verificação de implantação e caminho de construção do renderizador.	Falhe na verificação de prontidão antes de aceitar tráfego de renderização.
HTML grande demais	Política de HTML.	Rejeite antes de iniciar o Chrome.
Timeout do navegador	Fronteira do renderizador.	Faça a renderização falhar e registre o nome do template, o tamanho, a largura e o timeout.
Falha do parser	Fronteira de importação.	Armazene uma pequena fixture sanitizada para depuração quando a política permitir.
Vazamento de processo do navegador	Ciclo de vida do worker.	Feche no encerramento e reinicie após uma contagem controlada de renderizações.

Padrões seguros

Aspecto	Padrão	Quando substituir
Timeout de renderização	`30` segundos.	Aumente apenas para documentos medidos e limitados.
Tamanho máximo de HTML	`5,000,000` bytes.	Reduza para endpoints públicos.
Sandbox	Habilitado.	Desabilite apenas quando as restrições do contêiner exigirem, e o host estiver isolado.
Altura	Automática quando `heightPt <= 0`.	Use altura fixa para contratos de layout estritos.
Recursos externos	Bloqueados pela política do renderizador.	Permita apenas por meio de uma política de recursos revisada.

Lista de verificação de testes

Os testes de renderização cobrem HTML e CSS representativos.
Os testes de segurança cobrem HTML grande demais e tentativas de recursos bloqueados.
Os testes de importação verificam que o objeto de formulário retornado tem conteúdo, media box e recursos.
Os testes de parser cobrem a tabela de cross-reference (xref), o xref stream, o object stream e casos de fixtures malformadas.
Os testes de worker chamam close() e verificam que nenhum processo do navegador permanece.
Os testes de desempenho registram o tempo de renderização por template e tamanho de conteúdo.