Uso Básico

Esta página apresenta os blocos fundamentais de construção de todo documento TCPDF-Next: criar um documento, adicionar páginas, escrever texto, incorporar imagens e produzir a saída.

Criando um Documento

O factory estático Document::create() é o ponto de entrada único para todo PDF:

use Yeeefang\TcpdfNext\Core\Document;

$doc = Document::create();

Todos os parâmetros são opcionais — os padrões fornecem um documento A4 retrato medido em milímetros. Consulte a página de Configuração para a lista completa de opções.

Adicionando Páginas

Um documento começa vazio. Chame addPage() pelo menos uma vez antes de escrever qualquer conteúdo:

use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\ValueObjects\Margin;

// Adicionar uma página com os padrões do documento
$doc->addPage();

// Adicionar uma página Letter paisagem com margens personalizadas
$doc->addPage(
    pageSize: PageSize::Letter,
    orientation: Orientation::Landscape,
    margin: new Margin(left: 10, top: 10, right: 10, bottom: 10),
);

Tamanhos de Página Disponíveis

PageSize é um backed enum que inclui todos os tamanhos padrão ISO e norte-americanos:

Valor Enum	Dimensões
PageSize::A3	297 × 420 mm
PageSize::A4	210 × 297 mm
PageSize::A5	148 × 210 mm
PageSize::Letter	215,9 × 279,4 mm
PageSize::Legal	215,9 × 355,6 mm

Tamanhos personalizados são suportados via PageSize::custom(width, height).

Definindo Fontes

O TCPDF-Next inclui as fontes base padrão do PDF mais a família DejaVu Sans com suporte a Unicode.

// Fonte base embutida
$doc->setFont('Helvetica', size: 12);

// Fonte Unicode embutida
$doc->setFont('DejaVuSans', size: 10);

// Variantes negrito / itálico
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 14);
$doc->setFont('Helvetica', style: FontStyle::BoldItalic, size: 14);

Fontes Personalizadas

Registre uma fonte TrueType ou OpenType e depois use-a pelo alias:

use Yeeefang\TcpdfNext\Core\Config\FontConfig;

$doc->configureFonts(function (FontConfig $config): void {
    $config->addFont('/fonts/Inter-Regular.ttf', alias: 'Inter');
});

$doc->setFont('Inter', size: 11);

Saída de Texto

O TCPDF-Next fornece quatro métodos para posicionar texto na página. Cada um atende a uma necessidade de layout diferente.

cell()

Imprime uma célula de linha única. Ideal para rótulos, células de tabela e texto curto:

$doc->cell(
    width: 80,
    height: 10,
    text: 'Invoice #1042',
    border: true,
    align: Align::Center,
);

multiCell()

Imprime texto que quebra automaticamente dentro de uma largura definida. O cursor desce após cada chamada:

$doc->multiCell(
    width: 0,        // 0 = largura total disponível
    height: 7,
    text: 'This is a longer paragraph that will wrap across multiple lines '
        . 'based on the available width and the current font size.',
);

text()

Posiciona texto em uma posição absoluta (x, y). Não move o cursor:

$doc->text(x: 105, y: 20, text: 'Centered Title', align: Align::Center);

write()

Escreve texto inline na posição atual do cursor. Suporta links e flui naturalmente dentro de um parágrafo:

$doc->write(height: 5, text: 'Visit the ');
$doc->write(height: 5, text: 'TCPDF-Next docs', link: 'https://tcpdf-next.dev');
$doc->write(height: 5, text: ' for more information.');

Imagens

A Partir de um Caminho de Arquivo

$doc->imageFromFile(
    path: '/images/logo.png',
    x: 15,
    y: 15,
    width: 40,
);

A Partir de uma String ou Resource

$binary = file_get_contents('https://example.com/photo.jpg');

$doc->image(
    data: $binary,
    x: 15,
    y: 60,
    width: 50,
    type: 'JPEG',
);

Formatos suportados: PNG, JPEG, GIF, SVG, WebP.

Salvando e Saída

O TCPDF-Next oferece várias maneiras de obter o PDF final.

Salvar em Disco

$doc->save('/reports/invoice-1042.pdf');

Enviar para o Navegador

use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

// Exibição inline (Content-Disposition: inline)
$doc->output('invoice.pdf', OutputDestination::Inline);

// Forçar download (Content-Disposition: attachment)
$doc->output('invoice.pdf', OutputDestination::Download);

Obter Dados PDF Brutos

$pdfBytes = $doc->getPdfData();

// Use com uma resposta PSR-7, um job de fila, upload para S3, etc.

Enum OutputDestination

Valor	Comportamento
OutputDestination::Inline	Envia ao navegador para visualização inline
OutputDestination::Download	Envia ao navegador como download de arquivo
OutputDestination::File	Grava em um caminho de arquivo (usado internamente por save())
OutputDestination::String	Retorna string binária bruta (usado internamente por getPdfData())

API Fluente

A maioria dos setters retorna $this, habilitando um estilo encadeado e fluente:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\PageSize;
use Yeeefang\TcpdfNext\Core\Enums\Orientation;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;

$pdf = Document::create()
    ->setTitle('Monthly Report')
    ->setAuthor('Acme Corp')
    ->addPage(pageSize: PageSize::A4, orientation: Orientation::Portrait)
    ->setFont('Helvetica', style: FontStyle::Bold, size: 18)
    ->cell(width: 0, height: 15, text: 'Monthly Report — February 2026', align: Align::Center)
    ->ln()
    ->setFont('Helvetica', size: 11)
    ->multiCell(width: 0, height: 6, text: 'This report summarises key metrics...')
    ->save('/reports/monthly.pdf');

Exemplo Completo

Juntando tudo:

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Core\Enums\Align;
use Yeeefang\TcpdfNext\Core\Enums\FontStyle;
use Yeeefang\TcpdfNext\Core\Enums\OutputDestination;

$doc = Document::create();

$doc->setTitle('Hello World');
$doc->setAuthor('TCPDF-Next');

$doc->addPage();

// Cabeçalho
$doc->setFont('Helvetica', style: FontStyle::Bold, size: 20);
$doc->cell(width: 0, height: 15, text: 'Hello, TCPDF-Next!', align: Align::Center);
$doc->ln(20);

// Corpo
$doc->setFont('DejaVuSans', size: 12);
$doc->multiCell(
    width: 0,
    height: 7,
    text: 'TCPDF-Next is a modern, type-safe PDF generation library for PHP 8.5+. '
        . 'It provides a clean API, strict static analysis, and comprehensive Unicode support.',
);

// Logo
$doc->imageFromFile(path: __DIR__ . '/logo.png', x: 15, y: 80, width: 30);

// Saída
$doc->output('hello.pdf', OutputDestination::Download);

Próximos Passos

• Configuração — ajuste fino de padrões, criptografia e acessibilidade.
• Configuração — entenda como Core, Pro e Artisan se encaixam.
• FAQ — perguntas frequentes respondidas.