Texto, fontes e noções básicas de página

No primeiro tutorial, você renderizou uma página com uma única linha de texto. Desta vez, você assume o controle da própria página e do texto nela. Você vai escolher um tamanho de página, escrever títulos e parágrafos e estilizá-los com as fontes integradas do motor.

O que você vai construir

Você vai escrever dois scripts pequenos. Cada um produz um arquivo Portable Document Format (PDF) de uma página:

• 01-text-basics.php renderiza uma página A4 em retrato com um título colorido, parágrafos com quebra automática e três amostras de alinhamento.
• 02-fonts.php renderiza uma página de amostras que compara duas famílias de fontes integradas em vários tamanhos.

Tudo funciona apenas com o pacote nextpdf/core. Você não precisa de arquivos de fonte, de extensões adicionais nem de rede. Se você ainda não tem um projeto configurado, siga o primeiro tutorial antes e depois volte.

Passo 1: Estilizar texto em uma página A4

Toda página tem um tamanho e uma orientação. A4 é o tamanho de papel internacional comum, e Letter é o seu equivalente nos Estados Unidos. A orientação é retrato (em pé) ou paisagem (deitada). Você passa as duas escolhas para addPage() ao iniciar uma página.

Em seguida, três métodos fazem a escrita. setFont() escolhe o tipo e o tamanho da fonte para o texto que segue. cell() escreve uma linha dentro de uma caixa invisível. multiCell() quebra textos mais longos em quantas linhas forem necessárias. Nos dois métodos, uma largura de 0 significa “usar todo o espaço até a margem direita”.

Mais duas chamadas cuidam da aparência. setTextColor() recebe valores de vermelho, verde e azul de 0 a 255, e essa cor vale até você alterá-la de novo. O enum Alignment, uma lista fixa de opções nomeadas, oferece Left, Center, Right e Justify.

Crie 01-text-basics.php na pasta do seu projeto:

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

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

echo "Wrote out/text-basics.pdf\n";

Execute-o com php 01-text-basics.php. O script imprime Wrote out/text-basics.pdf, e o arquivo aparece na nova pasta out/.

O que acabou de acontecer

addPage(PageSize::A4(), Orientation::Portrait) criou a página antes de qualquer texto ser escrito. Passe Orientation::Landscape no lugar, e a mesma página fica deitada. Outros tamanhos nomeados, como PageSize::A5() ou PageSize::Letter(), funcionam da mesma forma.

setFont('helvetica', 'B', 20) selecionou Helvetica em negrito a 20 pontos. Um ponto (pt) é a unidade tradicional de impressão; 72 pontos equivalem a uma polegada. O título fica azul porque setTextColor(30, 64, 175) estava ativo quando a chamada cell() o escreveu. O setTextColor(0, 0, 0) seguinte voltou para o preto em tudo o que vem depois.

As duas chamadas multiCell() quebraram os parágrafos automaticamente. A justificada estica o espaçamento entre palavras para que as duas bordas fiquem alinhadas, exceto na última linha do parágrafo. Entre os blocos, ln() moveu a posição de escrita para baixo para dar mais respiro. Por fim, save() montou o arquivo e o gravou em out/.

Para cada parâmetro que esses métodos aceitam, consulte Compor texto com fontes e alinhamento.

Passo 2: Escolher entre as fontes integradas

O motor traz três famílias de texto integradas: Helvetica, Times e Courier. Helvetica é um tipo sans-serif, ou seja, suas letras não têm pequenos traços nas extremidades (serifas). Times é um tipo com serifa que se lê bem em passagens longas, no estilo de impressão. Courier tem largura fixa, então serve para listagens de código e recibos. Como essas famílias são integradas, seus scripts não precisam de nenhum arquivo de fonte.

O argumento de estilo de setFont() combina flags de uma única letra: 'B' para negrito, 'I' para itálico e 'U' para sublinhado. Uma string vazia significa regular, e as flags se combinam, então 'BI' dá negrito itálico.

As famílias integradas cobrem texto de base latina. Para outros sistemas de escrita ou para o tipo da sua própria marca, você registra um arquivo de fonte, como mostra a receita Incorporar e criar subconjuntos de fontes (o subconjunto mantém apenas os caracteres que você realmente usou, então os arquivos ficam pequenos). A matriz de suporte de fontes lista todos os formatos de fonte que o motor aceita.

Crie 02-fonts.php ao lado do primeiro script:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

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

echo "Wrote out/font-sampler.pdf\n";

Execute-o com php 02-fonts.php e abra out/font-sampler.pdf. Você vê a mesma frase de exemplo mudar de aparência entre as duas famílias e crescer ao longo de três tamanhos.

O que acabou de acontecer

addPage() sem argumentos usou a configuração de página padrão em orientação retrato, então nem todo script precisa detalhar o tamanho. Cada chamada setFont() trocou a família, o estilo ou o tamanho ativos no meio da página, e uma fonte permanece ativa até a próxima chamada setFont().

Os laços convertem o tamanho com (float) porque setFont() espera um número decimal. As alturas de linha acompanham o tamanho da fonte ($size * 0.8), então textos maiores recebem linhas mais altas e nada se sobrepõe. Tente substituir 'times' por 'courier' e executar o script de novo para ver a terceira família.

Se algo deu errado

• Um erro de “class not found” ou de autoload geralmente significa que o script não encontrou vendor/autoload.php. Execute-o dentro da pasta do projeto que contém vendor/.
• Um nome de família digitado errado lança uma exceção que nomeia a fonte que não foi encontrada. Verifique a grafia: helvetica, times, courier.
• O hub de solução de problemas reúne correções comuns, e Fontes e marcação cobre problemas de fonte em profundidade.
• Toda exceção do motor está documentada na referência de erros, com o contexto que ela carrega e a ação de recuperação.

Próximo

Agora você já sabe moldar páginas, estilizar texto e escolher fontes com intenção. No próximo tutorial você posiciona imagens na página e organiza o conteúdo com tabelas e listas.