Templates (XObjects)

PDF Form XObjects — referred to as templates in TCPDF-Next — let you record a block of content once and stamp it onto any number of pages. This is ideal for headers, footers, watermarks, logos, and any element that repeats throughout a document.

All methods return static, so every call can be chained (except startTemplate(), which returns the template ID).

Quick Reference

Method	Purpose
startTemplate()	Begin recording a template; returns template ID
endTemplate()	Stop recording
printTemplate()	Place a recorded template on the current page

Basic Example

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create();

// Create a reusable header template
$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();

// Use the template on multiple pages
$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

Begins recording a new template. All drawing operations after this call are captured into the template instead of being rendered directly on a page.

Parameter	Type	Description
$w	float	Template width in user units (0 = page width)
$h	float	Template height in user units (0 = page height)

Returns an integer template ID used to reference the template later.

WARNING

Do not call addPage() while recording a template. Templates capture content within a fixed bounding box — they are not pages.

endTemplate()

Stops recording and finalises the template. Content drawn after this call goes to the current page again.

printTemplate()

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

Stamps a previously recorded template onto the current page at the specified position.

Parameter	Type	Description
$id	int	Template ID returned by startTemplate()
$x	float	X position on the page
$y	float	Y position on the page
$w	float	Display width (0 = original template width)
$h	float	Display height (0 = original template height)

You can print the same template at different sizes by varying $w and $h. The template content is scaled to fit.

Use Cases

Repeated Header / Footer

$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);
}

Scaled Logo

Print the same template at different sizes:

$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)   // Full size
    ->printTemplate($logo, 10, 40, 30, 10);   // Half size

Tips

• Templates are stored as PDF Form XObjects -- content is defined once regardless of how many times it is printed, keeping file size low.
• Templates can contain any drawable content: text, images, shapes, and even other templates.
• The coordinate system inside a template starts at (0, 0) in the top-left corner of the bounding box.