Início rápido do Artisan

Visão geral

Associe um ChromeRendererConfig a um documento NextPDF, chame writeHtmlChrome() e salve o arquivo Portable Document Format (PDF). O Chrome renderiza o Hypertext Markup Language (HTML). A ponte importa o resultado como um Form XObject, e o texto continua selecionável.

Visão conceitual

writeHtmlChrome() é um método do Document do core do NextPDF, fornecido pelo concern HasTextOutput. O método valida a entrada e resolve o renderizador do Artisan. Em seguida, envia o HTML ao Chrome, analisa o PDF retornado e incorpora a página 0 como um Form XObject na posição atual do cursor. A assinatura pública é writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — verificada em nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

Exemplo de código — Início rápido

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

Este é o fluxo canônico do README.md do pacote. O Chrome cuida do layout flex do Cascading Style Sheets (CSS). Os números continuam como texto selecionável na saída porque a página é incorporada como um Form XObject, não como uma imagem rasterizada.

Tamanho de página personalizado

Passe largura e altura explícitas em pontos de PDF para ajustar a uma página de tamanho fixo (A4 no exemplo):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

Quando você fornece os dois valores, o Chrome imprime exatamente nesse tamanho de papel. Quando você omite a altura (ou passa null), a ponte se ajusta à altura medida do conteúdo e adiciona uma pequena margem de segurança para reflow. Consulte /integrations/artisan/production-usage/ para entender por que essa margem existe e quando substituí-la.

O que você obtém

Propriedade	Comportamento
Texto	Selecionável e pesquisável (texto vetorial, não rasterizado)
Cascading Style Sheets (CSS)	Layout do Chrome: flexbox, grid, seletores complexos, fontes da web por meio de valores data Uniform Resource Identifier (URI)
Rede	Sem buscas de sub-recursos; Uniform Resource Locators (URLs) remotos não são carregados (consulte /integrations/artisan/security-and-operations/)
Páginas	A página 0 da saída do Chrome é importada

Casos extremos e pegadinhas

• HTML vazio é uma operação nula. writeHtmlChrome('') retorna o documento inalterado (verificado em HasTextOutput::writeHtmlChrome).
• Nenhuma página ainda. Se o documento não tiver nenhuma página, writeHtmlChrome() adiciona uma antes de renderizar.
• Recursos remotos não são carregados. <img src="https://..."> é renderizado vazio. Inclua os recursos inline como URIs data:. Essa é a postura de isolamento de rede, não um bug. Consulte /integrations/artisan/security-and-operations/.
• Ponte ausente. Se nextpdf/artisan não estiver instalado, o core lança uma exceção de layout em vez de um erro fatal.

Desempenho

A primeira chamada inclui o tempo de inicialização e de layout do Chrome. As chamadas subsequentes reutilizam o processo ativo do Chrome por meio do BrowserPool. Para tarefas em lote ou workers de longa duração, leia as orientações sobre ciclo de vida e recursos na página /integrations/artisan/production-usage/.

Notas de segurança

O início rápido usa HTML confiável e codificado diretamente no código. Antes de passar qualquer HTML influenciado pelo usuário para writeHtmlChrome(), leia /integrations/artisan/security-and-operations/. A ponte isola o acesso à rede, mas a renderização de HTML ainda tem uma superfície de ataque.

Contexto comercial

Isso produz um PDF a partir de HTML usando a ponte de código aberto. Para incorporar um arquivo Extensible Markup Language (XML) de nota fiscal eletrônica em conformidade no mesmo documento, o nível Premium Pro fornece um embedder. O caminho de código aberto não é afetado quando o Premium está ausente.

Consulte também

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/production-usage/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/security-and-operations/