Fontes

O TCPDF-Next suporta fontes TrueType, OpenType e Type1 com subconjuntos automáticos, renderização CJK e texto bidirecional. As fontes são carregadas através do método addFont() no Document ou gerenciadas diretamente via FontManager.

Tipos de Fontes Suportados

Formato	Extensões	Notas
TrueType	.ttf	Suporte completo a contornos de glifos, formato mais comum
OpenType	.otf	Variantes CFF e TrueType ambas suportadas
Type1	.pfb + .afm	Fontes PostScript legadas, arquivo de métricas necessário

Fontes Core

A especificação PDF define 14 fontes padrão (as "Base 14") que todo visualizador conforme deve suportar. Estas não requerem incorporação, mantendo o tamanho do arquivo mínimo.

Família	Estilos
Helvetica	Regular, Bold, Italic, Bold Italic
Times	Regular, Bold, Italic, Bold Italic
Courier	Regular, Bold, Italic, Bold Italic
Symbol	Regular
ZapfDingbats	Regular

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Helvetica — the PDF workhorse', newLine: true)
    ->setFont('Times', 'I', 12)
    ->cell(0, 10, 'Times Italic — classic serif', newLine: true)
    ->setFont('Courier', 'B', 12)
    ->cell(0, 10, 'Courier Bold — monospaced', newLine: true);

Carregamento de Fontes Personalizadas

addFont()

Registre um arquivo de fonte TrueType ou OpenType e use-o imediatamente.

$pdf = Document::create()
    ->addFont('NotoSansTC', '', '/path/to/NotoSansTC-Regular.ttf')
    ->addPage()
    ->setFont('NotoSansTC', '', 12)
    ->cell(0, 10, '繁體中文文字', newLine: true);

Famílias de Fontes com Múltiplos Estilos

Registre cada variante de estilo sob o mesmo nome de família. O TCPDF-Next seleciona o arquivo correto quando você chama setFont() com uma string de estilo.

$pdf = Document::create()
    ->addFont('Roboto', '', '/fonts/Roboto-Regular.ttf')
    ->addFont('Roboto', 'B', '/fonts/Roboto-Bold.ttf')
    ->addFont('Roboto', 'I', '/fonts/Roboto-Italic.ttf')
    ->addFont('Roboto', 'BI', '/fonts/Roboto-BoldItalic.ttf')
    ->addPage()
    ->setFont('Roboto', '', 11)
    ->cell(0, 10, 'Regular weight', newLine: true)
    ->setFont('Roboto', 'B', 11)
    ->cell(0, 10, 'Bold weight', newLine: true)
    ->setFont('Roboto', 'I', 11)
    ->cell(0, 10, 'Italic style', newLine: true)
    ->setFont('Roboto', 'BI', 11)
    ->cell(0, 10, 'Bold Italic', newLine: true);

Subconjuntos de Fontes

Por padrão, o TCPDF-Next incorpora apenas os glifos que aparecem no documento. O FontSubsetter cuida disso automaticamente durante a serialização do PDF.

// O subconjunto de fontes é automático — apenas glifos usados são incorporados
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded');
// Resultado: tamanho de arquivo PDF menor

Por que Subconjuntos Importam

Uma fonte CJK completa pode ultrapassar 15 MB. Se seu documento usa apenas um punhado de caracteres, o subconjunto reduz os dados da fonte incorporada para poucos kilobytes. Isso é fundamental para entrega web e anexos de e-mail.

Desabilitando Subconjuntos

Em casos raros (ex.: campos de formulário editáveis onde o usuário pode digitar qualquer caractere), você pode precisar da fonte completa. Passe false para o parâmetro de subconjunto ao registrar:

$pdf->addFont('NotoSans', '', '/fonts/NotoSans-Regular.ttf', subset: false);

Suporte CJK

Texto em chinês, japonês e coreano requer fontes com grandes conjuntos de glifos. O TCPDF-Next valida conteúdo CJK através do CjkValidator e garante codificação correta na saída PDF.

$pdf = Document::create()
    ->addFont('NotoSansCJK', '', '/fonts/NotoSansCJKtc-Regular.otf')
    ->addPage()
    ->setFont('NotoSansCJK', '', 12)
    ->cell(0, 10, '中文：你好世界', newLine: true)
    ->cell(0, 10, '日本語：こんにちは世界', newLine: true)
    ->cell(0, 10, '한국어：안녕하세요 세계', newLine: true);

Fontes CJK são sempre tratadas com subconjuntos, a menos que explicitamente desabilitado — a economia de tamanho é substancial.

Texto Bidirecional (BiDi)

O BiDiResolver implementa o Algoritmo Bidirecional Unicode para renderização correta de scripts da direita para esquerda como árabe e hebraico, incluindo conteúdo misto LTR/RTL.

$pdf = Document::create()
    ->addFont('NotoSansArabic', '', '/fonts/NotoSansArabic-Regular.ttf')
    ->addPage()
    ->setFont('NotoSansArabic', '', 14)
    ->cell(0, 10, 'مرحبا بالعالم', newLine: true)   // Árabe
    ->write(10, 'Mixed: Hello مرحبا World');          // LTR + RTL

A reordenação BiDi é aplicada automaticamente quando o texto contém caracteres RTL. Nenhuma configuração manual é necessária.

ToUnicode CMap

O TCPDF-Next gera um ToUnicode CMap para cada fonte incorporada. Esse mapeamento permite que visualizadores PDF extraiam texto Unicode correto quando usuários copiam/colam ou quando motores de busca indexam o documento. É gerado automaticamente durante a serialização.

Métricas de Fontes

As classes FontInfo e FontMetrics expõem medições tipográficas detalhadas.

$pdf->setFont('Helvetica', '', 12);

// Medir uma string específica na fonte atual
$width = $pdf->getStringWidth('Hello, World!');

// Usar métricas para layout preciso
$cellWidth = $pdf->getStringWidth('Total:') + 4; // adicionar 4mm de padding
$pdf->cell($cellWidth, 8, 'Total:');

As métricas incluem ascender, descender, line gap, cap height, x-height e larguras de avanço por glifo — todas derivadas das tabelas internas da fonte.

Exemplo Completo

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    // Registrar fontes
    ->addFont('Roboto', '', '/fonts/Roboto-Regular.ttf')
    ->addFont('Roboto', 'B', '/fonts/Roboto-Bold.ttf')
    ->addFont('NotoSansTC', '', '/fonts/NotoSansTC-Regular.ttf')

    ->addPage()

    // Cabeçalho em inglês
    ->setFont('Roboto', 'B', 18)
    ->cell(0, 12, 'Multilingual Invoice', newLine: true)
    ->ln(3)

    // Corpo em inglês
    ->setFont('Roboto', '', 11)
    ->cell(0, 8, 'Customer: Acme Corporation', newLine: true)
    ->cell(0, 8, 'Date: 2026-02-16', newLine: true)
    ->ln(5)

    // Seção em chinês
    ->setFont('NotoSansTC', '', 11)
    ->cell(0, 8, '客戶名稱：台灣科技有限公司', newLine: true)
    ->cell(0, 8, '發票日期：2026年2月16日', newLine: true)

    ->save('multilingual-invoice.pdf');