Branding — Referensi Mendalam

Sekilas

Halaman ini adalah referensi mendalam untuk modul NextPDF\Enterprise\Branding. Modul ini menandai keluaran evaluasi dan membiarkan keluaran berbayar tidak tersentuh. Sebuah BrandingMode yang diresolusi dari lisensi memilih sebuah strategi; BrandingApplicator menerapkan strategi yang diresolusi ke byte PDF yang telah di-render. Di bawah lisensi berbayar transformasinya adalah identitas: keluaran tidak berubah byte demi byte, tanpa perlu perubahan kode. Untuk alur kerja evaluasi, baca halaman kapabilitas Branding terlebih dahulu.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tingkat Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Subsistem ini membawa kode kapabilitas enterprise.branding khusus karena mengatur perilaku evaluasi di semua edisi. Mode branding diresolusi dari envelope lisensi yang ditandatangani saat runtime; tidak ada flag aplikasi yang memilihnya. Lisensi berbayar meresolusi mode ke None dan tidak pernah menghasilkan keluaran ber-branding. Tidak ada build produksi untuk beralih.

Permukaan API publik

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
BrandingMode	—	None ('none'): tanpa modifikasi	—	—	Enum berbasis string; EvaluationWatermark ('evaluation') mengaktifkan evaluation branding.
BrandingStrategy	—	Kontrak yang dikonsumsi oleh titik integrasi	—	—	Interface; pemanggil tidak pernah bercabang pada BrandingMode secara langsung.
BrandingStrategy::isActive	—	false untuk strategi null, true untuk strategi evaluasi	bool	—	false berarti setiap metode lain mengembalikan nilai identitas.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (point)	String kosong saat tidak aktif; operator watermark diagonal saat aktif	string	—	Stream mengasumsikan sebuah resource font /helvetica pada halaman.
BrandingStrategy::decorateProducer	string $producer	Identitas saat tidak aktif; menambahkan sufiks evaluasi saat aktif	string	—	Sufiks default: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identitas saat tidak aktif; menambahkan prefiks evaluasi di depan saat aktif	string	—	Subject kosong menghasilkan penanda yang telah di-trim.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Memetakan None ke NullBrandingStrategy, EvaluationWatermark ke EvaluationBrandingStrategy	BrandingStrategy	—	Statis; config null menggunakan default.
EvaluationBrandingConfig::__construct	Enam parameter bernama opsional (text, suffix, prefix, size, gray, angle)	Default: 48 pt, gray 0.85, 45 derajat	Instance	InvalidArgumentException pada text kosong, ukuran font non-positif, atau gray di luar 0.0–1.0	final readonly; immutable.
EvaluationBrandingStrategy	EvaluationBrandingConfig opsional	Menerapkan watermark dan dekorasi metadata	—	—	final readonly; mengimplementasikan BrandingStrategy.
NullBrandingStrategy	—	Identitas pada setiap metode	—	—	Dipilih di bawah lisensi berbayar.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Strategi tidak aktif: input dikembalikan byte demi byte; aktif: satu incremental update ditambahkan	string	BrandingApplicationException ketika branding aktif tidak dapat diterapkan dengan aman	Transformasi byte murni dan deterministik.
BrandingApplicationException	—	Sinyal kegagalan terminal, fail-closed	—	—	Membawa SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); factory unsupportedStructure().

Signature entry-point

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

Kontrak perilaku

Resolusi mode dan strategi. Status lisensi — bukan kode aplikasi — yang memilih BrandingMode. BrandingStrategyFactory::create memetakan None ke NullBrandingStrategy dan EvaluationWatermark ke EvaluationBrandingStrategy. Titik integrasi mengonsumsi interface BrandingStrategy dan tidak pernah memeriksa mode secara langsung, sehingga logika branding tetap terpusat. Di bawah lisensi berbayar strategi null yang dipilih dan keluarannya identik dengan keluaran yang dihasilkan tanpa subsistem branding sama sekali.

Pembuatan watermark. buildPageWatermark memancarkan operator content-stream PDF untuk satu halaman: sebuah graphics state terisolasi (q/Q), font Helvetica standard-14 melalui nama resource /helvetica, mode rendering teks fill, dan sebuah matriks rotasi yang menempatkan teks secara diagonal melintasi pusat halaman. Gaya default adalah teks 48 pt pada level gray 0.85, dirotasi 45 derajat. Pemusatan mengaproksimasi lebar teks berdasarkan jumlah glyph — grapheme cluster ketika intl dimuat, code point Unicode melalui mbstring jika tidak, panjang byte sebagai fallback terakhir. Tidak ada advance width per-glyph yang dikonsultasikan secara desain. Teks watermark di-escape sebagai literal string PDF sesuai ISO 32000-2:2020 §7.3.4.2 (backslash dan tanda kurung).

Dekorasi metadata. decorateProducer menambahkan sufiks producer ke nilai /Producer. decorateSubject menambahkan prefiks subject di depan nilai /Subject; subject kosong menghasilkan penanda yang telah di-trim, sehingga dokumen tanpa metadata subject tetap ditandai.

Penerapan byte. BrandingApplicator::apply adalah konsumen terminal dari kontrol branding. Dengan strategi tidak aktif ia mengembalikan input byte demi byte. Dengan strategi aktif ia menambahkan satu incremental update dalam bentuk yang didefinisikan oleh ISO 32000-2:2020 §7.5.6: byte asli tetap utuh, dan body yang ditambahkan berisi objek Info yang didekorasi (menggunakan kembali nomor objek yang ada), satu content stream watermark ditambah satu objek halaman yang diperbarui per halaman, dan sebuah cross-reference stream baru (/Type /XRef, /W [1 4 2]) yang /Prev-nya menunjuk kembali ke startxref sebelumnya. Transformasi ini murni dan deterministik untuk input dan konfigurasi tertentu.

Kontrak fail-closed. Ketika strategi aktif, input harus dapat di-brand: sebuah header %PDF-, tanpa entri /Encrypt, tanpa object stream (/ObjStm), sebuah cross-reference-stream tail, dan sebuah resource font /helvetica yang dapat diresolusi dari setiap halaman. Pelanggaran apa pun memunculkan BrandingApplicationException alih-alih mengembalikan byte yang tidak ter-brand. Pemanggil harus memperlakukan exception sebagai terminal dan tidak boleh meng-commit byte asli yang tidak ditandai.

Kasus tepi & mode kegagalan

• Keluaran ber-branding berarti status lisensi bergaya evaluasi. Itu mencerminkan status lisensi, bukan cacat.
• Watermark berada di tengah dan diagonal secara desain. Ia tidak dapat disetel untuk penggunaan produksi; lisensi berbayar menghapusnya sepenuhnya.
• EvaluationBrandingConfig menolak teks watermark kosong, ukuran font non-positif, dan level gray di luar 0.0–1.0 dengan InvalidArgumentException.
• Strategi aktif yang tidak menghasilkan perubahan Producer, Subject, atau watermark ditolak dengan BrandingApplicationException alih-alih memancarkan byte yang tampak berbayar.
• Halaman tanpa /MediaBox yang dapat dipakai (tidak ada atau diwarisi) diberi watermark pada default ISO 216 A4 sebesar 595.276 × 841.890 point.
• /Contents dalam bentuk referensi tunggal dan array keduanya didukung; referensi watermark ditambahkan terakhir agar ia digambar di atas. Halaman tanpa /Contents menerima satu.
• Nilai string Info di-round-trip dalam representasi aslinya: string heksadesimal (UTF-16BE) tetap heksadesimal, literal string tetap literal. Kunci yang tidak ada ditambahkan, di-encode heksadesimal ketika nilainya mengandung karakter non-ASCII.
• Dokumen terenkripsi ditolak: menulis ulang objek string di bawah /Encrypt akan memerlukan kunci enkripsi dokumen.
• Kegagalan membawa kode stabil SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) sehingga pipeline yang mengonsumsi dapat melakukan dead-letter dan audit terhadap keluaran yang tidak dapat di-brand.
• Modul ini tidak melakukan operasi kriptografis. Verifikasi tanda tangan envelope lisensi merupakan tanggung jawab subsistem licensing; lihat referensi mendalam Licensing.

Konformitas

Klaim	Standar	Klausul
Incremental update menambahkan perubahan ke akhir file dan membiarkan konten asli tetap utuh.	ISO 32000-2	§7.5.6
Cross-reference section pada update hanya mencakup objek yang berubah, dan trailer yang ditambahkan membawa entri Prev yang melokasi cross-reference section sebelumnya.	ISO 32000-2	§7.5.6
Literal string ditulis dalam tanda kurung; tanda kurung yang tidak seimbang dan reverse solidus memerlukan penanganan escape.	ISO 32000-2	§7.3.4.2

Semua klausul diparafrasekan; NextPDF tidak mereproduksi teks normatif. NextPDF tidak membuat klaim sertifikasi. Applicator menulis incremental update dalam bentuk ISO 32000-2 yang dikutip sebagai pernyataan kapabilitas; ia bukan writer yang tersertifikasi atau divalidasi secara independen. Halaman ini menjelaskan perilaku runtime saja. Ia tidak memberikan jaminan, tidak ada pernyataan tentang kelayakan atau efek hukum, dan bukan merupakan nasihat hukum; ketentuan evaluasi atau langganan didefinisikan sepenuhnya oleh perjanjian lisensi.

Catatan pengembangan

• BrandingMode, BrandingStrategy, kedua strategi, dan config membawa @since 3.0.0; BrandingApplicator dan BrandingApplicationException membawa @since 3.1.0.
• Subsistem ini tidak melakukan panggilan jaringan. Applicator hanya membaca field struktural yang ditulis ulangnya: string dictionary Info, dictionary halaman, dan cross-reference tail.
• Envelope lisensi adalah artefak yang ditandatangani yang tanda tangan penerbitnya diverifikasi oleh runtime. Provisioning, pembaruan, dan penyimpanan aman lisensi adalah tanggung jawab operator.
• Semua tipe konkret adalah final; strategi dan config juga readonly. Bangun instance config baru untuk mengubah gaya watermark.
• BrandingStrategy::isActive() yang mengembalikan false menjamin nilai identitas dari setiap metode lain; pemanggil dapat melakukan short-circuit padanya untuk performa.
• Stream watermark mereferensikan nama resource /helvetica. Core mendaftarkan resource ini untuk branding-nya sendiri; integrasi yang menonaktifkan branding Core harus memastikan resource tersebut ada.
• Applicator tidak menghitung digest apa pun; pemanggil me-digest ulang byte yang ber-branding sebelum meng-commit-nya.
• Detail mekanisme internal tetap berada di dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung saja. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Branding — halaman kapabilitas untuk subsistem evaluation-branding.
• Trial dan Evaluation Branding — kisah evaluasi end-to-end.
• Licensing — Referensi Mendalam
• Ringkasan Enterprise