Componha texto com fontes e alinhamento

Visão geral

Use esta receita para posicionar texto e controlar a família, o estilo, o tamanho e o alinhamento da fonte. Para isso, você usa três métodos: setFont(), cell() e multiCell(). O código segue examples/04-text-and-fonts.php.

Instalação

composer require nextpdf/core:^3

Essa restrição de versão instala o pacote nextpdf/core. O exemplo requer PHP 8.4.

Visão conceitual

setFont($family, $style, $size) seleciona a face ativa para a próxima chamada de texto. O argumento $style pode combinar três sinalizadores: B (negrito), I (itálico) e U (sublinhado). O sinalizador U aplica decoração de texto; os outros sinalizadores selecionam a variante da fonte. As famílias Helvetica, Times e Courier são resolvidas para as 14 fontes Type 1 padrão nomeadas na ISO 32000-2. Um perfil de conformidade pode substituir esse comportamento e exigir uma fonte substituta incorporada.

cell() escreve uma linha dentro de uma caixa. multiCell() quebra as palavras em uma coluna com a largura e a altura de linha que você fornecer. O texto começa no espaço de texto, e a matriz de texto mapeia esse espaço para o espaço do usuário (ISO 32000-2). Você trabalha em unidades de usuário, e o motor emite a matriz por você.

Defina o alinhamento com o enum Alignment: Left, Center, Right, Justify. No multiCell(), a justificação distribui o espaçamento entre palavras ao longo da linha.

Superfície da API

setFont(string $family, string $style = '', float $size = 12.0): static — NextPDF\Core\Concerns\HasTypography.
cell(float $width, float $height, string $text = '', bool|string $border = false, bool $newLine = false, Alignment $align = Alignment::Left, bool $fill = false): static — NextPDF\Core\Concerns\HasTextOutput.
multiCell(float $width, float $height, string $text, bool|string $border = false, Alignment $align = Alignment::Left): static — mesmo trait.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

A tabela completa do PHPDoc vem diretamente do código-fonte.

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

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

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

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Heading', newLine: true);

$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Word-wrapped justified body text.', align: Alignment::Justify);

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

Exemplo de código — Produção

Este exemplo é autocontido, para que o test harness possa executá-lo. Ele espelha examples/04-text-and-fonts.php e mostra variantes de estilo, vários tamanhos, texto justificado com quebra automática e os três alinhamentos.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Text and Fonts');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Text and Font Styles', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Normal text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, 'Bold text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'I', 12);
$doc->cell(0, 8, 'Italic text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'BI', 12);
$doc->cell(0, 8, 'Bold-Italic text in Helvetica 12pt.', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Font Sizes', newLine: true);
foreach ([8, 10, 12, 14, 18] as $size) {
    $doc->setFont('helvetica', '', (float) $size);
    $doc->cell(0, $size * 0.8, "This is {$size}pt text.", newLine: true);
}
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Multi-Line Text (Word Wrap)', newLine: true);
$doc->setFont('helvetica', '', 11);
$paragraph = 'NextPDF is a modern PDF 2.0 library for PHP. It provides a '
    . 'fluent API for document creation. This paragraph demonstrates '
    . 'automatic word wrapping and justified alignment with multiCell().';
$doc->multiCell(0, 7, $paragraph, align: Alignment::Justify);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Text Alignment', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->cell(0, 8, 'Left-aligned text', newLine: true, align: Alignment::Left);
$doc->cell(0, 8, 'Center-aligned text', newLine: true, align: Alignment::Center);
$doc->cell(0, 8, 'Right-aligned text', newLine: true, align: Alignment::Right);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/compose-text-and-fonts.pdf');

echo "Wrote compose-text-and-fonts.pdf\n";

STDOUT esperado:

Wrote compose-text-and-fonts.pdf

Casos extremos e pegadinhas

Largura 0 significa a largura restante. Quando você passa 0, cell(0, ...) e multiCell(0, ...) usam o espaço até a margem direita. Para uma caixa de largura fixa, passe uma largura explícita.
Ordem da string de estilo. 'BI' e 'IB' selecionam a mesma variante negrito-itálico porque o analisador ignora a ordem dos sinalizadores. O sinalizador 'U' é um sinalizador de decoração, não uma variante de fonte.
Cobertura de glifos das fontes padrão. As 14 fontes padrão renderizam todo o repertório de WinAnsiEncoding (Windows-1252). Isso cobre o latino acentuado da Europa Ocidental, o sinal de Euro e pontuação tipográfica comum — travessões curtos e longos, aspas curvas, o marcador (bullet), as reticências e o sinal de marca registrada. Para scripts fora desse conjunto, como chinês, japonês, coreano, árabe, hebraico, grego, cirílico ou tailandês, registre e selecione uma face TrueType. Consulte Incorporar e criar subconjuntos de fontes.
Altura de linha em relação ao tamanho da fonte. A altura de cada linha de multiCell() é o tamanho da fonte multiplicado pelo fator padrão de altura de linha do perfil de métricas. Se a altura for pequena demais, as linhas podem se sobrepor.
Justificação na última linha. Um multiCell() justificado não estica a linha final de um parágrafo. Isso corresponde à composição tipográfica convencional.

Desempenho

A emissão de texto é linear em relação à contagem de glifos, O(n). O orçamento é wall_ms: 1000, peak_mb: 64. Esse orçamento é menor que o das receitas em HyperText Markup Language (HTML), porque não há cascata nem árvore de layout. As fontes padrão não são incorporadas, o que mantém a saída pequena.

Notas de segurança

O conteúdo de texto é renderizado, não interpretado. Valide o comprimento das strings que você recebe de usuários para manter o tamanho da saída limitado. Esse caminho não executa nenhum script nem busca nenhum recurso remoto.

Conformidade

Declaração	Especificação	Cláusula	reference_id
As famílias Helvetica, Times e Courier estão entre as 14 fontes Type 1 padrão.	ISO 32000-2	iso32000_2_sec9#x1.x29
As famílias standard-14 suportam todo o conjunto de caracteres latinos (WinAnsiEncoding, Windows code page 1252).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
As coordenadas de texto estão no espaço de texto, mapeadas para o espaço do usuário pela matriz de texto.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

Esta receita mostra como o NextPDF compõe texto com as fontes padrão. A cobertura de glifos delas é todo o repertório de WinAnsiEncoding (Windows-1252) — latino da Europa Ocidental mais pontuação tipográfica comum. Texto em outros scripts requer uma face de fonte incorporada.

Contexto comercial

Não aplicável.