Seu primeiro PDF

Visão geral

Neste tutorial, você gera dois arquivos PDF. Primeiro, você escreve texto diretamente com a API (Application Programming Interface) fluente do core. Em seguida, você renderiza um fragmento de Hypertext Markup Language (HTML) com Cascading Style Sheets (CSS) em uma página. No final, você terá um script funcional que pode adaptar para um documento real, além de links para as variantes de framework e servidor.

As duas abordagens usam o mesmo engine, então o que você aprende aqui vale para todas as distribuições.

O diagrama abaixo mostra as duas abordagens de criação e as três superfícies de implantação que as reutilizam.

From your code to a PDF file

Antes de começar

Você precisa ter o engine do core instalado e um lugar para executar um script PHP.

1. Confirme que o PHP 8.4 é o runtime ativo:

   php --version

2. Instale o engine do core no projeto, caso ainda não esteja presente:

   composer require nextpdf/core

3. Crie um arquivo de trabalho chamado first-pdf.php na raiz do projeto.

As 14 fontes padrão funcionam sem configuração

A fonte padrão do corpo corresponde a uma das 14 fontes Type 1 padrão nomeadas na ISO 32000-2. O primeiro documento não precisa de nenhum arquivo de fonte. Registre e incorpore fontes personalizadas depois, quando o design exigir.

Gere um PDF a partir do PHP

Comece pela API fluente. Document::createStandalone() retorna um documento que você pode usar imediatamente. Adicione uma página, defina uma fonte, escreva células e salve. Cada método de criação retorna o documento; por isso, as chamadas são lidas de cima para baixo.

1. Coloque este código em first-pdf.php. O script declara strict types, carrega o autoloader e monta uma página:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. Execute o script:

   php first-pdf.php

3. Verifique a saída. Você deverá ver esta linha na saída padrão e um novo arquivo chamado first-pdf.pdf ao lado do script:

   Wrote first-pdf.pdf

Você acabou de gerar um arquivo PDF 2.0 válido. Abra-o em qualquer visualizador para ver o título e a linha logo abaixo.

save versus output

save() grava o documento em um caminho de arquivo. Para transmitir os bytes para um navegador, chame output(). Para capturar os bytes em memória, chame getPdfData(). Um documento é de uso único. Depois de gravar um documento, crie uma nova instância para o próximo em vez de reutilizá-la.

Renderize HTML para PDF

Escrever células dá a você controle preciso. A maioria dos documentos, porém, é mais rápida de expressar como HTML e CSS. O engine do core inclui um pipeline de HTML em PHP puro. O método writeHtml() renderiza um fragmento na página atual. Ele não depende de um navegador nem de um serviço externo.

1. Crie um segundo arquivo, html-pdf.php, que renderiza um fragmento de HTML:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. Execute o arquivo:

   php html-pdf.php

3. Verifique a linha de saída e o novo arquivo:

   Wrote html-pdf.pdf

Trate a entrada de HTML como não confiável

Quando o HTML vem de um usuário, de um formulário ou de qualquer fonte externa, valide-o e sanitize-o antes de passá-lo para writeHtml(). A receita Renderizar HTML para uma página PDF aborda a postura de segurança completa e o modelo de streaming.

O engine renderiza um subconjunto compatível de HTML e CSS. Antes de depender de uma propriedade, consulte a matriz de suporte a CSS. Quando um layout precisa de fidelidade total do navegador, como flexbox, grid ou web fonts, instale o renderizador Artisan e chame writeHtmlChrome() em vez disso. Esse método mantém o texto selecionável.

A partir de um controller de framework

Sua aplicação talvez já rode em um framework ou por meio do servidor. As mesmas duas chamadas migram para esse ambiente. O engine permanece o mesmo. Apenas a integração muda.

Laravel

A facade Pdf resolve um novo documento a cada chamada. PdfResponse transforma um documento em uma resposta de download:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Consulte o guia rápido do Laravel.

Symfony

O bundle expõe um serviço PdfFactory. Use um type-hint de NextPDF\Symfony\Service\PdfFactory em um controller, monte um documento da mesma forma e retorne-o como uma resposta HTTP. Consulte o guia rápido do Symfony.

Servidor (REST)

Com o NextPDF Server em execução, envie, via POST, um array ordenado de operações, e o servidor retorna os bytes do PDF:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Em uma resposta 200, o corpo contém o PDF. Consulte o guia rápido do Connect.

Próximos passos

Você acabou de gerar um PDF de três maneiras. Use estas páginas para aprofundar cada uma delas.

Renderizar HTML para uma página PDF A receita de HTML completa: elementos suportados, o modelo de streaming e a postura de segurança.

Escolha o seu caminho Decida entre o core, um framework, o servidor e qual renderizador de HTML usar.

Referência do engine do core Cada método, parâmetro e valor de retorno do Document.

Cookbook Receitas focadas em tarefas para estilização, tabelas, paginação e muito mais.