Membuat lapisan konten opsional (OCG)

Sekilas pandang

Bungkus konten dalam grup konten opsional bernama (OCG), yang sering disebut lapisan. Pembaca PDF dapat mengaktifkan/menonaktifkan setiap lapisan melalui panel Layers, dan satu lapisan dimulai dalam keadaan tersembunyi secara baku. Resep ini mengikuti examples/26-layers.php.

OCG adalah kamus grup konten opsional ISO 32000-2 dengan Type /OCG. NextPDF membungkus konten berlapis di antara BDC/EMC dan menggunakan tag marked-content OC.

Instalasi

composer require nextpdf/core:^3

Anda tidak memerlukan ekstensi opsional. API lapisan telah stabil sejak 1.0.0 dan berjalan pada matriks backport 8.1–8.4.

Tinjauan konseptual

startLayer($name, $visible) membuka OCG. Semua yang Anda gambar hingga endLayer() pasangannya menjadi bagian dari grup tersebut. $name adalah label yang ditampilkan oleh pembaca PDF di panel Layers. ISO 32000-2 mewajibkan Name OCG, yaitu string yang ditampilkan kepada pengguna. Memberikan $visible: false mendaftarkan grup dalam keadaan OFF pada konfigurasi baku, sehingga pembaca menyembunyikannya sampai pengguna mengaktifkannya.

Visibilitas bergantung pada kepatuhan pembaca. Untuk kamus keanggotaan konten opsional (OCMD), kebijakan visibilitas baku adalah AnyOn. Lapisan terlihat jika ada grup yang dirujuk berada dalam keadaan ON. Lapisan tersembunyi hanya disembunyikan berdasarkan konvensi pembaca. Lapisan tersebut tidak dihapus atau dilindungi, dan bukan redaksi maupun kontrol keamanan. Untuk menghapus konten, jangan menggambarnya.

Permukaan API

Permukaan API dihasilkan secara otomatis dari PHPDoc. Resep ini menggunakan dua metode berikut:

startLayer(string $name, bool $visible = true): static — membuka OCG bernama; $visible: false membuat OCG tersebut tersembunyi secara baku.
endLayer(): static — menutup lapisan terakhir yang dibuka (pasangan dari startLayer()).

Contoh kode — Mulai cepat

<?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');

Contoh kode — Produksi

Gunakan contoh lengkap yang siap dijalankan oleh harness ini. Contoh ini menghormati NEXTPDF_COOKBOOK_OUTPUT dan tidak menambahkan sumber entropi sendiri.

<?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";

Kasus tepi & jebakan

Pasangkan setiap startLayer() dengan endLayer(). Lapisan yang tidak ditutup menyisakan BDC yang menggantung tanpa EMC dan membuat struktur dokumen cacat. Pasangkan setiap panggilan pembuka dengan panggilan penutupnya.
Lapisan tersembunyi tidak dihapus. visible: false hanya menyembunyikan konten berdasarkan konvensi pembaca. Tanda dan teks apa pun tetap ada di dalam berkas dan dapat dipulihkan. Ini bukan redaksi. Untuk data sensitif, jangan menggambarnya.
Dukungan panel lapisan beragam. Mengaktifkan/menonaktifkan lapisan memerlukan pembaca yang menampilkan konten opsional. Alur cetak dan penampil minimal mungkin selalu menampilkan atau selalu menyembunyikan lapisan yang nonaktif secara baku.
Penyarangan. Lapisan bersarang diperbolehkan, tetapi visibilitas setiap grup di dalamnya tetap independen. Jangan berasumsi bahwa lapisan luar-OFF menyembunyikan grup dalam-ON kecuali Anda menghubungkan kebijakan keanggotaan.

Performa

Setiap lapisan menambahkan satu kamus OCG dan satu pasangan BDC/EMC di sekitar kontennya. Overhead ini dapat diabaikan. Biayanya berskala mengikuti konten di dalam lapisan, bukan jumlah lapisan, sehingga tetap jauh di bawah anggaran 2000 ms / 64 MB.

Catatan keamanan

Visibilitas konten opsional bergantung pada kepatuhan pembaca, bukan kontrol akses. Menyembunyikan lapisan tidak mengenkripsi, meredaksi, atau menghapus kontennya. Siapa pun dapat mengaktifkan kembali lapisan tersebut atau mengekstrak byte-nya. Jangan pernah menggunakan lapisan tersembunyi untuk menyembunyikan teks rahasia; sebagai gantinya, hilangkan kontennya sepenuhnya. Resep ini tidak mengurai masukan apa pun dan tidak melakukan permintaan jaringan apa pun.

Kesesuaian

Pernyataan	Spesifikasi	Klausul
Kamus OCG memiliki `Type /OCG`.	ISO 32000-2	§8.11.2
`Name` OCG adalah label wajib yang ditampilkan kepada pengguna.	ISO 32000-2	§8.11.2
Konten opsional diapit di antara `BDC`/`EMC` dengan tag `OC`.	ISO 32000-2	§8.11.3.2
Kebijakan OCMD adalah AllOn/AnyOn/AnyOff/AllOff (baku AnyOn).	ISO 32000-2	§8.11.4.3

Profil keterulangan — struktural. Atom /ID trailer dan tanggal berubah pada setiap penyimpanan. Harness menghapus atom-atom tersebut dan membandingkan struktur yang dinormalisasi oleh qpdf. Resep ini menjelaskan bagaimana NextPDF menghasilkan struktur tersebut. Resep ini tidak menyatakan kesesuaian ISO 32000-2 secara umum.

Konteks komersial

Tidak berlaku. Grup konten opsional adalah kapabilitas Core tanpa pembatas Premium.