Configure o NextPDF e renderize seu primeiro PDF

O NextPDF é uma biblioteca PHP que cria arquivos PDF (Portable Document Format). Neste tutorial, você o instala em uma pasta vazia e renderiza seu primeiro documento de uma página. Você precisa de um terminal e cerca de dez minutos.

O que você vai construir

Você vai construir um projeto minúsculo que contém um único script, 01-hello.php. O script renderiza uma única página com uma linha de título em negrito e um parágrafo. Ele salva o resultado como out/hello.pdf. Ao longo do caminho, você aprende dois comandos que confirmam que sua instalação está saudável.

Esta página ensina um caminho de instalação: uma pasta vazia mais o pacote do engine. Existem outros caminhos, como adaptadores de framework, renderizadores baseados em navegador e o cliente Python. Eles estão em Instalação e Escolha seu caminho. Você não precisa deles hoje.

Passo 1: Crie um projeto e instale o NextPDF

O Composer é o gerenciador de pacotes do PHP. Ele baixa bibliotecas para o seu projeto e gera um autoloader. Um autoloader é um pequeno arquivo PHP que encontra as classes das bibliotecas para você, de modo que você nunca escreve longas listas de includes.

Abra um terminal e execute estes três comandos:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

O Composer exibe o progresso enquanto resolve e baixa os pacotes. As linhas exatas variam conforme a versão do Composer e o seu cache local. Uma instalação bem-sucedida termina sem texto de erro e se parece aproximadamente com isto:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

O que acabou de acontecer

O Composer criou três coisas na sua pasta. O composer.json registra que seu projeto depende do engine. O composer.lock fixa a versão exata que foi instalada, de modo que uma instalação posterior resolve o mesmo código. A pasta vendor/ guarda os pacotes baixados, incluindo o vendor/autoload.php. Seu script carrega esse único arquivo, e todas as classes do engine ficam disponíveis.

O Composer também verificou a sua configuração do PHP durante a instalação. O engine declara as extensões PHP de que precisa. Extensões são módulos opcionais embutidos no PHP. Se alguma estiver faltando, o Composer para e a nomeia, em vez de deixar você com uma instalação quebrada.

Passo 2: Renderize seu primeiro PDF

Crie um arquivo chamado 01-hello.php ao lado do composer.json. Cole este programa completo:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

echo "Wrote out/hello.pdf\n";

Execute-o:

php 01-hello.php

Você deve ver exatamente uma linha:

Wrote out/hello.pdf

Abra out/hello.pdf em qualquer visualizador de PDF. Você verá a linha de título em negrito com o parágrafo abaixo dela, e a maioria dos visualizadores mostra “Hello from NextPDF” no título da janela.

O que acabou de acontecer

Percorra o script de cima para baixo:

• require carrega o autoloader do Composer, de modo que a classe Document é resolvida.
• @mkdir cria a pasta out/. O @ no início mantém o script silencioso quando a pasta já existe, para que você possa executá-lo novamente.
• Document::createStandalone() retorna um documento novo. Ele foi feito para scripts curtos de linha de comando exatamente como este.
• setTitle() define o título do documento, que os visualizadores mostram no título da janela.
• addPage() adiciona uma página vazia e posiciona o cursor no canto superior esquerdo.
• setFont() escolhe uma família de fontes, um estilo e um tamanho em pontos. Pontos são a unidade padrão para tamanhos de fonte na impressão. 'B' significa negrito, e '' significa regular. A família chamada helvetica é embutida, então você não precisa de nenhum arquivo de fonte.
• cell() escreve uma linha de texto na posição do cursor. Uma largura de 0 significa “esticar até a margem direita”. newLine: true move o cursor para baixo em seguida, como pressionar Enter.
• save() monta o PDF finalizado e o grava em disco.

Um documento produz um arquivo. Quando você precisar de um segundo PDF, crie um novo documento em vez de reutilizar o antigo.

Passo 3: Verifique sua configuração

Duas verificações rápidas confirmam que esta instalação continuará funcionando além de um único script.

Primeiro, liste as extensões que o seu PHP carrega:

php -m

Procure na lista por curl, gd, intl, mbstring, openssl e zlib. O engine depende dessas seis. O Composer já as verificou no Passo 1, então todas devem aparecer.

Segundo, execute a verificação de integridade do próprio engine:

vendor/bin/nextpdf doctor

No Windows, chame vendor\bin\nextpdf doctor. O comando inspeciona a sua versão do PHP, as extensões, a pasta temporária e a configuração. Cada verificação exibe [OK], [WARN] ou [FAIL], seguida de um veredito geral.

O que acabou de acontecer

Leia primeiro o bloco Extensions. Seis linhas [OK] chamadas curl, gd, intl, mbstring, openssl e zlib significam que sua instalação está pronta para todos os tutoriais seguintes.

O relatório também lista as capacidades do engine. Na instalação gratuita do Core, as capacidades que pertencem aos pacotes comerciais exibem [FAIL] com uma mensagem que nomeia o pacote que as fornece. Isso é esperado aqui, e pode fazer o veredito geral virar UNHEALTHY, mesmo que sua configuração do Core esteja correta. Para estes tutoriais, o bloco Extensions é o sinal que importa.

Se algo deu errado

Compare seu sintoma com estes casos comuns primeiro:

• composer: command not found significa que o Composer está faltando ou não está no seu PATH. Instale-o em getcomposer.org e repita o Passo 1.
• Failed opening required '.../vendor/autoload.php' significa que o script foi executado fora da pasta do projeto, ou que a instalação não foi concluída. Entre na pasta do Passo 1 e execute composer install.
• Se o Composer parar durante o Passo 1 e nomear uma extensão PHP faltante, habilite essa extensão no seu php.ini. Confirme com php -m e repita a instalação.
• Uma linha [FAIL] no bloco Extensions do doctor nomeia uma extensão PHP faltante. Habilite-a no php.ini, confirme com php -m e execute o doctor novamente. Linhas [FAIL] de capacidades que nomeiam um pacote comercial são esperadas na instalação do Core e não exigem ação aqui.

Para qualquer outra coisa, comece pela base de conhecimento de solução de problemas. Se um script lançar uma exceção, procure a classe dela na referência de erros; a maioria dos erros de iniciante aparece em erros gerais.

Próximos passos

Você tem uma instalação funcional e seu primeiro arquivo renderizado. Continue com Texto, fontes e noções básicas de página para controlar tamanhos de página, fontes embutidas, cores e alinhamento.