HTML para PDF, o caminho fácil

Até aqui nesta trilha, você construiu páginas uma chamada de cada vez. Muitos documentos são mais rápidos de descrever como markup, o formato de texto baseado em tags usado em páginas web. Neste tutorial, você entrega ao NextPDF um pouco de Hypertext Markup Language (HTML), e o engine desenha a página para você.

O que você vai construir

Um relatório de uma página renderizado a partir de uma única string de HTML. Ele tem um título colorido, um parágrafo curto e uma tabela com uma linha de totais. Você o estiliza com Cascading Style Sheets (CSS), a linguagem de regras que controla a aparência do markup. Nos tutoriais anteriores, você usou a API (Application Programming Interface) fluente, as chamadas de método encadeadas. Aqui, em vez disso, você descreve o layout em markup, e o mesmo engine o renderiza.

Passo 1: Renderize um relatório estilizado a partir de HTML

Crie um arquivo chamado 01-html.php na pasta do seu projeto, ao lado de vendor. Cole este script completo:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

Execute o script a partir da pasta do projeto:

php 01-html.php

Você deve ver uma linha de saída:

Wrote out/reading-report.pdf

Abra out/reading-report.pdf em qualquer visualizador de Portable Document Format (PDF). O título é azul-escuro, e a linha de cabeçalho da tabela é preenchida com a mesma cor.

O que acabou de acontecer

@mkdir(__DIR__ . '/out'); cria a pasta de saída. O sinal @ oculta o aviso quando a pasta já existe, então execuções repetidas permanecem silenciosas.
Document::createStandalone(), setTitle() e addPage() funcionam exatamente como nos tutoriais anteriores. Mudar para markup não altera nada na configuração do documento.
writeHtml() lê sua string uma vez, de cima para baixo, e desenha cada elemento na posição atual. Títulos e parágrafos se tornam texto estilizado. A tabela se torna linhas dimensionadas de células com bordas.
Os atributos style inline carregam o CSS. O engine entende propriedades comuns como color, background-color, text-align e width.
Nenhum navegador e nenhum software extra estão envolvidos. O pipeline é PHP puro dentro do engine, então o script roda onde quer que sua instalação do Composer rode.

O engine oferece suporte a um subconjunto prático de HTML e CSS, não a tudo que um navegador aceita. Qualquer coisa fora desse subconjunto é ignorada silenciosamente, em vez de gerar um erro. A matriz de suporte a CSS registra exatamente o que é coberto. Para um passo a passo mais aprofundado deste pipeline, consulte Renderizar HTML em uma página PDF.

Quando usar HTML e quando usar a API fluente

Ambos os caminhos rodam no mesmo engine, então escolha o que melhor se adequar ao documento.

Escolha writeHtml() quando o documento se parece com uma página web: títulos, parágrafos, listas e tabelas. Markup é mais rápido de escrever e mais fácil para os colegas de equipe editarem.
Escolha a API fluente quando você precisa de posicionamento exato, como posições fixas ou células medidas com precisão. Markup dá a você fluxo; as chamadas fluentes dão a você controle.
Verifique a matriz de suporte a CSS antes de depender de uma propriedade. Quando um estilo não é coberto, construa essa parte com chamadas fluentes.

O limite de segurança

HTML real muitas vezes vem de fora do seu código, por exemplo, de um formulário ou de um banco de dados. Trate-o como entrada não confiável e valide ou limpe-o antes de renderizar. Por padrão, o pipeline integrado não executa scripts e não busca recursos remotos. Esse padrão mantém o renderizador conservador, mesmo quando o markup não é. Se você precisar de opções de renderização de nível de navegador, consulte Escolha o seu caminho.

Se algo deu errado

Failed to open stream: No such file or directory geralmente significa que o script não consegue encontrar vendor/autoload.php. Execute-o a partir da pasta onde você rodou o Composer.
Um estilo ausente geralmente é uma propriedade fora do subconjunto suportado. O engine ignora o que não suporta em vez de falhar. Compare seu markup com a matriz de suporte a CSS.
Uma exceção durante a renderização identifica o problema exato. Consulte-a na referência de erros de renderização e de entrada/saída.

Para qualquer outra coisa, comece pelo guia de solução de problemas.

Próximos passos

Agora você sabe construir documentos chamada por chamada e a partir de markup. Conclua a trilha com Para onde ir a seguir. Ele mapeia o cookbook, a referência e os guias que você usará depois desta trilha.