Compliance — Referensi Mendalam

Sekilas pandang

Modul Compliance menggabungkan tiga permukaan independen di bawah NextPDF\Pro\Compliance:

• Pelaporan language-tag — facade kebijakan /Lang PDF/UA-2 yang ketat plus reporter peristiwa-kepatuhan terstruktur berbentuk PSR-3.
• Penanganan e-invoice — validasi Factur-X 1.08 / ZUGFeRD 2.4 terhadap model semantik EN 16931, dan emisi PDF/A-3 hibrida.
• Provenans — menyematkan dan mengekstrak manifest store C2PA yang disuplai pemanggil melalui parser JUMBF yang diperkeras secara adversarial; sintesis klaim tetap tergerbang-preview.

Modul ini melaporkan apa yang diperiksanya. Ia tidak mensertifikasi dokumen dan tidak melakukan penandatanganan kriptografis.

Ketersediaan & lisensi

Kapabilitas ini dikirim dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur. Ini adalah kapabilitas edisi Pro. Builder klaim C2PA eksperimental selain itu memerlukan opt-in environment eksplisit (lihat Kasus tepi & mode kegagalan).

Permukaan API publik

composer require nextpdf/pro:^3

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
LangComplianceReporter::warn() / ::error()	string $tag, string $reason, ?string $clauseReference = null	Mengeluarkan satu rekaman JSON terstruktur per peristiwa language-tag melalui logger PSR-3	void	JsonException jika rekaman gagal encoding JSON	warn = penolakan mode-lax; error = penolakan mode-strict
LangComplianceReporter::reportException()	InvalidBcp47TagException $exception, string $severity = 'error'	Mengekstrak tag dan alasan dari eksepsi; mendelegasikan ke warn() atau error()	void	Seperti di atas	Jalur kemudahan
LangComplianceReporter::buildRecord()	string $severity, string $tag, string $reason, ?string $clauseReference = null	Membangun array rekaman tanpa mencatat	array	Tidak melempar	Untuk sink khusus seperti ringkasan JSON per-berkas
ConformancePolicy::default()	?LoggerInterface $logger = null	Kebijakan UA-2 ketat: tag /Lang yang malformasi atau tidak terdaftar ditolak	self	Tidak melempar	Baku v5.0 adalah ketat
ConformancePolicy::fromCore()	CoreConformancePolicy $core, ?LoggerInterface $logger = null	Membungkus kebijakan Core yang ada apa adanya; tidak ada sumbu yang dibalik	self	Tidak melempar	Utamakan default() untuk postur ketat
ConformancePolicy::withStrictUa2()	bool $enabled	Mengembalikan salinan dengan sumbu ketat diatur; menonaktifkan mengeluarkan notice PSR-3	self	Tidak melempar	Opt-out deprecated; target penghapusan 6.0.0
ConformancePolicy::isStrictUa2() / ::mode()	—	Membaca kebijakan Core yang mendasari	bool / ConformanceMode	Tidak melempar	—
EInvoiceValidator::validate()	string $pdfPath	Pipeline penuh: pemeriksaan wrapper PDF/A-3, ekstraksi lampiran, deteksi profil, aturan EN 16931, Schematron	EInvoiceValidationResult	Subkelas EInvoiceException saat kegagalan I/O, struktur PDF malformasi, atau kres tooling	Antarmuka SPI beku; PDF non-e-invoice yang well-formed mengembalikan hasil, tidak pernah melempar
EInvoiceXmlValidator::validate()	string $xmlPayload, ValidatorContext $context	Pra-terbang struktural plus korpus aturan semantik-mendalam EN 16931 atas payload CII	kontrak ValidationResult	Tidak melempar untuk input tidak valid; penolakan muncul sebagai hasil gagal dengan temuan	Validator lintas-tier konkret; input digerbang melalui XmlGuard
EInvoiceValidationResult::isValid()	—	Benar hanya ketika wrapper, spek lampiran, profil, sintaks berlaku dan tidak ada pelanggaran FATAL	bool	Tidak melempar	Daftar pelanggaran kosong saja bukanlah validitas
EInvoiceValidationResult::notAnEInvoice()	—	Hasil deterministik semua-null, semua-false	self	Tidak melempar	Factory untuk kasus “bukan faktur hibrida”
EInvoiceProfile	enum berbasis-string	Case MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, didukung URN BT-24	—	—	isEn16931Conformant() false untuk MINIMUM dan BASIC_WL
EInvoiceSyntax	enum berbasis-string	Case UN_CEFACT_CII, UBL_INVOICE, UBL_CREDIT_NOTE	—	—	Hanya CII yang isFacturXEligible(); UBL hanya-validator
BusinessRuleViolation	string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null	DTO pelanggaran imutabel	—	—	Famili rule-id BR-, BR-CO-, BR-CL-, BR-DEC-, BR-FXEXT-
BusinessRuleSeverity	enum berbasis-string	FATAL membatalkan faktur; WARNING menandai masalah kualitas	—	—	Mencerminkan level Schematron EN 16931
FacturXEmbedder::embed()	lihat pagar signature	Menambahkan stream embedded-file, filespec, dan XMP ke sumber PDF/A; menulis ulang xref	void	EInvoiceException saat XML malformasi, sumber tak terbaca, katalog hilang, sumber object-stream atau xref-stream, atau kegagalan tulis output	Berkas sumber dibiarkan utuh
FacturXEmbedderOptions::default()	—	/AFRelationship /Alternative, nama berkas factur-x.xml, tipe INVOICE, versi 1.0	self	Tidak melempar	Baku memenuhi mandat Jerman dan tetap diterima di Prancis
FacturXEmbedderOptions::withRelationship() / ::withFilename()	string	Mengembalikan salinan dengan override diterapkan	self	InvalidArgumentException di luar set penerimaan	Relationship: Source, Data, Alternative; nama berkas termasuk zugferd-invoice.xml dan xrechnung.xml
FacturXEmbedderOptions::withDocumentType()	string $documentType	Mengembalikan salinan dengan override document-type XMP	self	Tidak melempar	Nilai tidak dienumerasi secara defensif
FacturXContractEmbedder::embed()	string $pdfBytes, string $xmlPayload, EmbedderOptions $options	Adapter byte-masuk, byte-keluar atas FacturXEmbedder via berkas temp berumur-pendek	string	EInvoiceException; profil XRECHNUNG ditolak karena hanya-Enterprise	Implementasi EmbedderInterface lintas-tier
C2paManifestEmbedder::embed()	string $pdfBytes, ManifestStore $store	Menyematkan serialisasi byte store pada lokasi profil	string	C2paException saat kegagalan embed apa pun	Antarmuka SPI beku; hanya-byte, tanpa I/O
C2paManifestEmbedder::extract()	string $pdfBytes	Mengurai store tersemat melalui parser JUMBF yang diperkeras	ManifestStore|null	Subkelas C2paException ketika store hadir tetapi melanggar cap pengerasan	Null menandakan ketiadaan; ketiadaan tidak pernah melempar
ManifestStore::fromBoxes() / ::empty()	list<JumbfBox> / —	Membangun value object store imutabel	self	Tidak melempar	Urutan box menanggung-beban untuk kesetaraan round-trip
ManifestStore::toBytes() / ::isEmpty() / ::size()	—	Menserialisasi box root; store kosong menserialisasi ke string kosong	string / bool / int	Tidak melempar	—
JumbfBoxParser::parse()	string $bytes	Mengurai box JUMBF tingkat-root di bawah cap keras	list<JumbfBox>	MalformedJumbfException, JumbfBombException, JumbfCycleDetectedException, JumbfDepthExceededException	Cap: kedalaman 8, 64 MiB per box, 128 MiB total, MAX_CHILDREN_PER_SUPERBOX 4096
JumbfBox::superbox() / ::leaf()	string $tbox, …	Membangun box tervalidasi; toBytes() round-trip melalui parser	self	MalformedJumbfException ketika TBox tidak tepat 4 byte	—
C2paCapabilityStatus::current() / ::summary()	—	Melaporkan kematangan kapabilitas C2PA, saat ini preview-draft	self / string	Tidak melempar	Penanda preview yang dapat diperiksa mesin
Feature::PREVIEW_C2PA_DRAFT->isEnabled()	—	Membaca environment proses pada setiap panggilan; hanya literal '1' yang mengaktifkan	bool	Tidak melempar	Env var NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT
ExperimentalC2paEmbedder::buildManifestStore()	string $sourceBytes, string $producer	Membangun manifest store yang dipatok-draft dengan satu asersi klaim hash-binding SHA-256	ManifestStore	Konstruktor melempar LogicException ketika flag preview mati	Preview; format wire dipatok ke snapshot draft; tidak ada tanda tangan klaim yang dikeluarkan

Signature entry-point, verbatim:

public static function default(?LoggerInterface $logger = null): self
public function withStrictUa2(bool $enabled): self
public function isStrictUa2(): bool

public function validate(string $pdfPath): EInvoiceValidationResult

public function embed(
    string $sourcePdfPath,
    string $xml,
    EInvoiceProfile $profile,
    string $outputPdfPath,
    ?FacturXEmbedderOptions $options = null,
): void

public function embed(string $pdfBytes, ManifestStore $store): string
public function extract(string $pdfBytes): ?ManifestStore

Kontrak perilaku

Pelaporan language-tag. LangComplianceReporter mengeluarkan satu rekaman JSON terstruktur per peristiwa language-tag PDF/UA-2. Setiap rekaman membawa diskriminator peristiwa yang tetap, sebuah severitas (warn untuk penolakan mode-lax, error untuk penolakan mode-strict), tag yang melanggar secara verbatim, alasan yang dapat dibaca mesin, komponen tag yang diurai (atau null ketika tag gagal tata bahasa bentuk RFC 5646), sebuah referensi klausa ISO 14289-2 §8.4.4, dan timestamp UTC dengan mikrodetik. JSON tersebut berjalan sebagai badan pesan PSR-3; sink hilir mengurai field pesan secara langsung. ConformancePolicy adalah facade Premium atas kebijakan konformitas Core. Bakunya menerapkan penanganan bahasa UA-2 yang ketat dan menolak tag yang malformasi atau tidak terdaftar yang mencapai /Lang. Pembantu opt-out withStrictUa2(false) kembali ke perilaku lax warisan dan mencatat sebuah notice PSR-3 ketika nilai efektif benar-benar berubah. NextPDF menandai pembantu tersebut deprecated sejak v5.0 dengan target penghapusan 6.0.0. Untuk bermigrasi: audit korpus untuk nilai /Lang yang malformasi dengan composer pdfua2:audit-lang-tags <pdf-or-dir>, perbaiki, lalu hilangkan panggilan opt-out.

Penanganan e-invoice. EInvoiceValidator adalah kontrak SPI beku untuk validasi PDF-hibrida: pemeriksaan wrapper PDF/A-3, ekstraksi lampiran /AF, deteksi profil dari pengidentifikasi spesifikasi BT-24, mesin aturan-bisnis EN 16931, dan satu lintasan Schematron. PDF non-Factur-X yang well-formed mengembalikan EInvoiceValidationResult::notAnEInvoice() alih-alih melempar; hanya kegagalan I/O, struktur PDF malformasi, atau kres tooling yang memunculkan subkelas EInvoiceException. EInvoiceXmlValidator adalah validator XML lintas-tier konkret: ia menggerbang input melalui XmlGuard Core, menjalankan pra-terbang struktural dan korpus aturan semantik EN 16931 yang mendalam, dan gagal-tertutup — galat mesin muncul sebagai temuan galat, tidak pernah sebagai lolos senyap. FacturXEmbedder mengubah sumber PDF/A menjadi PDF/A-3 hibrida: ia menambahkan stream embedded-file, sebuah filespec dengan /AFRelationship yang dapat dikonfigurasi, dan sebuah paket ekstensi XMP Factur-X, lalu menulis ulang tabel cross-reference klasik. Baik array /AF katalog maupun name tree /Names /EmbeddedFiles mereferensikan lampiran, sehingga pembaca ZUGFeRD warisan menyelesaikannya.

Provenans. C2paManifestEmbedder menyematkan manifest store C2PA yang disuplai pemanggil ke dalam string byte PDF, atau mengekstraknya. ManifestStore adalah value object imutabel yang melintasi batas. Jahitan ini hanya-byte dan netral-vendor: ia tidak mensintesis klaim, mencerna referensi URI, atau menyelesaikan pengikatan hash, dan ia tidak melakukan I/O jaringan atau sistem berkas. extract() mengembalikan null saat gagal-temu dan murah pada PDF tanpa store. Setiap ekstraksi non-null telah lolos cap pengerasan JumbfBoxParser.

Modul ini melaporkan apa yang diperiksanya. Ia tidak mensertifikasi dokumen, menjadikannya mengikat secara hukum, atau menjamin bahwa keluaran apa pun memenuhi suatu regulasi. Validator e-invoice bukan validator otoritas-pajak dan mengecualikan ekstensi nasional (misalnya SDI Italia, Chorus Pro Prancis, XRechnung Jerman). Sebagaimana dinyatakan EN 16931-1, penerbit faktur tetap bertanggung jawab untuk memenuhi aturan legislasi yang relevan. Dukungan terhadap suatu standar bukanlah kesesuaian terhadapnya. Konsultasikan tim kepatuhan Anda untuk kecukupan regulasi.

Kasus tepi & mode kegagalan

• PDF non-Factur-X yang well-formed mengembalikan hasil “bukan e-invoice”; ia tidak melempar.
• Daftar pelanggaran aturan-bisnis yang kosong tidak dengan sendirinya berarti dokumen valid; pemeriksaan wrapper dan lampiran juga berlaku.
• FacturXEmbedder gagal-tertutup pada sumber yang menggunakan object stream terkompresi (/Type /ObjStm) atau cross-reference stream (/Type /XRef, /XRefStm hibrida). Simpan-ulang sumber semacam itu dengan tabel cross-reference klasik terlebih dahulu.
• Payload XML digerbang melalui XmlGuard Core: deklarasi DOCTYPE atau entity, input berukuran-berlebih, dan UTF-8 tidak valid ditolak dengan EInvoiceException pada jalur embed, atau hasil gagal pada jalur validator.
• FacturXContractEmbedder menolak profil XRECHNUNG secara lantang alih-alih menurunkannya secara senyap; emisi XRechnung adalah kapabilitas Enterprise.
• C2paManifestEmbedder::extract() membedakan ketiadaan (null) dari malformasi (subkelas C2paException yang menamai invarian yang dilanggar: struktur malformasi, bomb ukuran atau jumlah, siklus offset, kedalaman nesting).
• Konstruksi ExperimentalC2paEmbedder melempar LogicException kecuali flag environment preview sama dengan '1'. Format wire-nya dipatok ke snapshot draft C2PA dan dapat berubah tanpa pemberitahuan; ia tidak mengeluarkan tanda tangan klaim. Kapabilitas ini tetap preview hingga profil PDF C2PA membeku.
• Opt-out lax UA-2 ketat deprecated; bermigrasilah ke baku ketat (lihat Kontrak perilaku).
• Modul ini tidak melakukan penandatanganan kriptografis. Penandatanganan klaim C2PA dan kustodi kunci berada di luar cakupan; lihat modul Security untuk perilaku penandatanganan mode-FIPS.

Kesesuaian

Perilaku	Acuan	Status
Deklarasi bahasa-alami (/Lang)	ISO 14289-2:2024 §8.4.4	Diperiksa / dilaporkan
Model semantik faktur inti	EN 16931-1:2026	Diperiksa (penerbit tetap bertanggung jawab)
Berkas terasosiasi / stream berkas tersemat	ISO 32000-2:2020 §14.13.2	Dikeluarkan (/AF, /EF, /Params)
Relationship lampiran dan aturan kontainer	Factur-X 1.08 §3.1, §6.2	Dikeluarkan / diperiksa (baku /AFRelationship /Alternative)
Manifest store C2PA / JUMBF	C2PA 2.1 §11.1	Embed / extract didukung; sintesis klaim preview

Ini mencatat spesifikasi yang menjadi acuan pembangunan modul dan apa yang diperiksa atau dikeluarkannya. Ini bukan pernyataan sertifikasi atau kecukupan regulasi. NextPDF tidak memegang sertifikasi untuk standar-standar ini.

Catatan pengembangan

• Bentuk rekaman reporter adalah kontrak stabil; aturan alerting hilir dapat mematok terhadap diskriminator peristiwa yang tetap.
• Menonaktifkan UA-2 ketat mengeluarkan notice deprecation yang terlihat-telemetri hanya ketika nilai efektif berubah; menegaskan-ulang nilai saat ini adalah senyap.
• Embedder Factur-X mempertahankan byte sumber secara verbatim dan menambahkan objek baru; ia bertujuan mempertahankan konformitas PDF/A-3 tetapi tidak memvalidasi-ulang. Salurkan output melalui validator PDF/A eksternal untuk atestasi keras.
• Jahitan C2PA membekukan lima invarian: tanpa impor pihak-ketiga, kontrak hanya-byte, tanpa I/O, ekstraksi null-saat-gagal-temu, dan tanpa sintesis klaim di lapisan stabil.
• Cap JumbfBoxParser adalah konstanta publik; ukur input yang Anda terima terhadapnya alih-alih menurunkan-ulang batas.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas pembantu, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Panduan kapabilitas Compliance
• Preview C2PA
• Security — Referensi Mendalam
• Spesifikasi