Optionele inhoudslagen maken (OCG)

In één oogopslag

Plaats inhoud in benoemde optional content groups (OCG’s), vaak lagen genoemd. Een PDF-lezer kan elke laag via het lagenpaneel in- en uitschakelen; één laag is standaard verborgen. Dit recipe volgt examples/26-layers.php.

Een OCG is een ISO 32000-2 optional content group dictionary met Type /OCG. NextPDF plaatst de laagmarkeringen tussen BDC/EMC en gebruikt de marked-content-tag OC.

Installeren

composer require nextpdf/core:^3

U hebt geen optionele extensie nodig. De layer-API is stabiel sinds 1.0.0 en past binnen de 8.1–8.4-backportmatrix.

Conceptueel overzicht

startLayer($name, $visible) opent een OCG. Alles wat u tekent tot aan de bijbehorende endLayer() hoort bij die groep. $name is het label dat de PDF-lezer in het lagenpaneel toont. ISO 32000-2 vereist de OCG-Name, de string die aan de gebruiker wordt getoond. Wanneer u $visible: false meegeeft, registreert u de groep in de OFF-status van de standaardconfiguratie, waardoor de lezer deze verbergt totdat de gebruiker hem inschakelt.

Zichtbaarheid is afhankelijk van de medewerking van de lezer. Voor een optional content membership dictionary (OCMD) is het standaardzichtbaarheidsbeleid AnyOn. De laag is zichtbaar als een van de gerefereerde groepen AAN staat. Een verborgen laag wordt alleen verborgen op basis van een conventie van de lezer. De laag wordt niet verwijderd of beschermd en is geen redactie of beveiligingsmaatregel. Om inhoud te verwijderen, tekent u deze niet.

API-oppervlak

PHPDoc genereert het API-oppervlak automatisch. Dit recipe gebruikt de volgende twee methoden:

startLayer(string $name, bool $visible = true): static — opent een benoemde OCG; met $visible: false is deze standaard verborgen.
endLayer(): static — sluit de laatst geopende laag (in evenwicht met startLayer()).

Codevoorbeeld — Snel aan de slag

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->startLayer('Content', visible: true);
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Always-visible body content.', newLine: true);
$doc->endLayer();

$doc->startLayer('Debug Grid', visible: false); // hidden until toggled
$doc->setDrawColor(200, 200, 200);
for ($x = 0.0; $x <= 210.0; $x += 10.0) {
    $doc->line($x, 0, $x, 297);
}
$doc->endLayer();

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/layers.pdf');

Codevoorbeeld — Productie

Gebruik dit volledige, harness-klare voorbeeld. Het respecteert NEXTPDF_COOKBOOK_OUTPUT en voegt geen eigen entropie toe.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Layer Examples (OCG)');
$doc->addPage();

// Layer 1 — background, visible by default.
$doc->startLayer('Background', visible: true);
$doc->setFillColor(230, 240, 250);
$doc->rect(10, 10, 190, 277, 'F');
$doc->endLayer();

// Layer 2 — watermark, visible by default; can be toggled off.
$doc->startLayer('Watermark', visible: true);
$doc->setFont('helvetica', 'B', 54);
$doc->setTextColor(200, 200, 200);
$doc->startTransform();
$doc->rotate(45, 105, 148);
$doc->setXY(30, 135);
$doc->cell(150, 20, 'DRAFT', align: Alignment::Center);
$doc->stopTransform();
$doc->endLayer();

// Layer 3 — main content, visible by default.
$doc->startLayer('Content', visible: true);
$doc->setTextColor(0);
$doc->setFont('helvetica', 'B', 20);
$doc->setXY(10, 15);
$doc->cell(0, 14, 'Layer Examples (OCG)', newLine: true);
$doc->ln(4);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This document contains four optional content groups. '
    . "Toggle them in your reader's Layers panel.");
$doc->endLayer();

// Layer 4 — debug grid, hidden by default.
$doc->startLayer('Debug Grid', visible: false);
$doc->setDrawColor(180, 180, 180);
$doc->setLineWidth(0.15);
for ($x = 0.0; $x <= 210.0; $x += 10.0) {
    $doc->line($x, 0, $x, 297);
}
for ($y = 0.0; $y <= 297.0; $y += 10.0) {
    $doc->line(0, $y, 210, $y);
}
$doc->endLayer();

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/layers.pdf';
$doc->save($out);

echo "Created layers.pdf\n";

Randgevallen en valkuilen

Houd elke startLayer() in evenwicht met een endLayer(). Een niet-gesloten laag laat een losse BDC zonder EMC achter en maakt de documentstructuur ongeldig. Koppel elke openende aanroep aan de bijbehorende sluitende aanroep.
Een verborgen laag wordt niet verwijderd. visible: false verbergt inhoud alleen op basis van een conventie van de lezer. De markeringen en eventuele tekst blijven in het bestand staan en kunnen worden teruggehaald. Dit is geen redactie. Teken gevoelige gegevens niet.
Ondersteuning voor het lagenpaneel verschilt. In- en uitschakelen vereist een lezer die optionele inhoud beschikbaar maakt. Afdrukpijplijnen en minimale viewers kunnen lagen die standaard uit staan altijd tonen of altijd verbergen.
Nesten. Geneste lagen zijn toegestaan, maar de zichtbaarheid van elke binnenste groep blijft onafhankelijk. Ga er niet van uit dat een buitenste UIT-laag een binnenste AAN-groep verbergt, tenzij u een lidmaatschapsbeleid instelt.

Prestaties

Elke laag voegt één OCG-dictionary en een BDC/EMC-paar rond de bijbehorende markeringen toe. De overhead is verwaarloosbaar. De kosten schalen met de inhoud binnen de lagen, niet met het aantal lagen; dit blijft dus ruim binnen het budget van 2000 ms / 64 MB.

Beveiligingsopmerkingen

De zichtbaarheid van optionele inhoud is afhankelijk van de medewerking van de lezer en is geen toegangscontrole. Het verbergen van een laag versleutelt, redacteert of verwijdert de inhoud ervan niet. Iedereen kan de laag weer inschakelen of de bytes extraheren. Gebruik nooit een verborgen laag om vertrouwelijke tekst te verbergen; laat de inhoud in plaats daarvan volledig weg. Dit recipe parseert geen invoer en doet geen netwerkverzoeken.

Conformiteit

Bewering	Specificatie	Clausule
Een OCG-dictionary heeft `Type /OCG`.	ISO 32000-2	§8.11.2
De OCG-`Name` is het verplichte label dat aan de gebruiker wordt getoond.	ISO 32000-2	§8.11.2
Optionele inhoud wordt ingesloten tussen `BDC`/`EMC` met de tag `OC`.	ISO 32000-2	§8.11.3.2
OCMD-beleidsregels zijn AllOn/AnyOn/AnyOff/AllOff (standaard AnyOn).	ISO 32000-2	§8.11.4.3

Reproduceerbaarheidsprofiel — structureel. Bij elke save veranderen de trailer-/ID en de datumatomen. De harness verwijdert die atomen en vergelijkt de qpdf-genormaliseerde structuur. Dit recipe beschrijft hoe NextPDF die structuur produceert. Het doet geen uitspraak over algemene ISO 32000-2-conformiteit.

Commerciële context

Niet van toepassing. Optional content groups zijn een Core-functie zonder Premium-drempel.