Layers (OCG)

PDF layers — formally called Optional Content Groups (OCG) — allow you to create content that can be toggled on and off in the viewer, or selectively included when printing. The layer system is managed through Graphics\LayerManager and accessed via the Document fluent API.

All methods return static, so every call can be chained.

Quick Reference

Method	Purpose
startLayer()	Begin a new layer with a given name
endLayer()	Close the current layer

Basic Example

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)

    // Visible in viewer, not printed
    ->startLayer('Screen Only', print: false, view: true)
    ->cell(0, 10, 'This text appears on screen but not when printed', newLine: true)
    ->endLayer()

    // Printed only
    ->startLayer('Print Only', print: true, view: false)
    ->cell(0, 10, 'This text appears only when printed', newLine: true)
    ->endLayer()

    // Always visible
    ->cell(0, 10, 'This text is always visible', newLine: true);

startLayer()

$pdf->startLayer(string $name, bool $print = true, bool $view = true): static

Begins a new layer. All content drawn after this call belongs to the layer until endLayer() is called.

Parameter	Type	Description
$name	string	Display name shown in the viewer's layer panel
$print	bool	Whether the layer content appears when printed
$view	bool	Whether the layer content appears on screen

endLayer()

Closes the current layer. Content drawn after this call is no longer part of any layer.

Layer Visibility Modes

The combination of $print and $view gives you four useful visibility modes:

$print	$view	Behaviour
true	true	Always visible (default)
false	true	Screen only — hidden when printed
true	false	Print only — hidden on screen
false	false	Initially hidden everywhere (user can toggle)

Nested Layers

Layers can be nested. A child layer inherits the visibility constraints of its parent -- if the parent is hidden, the child is hidden too.

$pdf->startLayer('Parent')
    ->cell(0, 10, 'Parent content', newLine: true)
    ->startLayer('Child', print: false, view: true)
    ->cell(0, 10, 'Child content — screen only', newLine: true)
    ->endLayer()
    ->endLayer();

Use Cases

Multi-Language PDFs

Place each translation on a separate layer. Readers toggle languages in the layer panel:

$pdf->startLayer('English')
    ->cell(0, 10, 'Hello, World!', newLine: true)
    ->endLayer()
    ->startLayer('Chinese')
    ->cell(0, 10, '你好，世界！', newLine: true)
    ->endLayer();

Watermark (Screen-Only)

$pdf->startLayer('Watermark', print: false, view: true)
    ->setFont('Helvetica', 'B', 48)
    ->setTextColor(200, 200, 200)
    ->text(60, 140, 'DRAFT')
    ->endLayer();

Print-Only Crop Marks

$pdf->startLayer('Crop Marks', print: true, view: false)
    ->cropMark(20, 20, 10, 10)
    ->cropMark(190, 20, 10, 10)
    ->endLayer();

Tips

• Layer names should be short and descriptive -- they appear verbatim in the viewer's layer panel.
• Adobe Acrobat and Foxit Reader have full OCG support; browser-based viewers may ignore layers.
• Layers add minimal overhead to file size since they are metadata flags, not duplicate content.