Templates (XObjects)

PDF Form XObjects — referidos como templates no TCPDF-Next — permitem gravar um bloco de conteúdo uma vez e estampá-lo em qualquer número de páginas. Isso é ideal para cabeçalhos, rodapés, marcas d'água, logos e qualquer elemento que se repita ao longo do documento.

Todos os métodos retornam static, então cada chamada pode ser encadeada (exceto startTemplate(), que retorna o ID do template).

Referência Rápida

Método	Propósito
startTemplate()	Iniciar gravação de template; retorna ID do template
endTemplate()	Parar gravação
printTemplate()	Posicionar template gravado na página atual

Exemplo Básico

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create();

// Criar template de cabeçalho reutilizável
$tpl = $pdf->startTemplate(190, 20);
$pdf->setFont('Helvetica', 'B', 14)
    ->setTextColor(255, 102, 0)
    ->cell(0, 10, 'ACME Corp — Confidential', align: 'C')
    ->line(0, 18, 190, 18);
$pdf->endTemplate();

// Usar o template em múltiplas páginas
$pdf->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setFont('Helvetica', '', 12)
    ->setY(35)
    ->cell(0, 10, 'Page 1 content', newLine: true)

    ->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setY(35)
    ->cell(0, 10, 'Page 2 content', newLine: true);

startTemplate()

$tpl = $pdf->startTemplate(float $w = 0, float $h = 0): int

Inicia a gravação de um novo template. Todas as operações de desenho após esta chamada são capturadas no template em vez de serem renderizadas diretamente na página.

Parâmetro	Tipo	Descrição
$w	float	Largura do template em unidades do usuário (0 = largura da página)
$h	float	Altura do template em unidades do usuário (0 = altura da página)

Retorna um ID inteiro do template usado para referenciar o template posteriormente.

WARNING

Não chame addPage() durante a gravação de um template. Templates capturam conteúdo dentro de uma caixa delimitadora fixa — não são páginas.

endTemplate()

Para a gravação e finaliza o template. Conteúdo desenhado após esta chamada vai para a página atual novamente.

printTemplate()

$pdf->printTemplate(int $id, float $x, float $y, float $w = 0, float $h = 0): static

Estampa um template previamente gravado na página atual na posição especificada.

Parâmetro	Tipo	Descrição
$id	int	ID do template retornado por startTemplate()
$x	float	Posição X na página
$y	float	Posição Y na página
$w	float	Largura de exibição (0 = largura original do template)
$h	float	Altura de exibição (0 = altura original do template)

Você pode imprimir o mesmo template em tamanhos diferentes variando $w e $h. O conteúdo do template é escalado para caber.

Casos de Uso

Cabeçalho / Rodapé Repetido

$header = $pdf->startTemplate(190, 15);
$pdf->setFont('Helvetica', 'B', 10)
    ->cell(95, 10, 'Company Name', align: 'L')
    ->cell(95, 10, date('Y-m-d'), align: 'R');
$pdf->endTemplate();

for ($i = 1; $i <= 5; $i++) {
    $pdf->addPage()
        ->printTemplate($header, 10, 10)
        ->setY(30)
        ->cell(0, 10, "Content for page {$i}", newLine: true);
}

Logo Escalado

Imprima o mesmo template em tamanhos diferentes:

$logo = $pdf->startTemplate(60, 20);
$pdf->image('/path/to/logo.png', 0, 0, 60, 20);
$pdf->endTemplate();

$pdf->addPage()
    ->printTemplate($logo, 10, 10, 60, 20)   // Tamanho completo
    ->printTemplate($logo, 10, 40, 30, 10);   // Metade do tamanho

Dicas

• Templates são armazenados como PDF Form XObjects -- o conteúdo é definido uma vez independentemente de quantas vezes é impresso, mantendo o tamanho do arquivo baixo.
• Templates podem conter qualquer conteúdo desenhável: texto, imagens, formas e até outros templates.
• O sistema de coordenadas dentro de um template começa em (0, 0) no canto superior esquerdo da caixa delimitadora.