Pro edycja

Compliance — pełna dokumentacja referencyjna

Na pierwszy rzut oka

Moduł Compliance łączy trzy niezależne powierzchnie w NextPDF\Pro\Compliance:

Raportowanie znaczników języka — fasada ścisłej polityki /Lang PDF/UA-2 oraz ustrukturyzowany reporter zdarzeń zgodności w kształcie PSR-3.
Obsługa e-faktur — walidacja Factur-X 1.08 / ZUGFeRD 2.4 względem modelu semantycznego EN 16931 oraz emisja hybrydowego PDF/A-3.
Proweniencja — osadzanie i wyodrębnianie dostarczonych przez wywołującego magazynów manifestów C2PA przez utwardzony na ataki parser JUMBF; synteza twierdzeń pozostaje bramkowana jako podgląd.

Moduł raportuje to, co sprawdza. Nie certyfikuje dokumentów i nie wykonuje podpisywania kryptograficznego.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się przy kopercie licencyjnej poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Nie istnieje flaga licencyjna dla poszczególnych funkcji. Jest to funkcja edycji Pro. Eksperymentalny konstruktor twierdzeń C2PA dodatkowo wymaga jawnego włączenia w środowisku (zobacz Przypadki brzegowe i tryby awarii).

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się błędem	Uwagi
`LangComplianceReporter::warn()` / `::error()`	`string $tag, string $reason, ?string $clauseReference = null`	Emituje jeden ustrukturyzowany rekord JSON na każde zdarzenie znacznika języka przez logger PSR-3	`void`	`JsonException`, jeśli kodowanie rekordu do JSON się nie powiedzie	`warn` = odrzucenie w trybie lax; `error` = odrzucenie w trybie strict
`LangComplianceReporter::reportException()`	`InvalidBcp47TagException $exception, string $severity = 'error'`	Wyodrębnia znacznik i powód z wyjątku; deleguje do `warn()` lub `error()`	`void`	Jak wyżej	Ścieżka wygody
`LangComplianceReporter::buildRecord()`	`string $severity, string $tag, string $reason, ?string $clauseReference = null`	Buduje tablicę rekordu bez logowania	`array`	Nie zgłasza wyjątku	Do niestandardowych ujść, np. podsumowań JSON per plik
`ConformancePolicy::default()`	`?LoggerInterface $logger = null`	Ścisła polityka UA-2: źle sformułowane lub niezarejestrowane znaczniki `/Lang` są odrzucane	`self`	Nie zgłasza wyjątku	Domyślne ustawienie v5.0 jest ścisłe
`ConformancePolicy::fromCore()`	`CoreConformancePolicy $core, ?LoggerInterface $logger = null`	Opakowuje istniejącą politykę Core bez zmian; żadna oś nie jest przełączana	`self`	Nie zgłasza wyjątku	Preferuj `default()` dla ścisłej postawy
`ConformancePolicy::withStrictUa2()`	`bool $enabled`	Zwraca kopię z ustawioną osią ścisłą; wyłączenie emituje `notice` PSR-3	`self`	Nie zgłasza wyjątku	Przestarzała rezygnacja; cel usunięcia `6.0.0`
`ConformancePolicy::isStrictUa2()` / `::mode()`	—	Odczytuje bazową politykę Core	`bool` / `ConformanceMode`	Nie zgłasza wyjątku	—
`EInvoiceValidator::validate()`	`string $pdfPath`	Pełny potok: kontrola opakowania PDF/A-3, wyodrębnienie załącznika, wykrycie profilu, reguły EN 16931, Schematron	`EInvoiceValidationResult`	Podklasa `EInvoiceException` przy błędzie we/wy, źle sformułowanej strukturze PDF lub awarii narzędzi	Zamrożony interfejs SPI; poprawnie sformułowany plik PDF niebędący e-fakturą zwraca wynik, nigdy nie zgłasza wyjątku
`EInvoiceXmlValidator::validate()`	`string $xmlPayload, ValidatorContext $context`	Wstępna kontrola strukturalna plus głęboki semantyczny korpus reguł EN 16931 na ładunku CII	kontraktowy `ValidationResult`	Nie zgłasza wyjątku dla niepoprawnego wejścia; odrzucenie ujawnia się jako nieudany wynik z ustaleniami	Konkretny walidator międzypoziomowy; wejście bramkowane przez `XmlGuard`
`EInvoiceValidationResult::isValid()`	—	Prawda tylko wtedy, gdy opakowanie, specyfikacja załącznika, profil i składnia są spełnione oraz nie istnieje naruszenie FATAL	`bool`	Nie zgłasza wyjątku	Sama pusta lista naruszeń nie oznacza poprawności
`EInvoiceValidationResult::notAnEInvoice()`	—	Deterministyczny wynik: wszystko null, wszystko false	`self`	Nie zgłasza wyjątku	Fabryka dla przypadku „nie jest fakturą hybrydową”
`EInvoiceProfile`	enum oparty na łańcuchach	Przypadki `MINIMUM`, `BASIC_WL`, `BASIC`, `EN16931`, `EXTENDED`, oparte na URN-ach BT-24	—	—	`isEn16931Conformant()` zwraca false dla `MINIMUM` i `BASIC_WL`
`EInvoiceSyntax`	enum oparty na łańcuchach	Przypadki `UN_CEFACT_CII`, `UBL_INVOICE`, `UBL_CREDIT_NOTE`	—	—	Tylko CII jest `isFacturXEligible()`; UBL jest tylko dla walidatora
`BusinessRuleViolation`	`string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null`	Niezmienny DTO naruszenia	—	—	Rodziny identyfikatorów reguł `BR-`, `BR-CO-`, `BR-CL-`, `BR-DEC-`, `BR-FXEXT-`
`BusinessRuleSeverity`	enum oparty na łańcuchach	`FATAL` unieważnia fakturę; `WARNING` sygnalizuje problem jakościowy	—	—	Odzwierciedla poziomy Schematron EN 16931
`FacturXEmbedder::embed()`	zobacz blok sygnatury	Dołącza strumień pliku osadzonego, filespec i XMP do źródła PDF/A; przepisuje xref	`void`	`EInvoiceException` przy źle sformułowanym XML, nieczytelnym źródle, brakującym katalogu, źródle ze strumieniem obiektów lub strumieniem xref, lub niepowodzeniu zapisu wyjścia	Plik źródłowy pozostaje nienaruszony
`FacturXEmbedderOptions::default()`	—	`/AFRelationship /Alternative`, nazwa pliku `factur-x.xml`, typ `INVOICE`, wersja `1.0`	`self`	Nie zgłasza wyjątku	Domyślne wartości spełniają niemiecki mandat i pozostają akceptowane we Francji
`FacturXEmbedderOptions::withRelationship()` / `::withFilename()`	`string`	Zwraca kopię z zastosowanym nadpisaniem	`self`	`InvalidArgumentException` poza zbiorami akceptacji	Relacje: `Source`, `Data`, `Alternative`; nazwy plików obejmują `zugferd-invoice.xml` i `xrechnung.xml`
`FacturXEmbedderOptions::withDocumentType()`	`string $documentType`	Zwraca kopię z nadpisaniem typu dokumentu XMP	`self`	Nie zgłasza wyjątku	Wartości nie są defensywnie wyliczane
`FacturXContractEmbedder::embed()`	`string $pdfBytes, string $xmlPayload, EmbedderOptions $options`	Adapter bajt-wejście, bajt-wyjście nad `FacturXEmbedder` przez krótko żyjące pliki tymczasowe	`string`	`EInvoiceException`; profil `XRECHNUNG` jest odrzucany jako dostępny tylko w Enterprise	Międzypoziomowa implementacja `EmbedderInterface`
`C2paManifestEmbedder::embed()`	`string $pdfBytes, ManifestStore $store`	Osadza bajtową serializację magazynu w lokalizacji profilu	`string`	`C2paException` przy dowolnym niepowodzeniu osadzania	Zamrożony interfejs SPI; tylko bajty, bez we/wy
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	Parsuje osadzony magazyn przez utwardzony parser JUMBF	`ManifestStore\|null`	Podklasa `C2paException`, gdy magazyn jest obecny, ale narusza limit utwardzenia	Null sygnalizuje brak; brak nigdy nie zgłasza wyjątku
`ManifestStore::fromBoxes()` / `::empty()`	`list<JumbfBox>` / —	Buduje niezmienny obiekt wartości magazynu	`self`	Nie zgłasza wyjątku	Kolejność ramek jest istotna dla równości w cyklu round-trip
`ManifestStore::toBytes()` / `::isEmpty()` / `::size()`	—	Serializuje ramki główne; pusty magazyn serializuje się do pustego łańcucha	`string` / `bool` / `int`	Nie zgłasza wyjątku	—
`JumbfBoxParser::parse()`	`string $bytes`	Parsuje ramki JUMBF na poziomie głównym przy twardych limitach	`list<JumbfBox>`	`MalformedJumbfException`, `JumbfBombException`, `JumbfCycleDetectedException`, `JumbfDepthExceededException`	Limity: głębokość 8, 64 MiB na ramkę, 128 MiB łącznie, `MAX_CHILDREN_PER_SUPERBOX` 4096
`JumbfBox::superbox()` / `::leaf()`	`string $tbox, …`	Buduje zweryfikowaną ramkę; `toBytes()` przechodzi round-trip przez parser	`self`	`MalformedJumbfException`, gdy TBox nie ma dokładnie 4 bajtów	—
`C2paCapabilityStatus::current()` / `::summary()`	—	Raportuje dojrzałość możliwości C2PA, obecnie `preview-draft`	`self` / `string`	Nie zgłasza wyjątku	Sprawdzalny maszynowo znacznik podglądu
`Feature::PREVIEW_C2PA_DRAFT->isEnabled()`	—	Odczytuje środowisko procesu przy każdym wywołaniu; włącza tylko dosłowna wartość `'1'`	`bool`	Nie zgłasza wyjątku	Zmienna środowiskowa `NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT`
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes, string $producer`	Buduje magazyn manifestów przypięty do wersji roboczej z jednym twierdzeniem powiązania skrótu SHA-256	`ManifestStore`	Konstruktor zgłasza `LogicException`, gdy flaga podglądu jest wyłączona	Podgląd; format transmisji przypięty do migawki wersji roboczej; brak emisji podpisu twierdzenia

Sygnatury punktów wejścia, dosłownie:

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

Kontrakt zachowania

Raportowanie znaczników języka. LangComplianceReporter emituje jeden ustrukturyzowany rekord JSON na każde zdarzenie znacznika języka PDF/UA-2. Każdy rekord niesie stały dyskryminator zdarzenia, wagę (warn dla odrzucenia w trybie lax, error dla odrzucenia w trybie strict), wadliwy znacznik dosłownie, czytelny maszynowo powód, sparsowane składowe znacznika (lub null, gdy znacznik nie spełnia gramatyki kształtu RFC 5646), odniesienie do klauzuli ISO 14289-2 §8.4.4 oraz znacznik czasu UTC z mikrosekundami. JSON podróżuje jako treść komunikatu PSR-3; ujścia niżej w potoku parsują pole komunikatu bezpośrednio. ConformancePolicy to fasada Premium nad polityką zgodności Core. Jej ustawienie domyślne stosuje ścisłą obsługę języka UA-2 i odrzuca źle sformułowany lub niezarejestrowany znacznik docierający do /Lang. Pomocnik rezygnacji withStrictUa2(false) przywraca dotychczasowe zachowanie lax i loguje powiadomienie PSR-3, gdy efektywna wartość faktycznie się zmienia. NextPDF oznacza ten pomocnik jako przestarzały od v5.0 z celem usunięcia 6.0.0. Aby migrować: zaudytuj korpus pod kątem źle sformułowanych wartości /Lang za pomocą composer pdfua2:audit-lang-tags <pdf-or-dir>, popraw je, a następnie usuń wywołanie rezygnacji.

Obsługa e-faktur. EInvoiceValidator to zamrożony kontrakt SPI dla walidacji hybrydowego PDF: kontrola opakowania PDF/A-3, wyodrębnienie załącznika /AF, wykrycie profilu z identyfikatora specyfikacji BT-24, silnik reguł biznesowych EN 16931 oraz przebieg Schematron. Poprawnie sformułowany plik PDF inny niż Factur-X zwraca EInvoiceValidationResult::notAnEInvoice() zamiast zgłaszać wyjątek; tylko błędy we/wy, źle sformułowana struktura PDF lub awarie narzędzi podnoszą podklasę EInvoiceException. EInvoiceXmlValidator to konkretny międzypoziomowy walidator XML: bramkuje wejście przez Core XmlGuard, uruchamia wstępną kontrolę strukturalną oraz głęboki semantyczny korpus reguł EN 16931 i zawodzi bezpiecznie — błędy silnika ujawniają się jako ustalenia błędów, nigdy jako ciche przejścia. FacturXEmbedder przekształca źródło PDF/A w hybrydowy PDF/A-3: dołącza strumień pliku osadzonego, filespec z konfigurowalnym /AFRelationship oraz pakiet rozszerzenia XMP Factur-X, a następnie przepisuje klasyczną tablicę odniesień krzyżowych. Zarówno tablica /AF katalogu, jak i drzewo nazw /Names /EmbeddedFiles odwołują się do załącznika, więc czytniki dziedziczące ZUGFeRD go rozwiązują.

Proweniencja. C2paManifestEmbedder osadza dostarczony przez wywołującego magazyn manifestów C2PA w ciągu bajtów PDF lub jeden wyodrębnia. ManifestStore to niezmienny obiekt wartości przekraczający granicę. Spoina jest tylko bajtowa i neutralna wobec dostawcy: nie syntetyzuje twierdzeń, nie pobiera odniesień URI ani nie rozwiązuje powiązań skrótów oraz nie wykonuje żadnych operacji we/wy sieci ani systemu plików. extract() zwraca null przy braku i jest tani na plikach PDF bez magazynu. Każde niepuste wyodrębnienie przeszło już limity utwardzenia JumbfBoxParser.

Ten moduł raportuje to, co sprawdza. Nie certyfikuje dokumentu, nie czyni go prawnie wiążącym ani nie gwarantuje, że jakikolwiek wynik spełnia regulację. Walidator e-faktur nie jest walidatorem organu podatkowego i wyklucza rozszerzenia krajowe (na przykład włoskie SDI, francuskie Chorus Pro, niemieckie XRechnung). Jak stanowi EN 16931-1, wystawca faktury pozostaje odpowiedzialny za spełnienie reguł odpowiednich przepisów. Obsługa standardu nie jest zgodnością z nim. Skonsultuj się ze swoim zespołem ds. zgodności w sprawie wystarczalności regulacyjnej.

Przypadki brzegowe i tryby awarii

Poprawnie sformułowany plik PDF inny niż Factur-X zwraca wynik „nie jest e-fakturą”; nie zgłasza wyjątku.
Pusta lista naruszeń reguł biznesowych sama w sobie nie oznacza, że dokument jest poprawny; obowiązują też kontrole opakowania i załącznika.
FacturXEmbedder zawodzi bezpiecznie na źródłach używających skompresowanych strumieni obiektów (/Type /ObjStm) lub strumieni odniesień krzyżowych (/Type /XRef, hybrydowy /XRefStm). Najpierw zapisz takie źródła ponownie z klasyczną tablicą odniesień krzyżowych.
Ładunki XML są bramkowane przez Core XmlGuard: deklaracje DOCTYPE lub encji, nadmiernie duże wejście oraz niepoprawny UTF-8 są odrzucane z EInvoiceException na ścieżce osadzania lub jako nieudany wynik na ścieżce walidatora.
FacturXContractEmbedder odrzuca profil XRECHNUNG głośno zamiast po cichu go degradować; emisja XRechnung to funkcja Enterprise.
C2paManifestEmbedder::extract() odróżnia brak (null) od zniekształcenia (podklasa C2paException nazywająca naruszony niezmiennik: źle sformułowana struktura, bomba rozmiaru lub liczby, cykl przesunięć, głębokość zagnieżdżenia).
Konstrukcja ExperimentalC2paEmbedder zgłasza LogicException, chyba że flaga środowiskowa podglądu jest równa '1'. Jego format transmisji jest przypięty do migawki wersji roboczej C2PA i może się zmienić bez powiadomienia; nie emituje podpisu twierdzenia. Ta funkcja pozostaje podglądem, dopóki profil C2PA PDF się nie zamrozi.
Rezygnacja na rzecz lax dla ścisłego UA-2 jest przestarzała; migruj do ścisłego ustawienia domyślnego (zobacz Kontrakt zachowania).
Ten moduł nie wykonuje podpisywania kryptograficznego. Podpisywanie twierdzeń C2PA i powiernictwo kluczy są poza zakresem; zobacz moduł Security w zakresie zachowania podpisywania w trybie FIPS.

Konformancja

Zachowanie	Odniesienie	Status
Deklaracja języka naturalnego (`/Lang`)	ISO 14289-2:2024 §8.4.4	Sprawdzane / raportowane
Model semantyczny faktury podstawowej	EN 16931-1:2026	Sprawdzane (wystawca pozostaje odpowiedzialny)
Pliki powiązane / strumienie plików osadzonych	ISO 32000-2:2020 §14.13.2	Emitowane (`/AF`, `/EF`, `/Params`)
Relacja załącznika i reguły kontenera	Factur-X 1.08 §3.1, §6.2	Emitowane / sprawdzane (domyślnie `/AFRelationship /Alternative`)
Magazyn manifestów C2PA / JUMBF	C2PA 2.1 §11.1	Osadzanie / wyodrębnianie obsługiwane; synteza twierdzeń w podglądzie

To rejestruje specyfikacje, względem których zbudowano moduł, oraz to, co sprawdza lub emituje. Nie jest to deklaracja certyfikacji ani wystarczalności regulacyjnej. NextPDF nie posiada certyfikacji dla tych standardów.

Uwagi deweloperskie

Kształt rekordu reportera jest stabilnym kontraktem; reguły alertowania niżej w potoku mogą przypinać się do stałego dyskryminatora zdarzenia.
Wyłączenie ścisłego UA-2 emituje widoczne w telemetrii powiadomienie o przestarzałości tylko wtedy, gdy efektywna wartość się zmienia; ponowne potwierdzenie bieżącej wartości jest ciche.
Embedder Factur-X zachowuje bajty źródłowe dosłownie i dołącza nowe obiekty; dąży do zachowania zgodności PDF/A-3, ale nie waliduje ponownie. Przepuść wyjście przez zewnętrzny walidator PDF/A dla twardego poświadczenia.
Spoina C2PA zamraża pięć niezmienników: brak importów firm trzecich, kontrakt tylko bajtowy, brak we/wy, wyodrębnianie null przy braku oraz brak syntezy twierdzeń w warstwie stabilnej.
Limity JumbfBoxParser są publicznymi stałymi; wymiaruj akceptowane wejścia względem nich zamiast ponownie wyprowadzać limity.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.