Evidence — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die ausführliche Referenz für das Modul NextPDF\Enterprise\Evidence. Das Modul versiegelt Validierungsbefunde in ein unveränderliches EvidencePackage, exportiert es als deterministisches JSON mit einem stabilen SHA-256-Digest, persistiert es über einen austauschbaren Store-Vertrag und verfolgt Regressionen zwischen Läufen mit ContinuousMonitor. Das Modul verarbeitet Befunde, die von den Validierungs- und Compliance-Oberflächen erzeugt werden; es führt selbst keine Konformitätsprüfungen durch. Für eine Anleitung zum Arbeitsablauf lesen Sie zuerst die Evidence-Funktionsseite.

Verfügbarkeit & Lizenzierung

Diese Funktion wird mit NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und aktiviert sich mit einer Lizenzhülle der Enterprise-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Die Oberfläche wird über die Fähigkeit enterprise.compliance.evidence lizenziert; eine verweigerte Berechtigung verweigert die Funktion. Core und Pro erzeugen Befunde und Berichte; das Versiegeln von Befunden in ein unveränderliches, deterministisches, optional mit Zeitstempel versehenes Paket mit Regressionsverfolgung hat keine Entsprechung auf der Core- oder Pro-Stufe.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Verdrahtet Store und Exporter	EvidencePortal	Nichts deklariert	Beide Kollaborateure sind injizierbar
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Zählt bestanden/durchgefallen, versiegelt ein Paket mit frischer UUID-ID und Wanduhr-generatedAt, persistiert es	EvidencePackage	Nichts deklariert	Persistiert über store(), nicht persistImmutable()
EvidencePortal::getEvidence	string $documentHash	Zuletzt gespeichertes Paket für den Hash	?EvidencePackage	Nichts deklariert	null, wenn keines gespeichert ist
EvidencePortal::getHistory	string $documentHash	Vollständige Historie, neueste zuerst	list<EvidencePackage>	Nichts deklariert	Die Reihenfolge liefert der Store
EvidencePortal::exportAsJson	EvidencePackage $package	Delegiert an den Exporter	non-empty-string	JsonException	Gleiche Bytes wie EvidenceExporter::toJson
EvidencePackage::__construct	acht benannte Parameter, siehe Codeblock	Unveränderliches Wertobjekt	EvidencePackage	Nichts deklariert	Zähler werden nicht gegen $records validiert
EvidencePackage::allPassed	keine	failedCount === 0	bool	Nichts deklariert	true für ein leeres Paket; prüfen Sie gegen totalFindings
EvidencePackage::passRate	keine	passedCount / totalFindings	float	Nichts deklariert	0.0, wenn totalFindings === 0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Unveränderliches Ergebnis einer einzelnen Richtlinienprüfung	EvidenceRecord	Nichts deklariert	Alle Eigenschaften sind public readonly
EvidenceExporter::toJson	EvidencePackage $package	JSON mit fester Schlüsselreihenfolge; nicht escapte Schrägstriche und Unicode	non-empty-string	JsonException	Die Schlüsselreihenfolge ist tragend
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 über die toJson()-Bytes	non-empty-string (64 Hex)	JsonException	Stabil pro Paket
EvidenceStoreInterface::store	EvidencePackage $package	Hängt an; Historie pro Dokument-Hash ist erlaubt	void	Implementierungsdefiniert	Append-only-Semantik erforderlich
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	WORM-Schreibvorgang, sofern das Backend ihn unterstützt	void	Implementierungsdefiniert	Nicht-WORM-Backends verhalten sich wie store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Aktuellstes Paket für den Hash	?EvidencePackage	Implementierungsdefiniert
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Alle Pakete für den Hash, neueste zuerst	list<EvidencePackage>	Implementierungsdefiniert
EvidenceStoreInterface::count	keine	Gesamtzahl der gespeicherten Pakete	int<0, max>	Implementierungsdefiniert
InMemoryEvidenceStore	Klasse	Array-gestützter Store für Tests und Entwicklung	n. z.	n. z.	Nicht dauerhaft; keine WORM-Semantik
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Verdrahtet den Store	ContinuousMonitor	Nichts deklariert
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Vergleicht durchgefallene Richtliniennamen gegen das gespeicherte aktuellste Paket	MonitorResult	Nichts deklariert	Die erste Prüfung behandelt jeden aktuellen Fehlschlag als neu
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Fällig, wenn keine frühere Evidenz vorliegt, das Intervall verstrichen ist oder die gespeicherte Evidenz in der Zukunft datiert ist	bool	Nichts deklariert	Ausfallsicher bei Uhrabweichung
MonitorResult::__construct	acht benannte Parameter, siehe Codeblock	Unveränderliches Vergleichsergebnis	MonitorResult	Nichts deklariert	Enthält beide Pakete und checkedAt
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Konfigurations-Wertobjekt	MonitorSchedule	Nichts deklariert	Aufbewahrung und Alarmierung werden vom Host erzwungen
MonitorFrequency	String-basiertes Enum	Fälle Daily, Weekly, Monthly	n. z.	n. z.	Hintergrundwerte daily, weekly, monthly
MonitorFrequency::intervalSeconds	keine	Intervall pro Fall: 86400, 604800, 2592000	positive-int	Nichts deklariert	Monthly sind feste 30 Tage

Einstiegspunkt-Signaturen

final class EvidencePortal
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
        private readonly EvidenceExporter $exporter,
    )

    public function generateEvidence(string $documentHash, array $records, ?string $tsaTimestamp = null): EvidencePackage

    public function getEvidence(string $documentHash): ?EvidencePackage

    public function getHistory(string $documentHash): array

    public function exportAsJson(EvidencePackage $package): string
}

final readonly class EvidencePackage
{
    public function __construct(
        public string $packageId,
        public string $documentHash,
        public array $records,
        public int $totalFindings,
        public int $passedCount,
        public int $failedCount,
        public DateTimeImmutable $generatedAt,
        public ?string $tsaTimestamp = null,
    )

    public function allPassed(): bool

    public function passRate(): float
}

final readonly class EvidenceRecord
{
    public function __construct(
        public string $policyName,
        public bool $passed,
        public string $details,
        public string $validatorVersion,
        public DateTimeImmutable $timestamp,
    )
}

final readonly class EvidenceExporter
{
    public function toJson(EvidencePackage $package): string

    public function exportHash(EvidencePackage $package): string
}

interface EvidenceStoreInterface
{
    public function store(EvidencePackage $package): void;

    public function persistImmutable(EvidencePackage $package): void;

    public function findByDocumentHash(string $documentHash): ?EvidencePackage;

    public function findAllByDocumentHash(string $documentHash): array;

    public function count(): int;
}

final class ContinuousMonitor
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
    )

    public function check(EvidencePackage $currentEvidence, string $documentHash): MonitorResult

    public function isDue(string $documentHash, MonitorSchedule $schedule): bool
}

final readonly class MonitorSchedule
{
    public function __construct(
        public MonitorFrequency $frequency,
        public int $retentionDays = 90,
        public bool $alertOnNewIssues = true,
    )
}

enum MonitorFrequency: string
{
    case Daily = 'daily';
    case Weekly = 'weekly';
    case Monthly = 'monthly';

    public function intervalSeconds(): int
}

Verhaltensvertrag

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage ist der Einstiegspunkt für die Versiegelung. Von außen beobachtbare Regeln:

1. Zusammenstellung. generateEvidence zählt bestandene und durchgefallene Datensätze und setzt totalFindings auf ihre Summe. Es weist eine frische UUID der Version 4 als packageId zu, stempelt generatedAt mit der Wanduhr, persistiert das Paket über EvidenceStoreInterface::store und gibt es zurück. Die Datensatzliste wird in der gegebenen Reihenfolge unverändert eingebettet.
2. Unveränderlichkeit. EvidencePackage ist final readonly und wird nach der Konstruktion nie mutiert; es eignet sich für WORM-Speicherung. allPassed() ist failedCount === 0. passRate() ist passedCount / totalFindings und 0.0, wenn totalFindings === 0.
3. Deterministischer Export. EvidenceExporter::toJson gibt die Hülle und jeden Datensatz mit einer festen, handgeschriebenen Schlüsselreihenfolge aus; die Datensatzabfolge folgt dem Paket. Die Kodierung ist strikt und wirft bei einem Fehler, wobei Schrägstriche und Unicode nicht escapt bleiben (JSON_UNESCAPED_SLASHES). Zeitstempel werden mit DateTimeInterface::RFC3339_EXTENDED serialisiert, der erweiterten RFC-3339-Form mit Sekundenbruchteilen. exportHash gibt den 64-stelligen SHA-256-Hex-Digest über genau diese Bytes zurück. Dasselbe Paket ergibt immer denselben Digest, auf jedem Host, zu jeder Zeit. Das erneute Erzeugen von Evidenz für dasselbe Dokument ergibt eine neue packageId und generatedAt und damit einen neuen Digest: Der Determinismus gilt pro Paket, nicht pro Dokument.
4. Der Zeitstempel ist ein Nachweis der Zeit, kein Urteil. Ein Paket kann ein optionales, vom Aufrufer geliefertes RFC-3161-Token (base64-kodiert) tragen. Das Token bindet das Paketdatum an einen Zeitwert. Das Modul bettet es als undurchsichtige Zeichenkette ein; es ruft keine Token ab, parst und verifiziert sie nicht und bürgt nicht für die TSA. Die Token-Verifizierung obliegt den Signature- und Security-Modulen.
5. Regressionsverfolgung. ContinuousMonitor::check lädt das gespeicherte aktuellste Paket für den Dokument-Hash und vergleicht die eindeutigen durchgefallenen Richtliniennamen. Probleme werden kategorisiert als newIssues (jetzt durchgefallen, vorher nicht), resolvedIssues (vorher durchgefallen, jetzt nicht) und unchangedIssues (in beiden durchgefallen). hasChanges ist nur dann true, wenn neue oder behobene Probleme existieren; unveränderte Fehlschläge allein melden false. Bei einer ersten Prüfung ist jeder aktuelle Fehlschlag neu.
6. Planung. ContinuousMonitor::isDue gibt true zurück, wenn keine Evidenz für den Hash existiert, wenn die seit dem gespeicherten generatedAt verstrichene Zeit das Frequenzintervall des Zeitplans erreicht oder wenn die gespeicherte Evidenz relativ zum abfragenden Host in der Zukunft datiert ist. Der zukunftsdatierte Fall ist ausfallsicher: schlimmstenfalls eine zusätzliche Neuprüfung, nie eine versäumte.
7. Store-Vertrag. Implementierungen von EvidenceStoreInterface müssen Append-only-Semantik unterstützen; mehrere Pakete pro Dokument-Hash bilden die Historie, neueste zuerst. persistImmutable zielt auf WORM-fähige Backends; Nicht-WORM-Implementierungen müssen sich exakt wie store verhalten.

Grenzfälle & Fehlermodi

• Ein leeres Paket meldet allPassed() true und passRate() 0.0. Prüfen Sie gegen totalFindings > 0, bevor Sie ein Paket als bestanden behandeln.
• Die direkte Konstruktion von EvidencePackage validiert die Zähler nicht gegen $records. Verwenden Sie das Portal oder halten Sie die Zähler selbst konsistent.
• generateEvidence persistiert vor der Rückgabe. Führen Sie ContinuousMonitor::check mit dem neuen Paket aus, bevor Sie es persistieren; eine Prüfung nach der Persistierung vergleicht das Paket mit sich selbst und meldet keine Änderungen.
• exportHash deckt genau die toJson-Bytes ab. Ein Digest, der von einem anderen Serialisierer, einer anderen Schlüsselreihenfolge oder einer anderen Escape-Richtlinie neu berechnet wird, stimmt nicht überein.
• MonitorFrequency::Monthly ist ein festes 30-Tage-Fenster, kein Kalendermonat.
• MonitorSchedule::$retentionDays und $alertOnNewIssues sind Konfigurationswerte, die für Host-Scheduler mitgeführt werden. Das Modul löscht nie Evidenz und sendet nie Alarme.
• InMemoryEvidenceStore ist für Tests und Entwicklung. Pakete gehen beim Prozessende verloren, und sein persistImmutable hat keine WORM-Semantik.
• Die details-Zeichenketten von Datensätzen werden wortgetreu exportiert; der Exporter redigiert nicht. Halten Sie Geheimnisse und regulierte personenbezogene Daten aus details heraus. Ansässigkeit, Aufbewahrung und Zugriffskontrolle folgen der Store-Implementierung des Betreibers.
• Das Argument tsaTimestamp wird als undurchsichtige Zeichenkette angenommen. Ein fehlerhaftes Token wird unverändert eingebettet und tritt erst bei der nachgelagerten Verifizierung zutage.

Verhalten im FIPS-Modus

Dieses Modul berechnet SHA-256-Digests und bettet ein vom Aufrufer geliefertes RFC-3161-Token ein. Es führt keine Signierung und keine Schlüsselverwahrung durch. Das Verhalten im FIPS-Modus wird von den Modulen Security und Signature bestimmt.

Konformität

Aussage	Standard	Klausel
Ein Zeitstempel-Token weist aus, dass ein Datum zu einem bestimmten Zeitpunkt existierte.	IETF RFC 3161	§2
Exportierte Zeitstempel verwenden das Internet-Datum/Zeit-Profil von ISO 8601 mit Sekundenbruchteilen.	IETF RFC 3339	§5.6
In eine PDF eingebettetes Validierungsmaterial gehört zum Document Security Store; diese Oberfläche ist die des Signature-Moduls, nicht dieses hier.	ISO 32000-2:2020	§12.8.4

Alle Klauseln sind paraphrasiert; NextPDF reproduziert keinen normativen Text. NextPDF erhebt keinen Zertifizierungsanspruch. Die Evidenzerfassung unterstützt Audit-Arbeitsabläufe; sie ist keine rechtliche Bescheinigung und keine Audit-Zertifizierung. Ein Zeitstempel-Token ist ausschließlich ein Nachweis der Zeit, und dieses Modul behauptet nicht, dass irgendein Inhalt konform ist. Gültigkeit und Konformität bleiben Eigenschaften der fertigen Datei zusammen mit einem Validator. Diese Referenz ist keine Rechtsauskunft; ziehen Sie Ihre eigenen Compliance- und Rechtsberater hinzu.

Entwicklungshinweise

• Der Modulquelltext trägt @since 2.2.0; diese Referenz dokumentiert die Oberfläche, wie sie in nextpdf/enterprise 3.1.0 ausgeliefert wird.
• Alles läuft im Prozess auf Ihrem Host. Das Modul führt keine Netzwerk-E/A durch und kontaktiert selbst nie eine TSA.
• Die Schlüsselreihenfolge des Array-Literals des Exporters ist per Design tragend. Ihre Umsortierung würde exportHash verändern und zuvor gespeicherte Digests entwerten; der Quelltext verbietet dies.
• packageId ist eine UUID der Version 4, zusammengesetzt aus der Ausgabe von \random_bytes(16); Bezeichner sind eindeutig, aber nicht reproduzierbar.
• Die dauerhafte Persistierung liefert der Host. Die WORM-Durchsetzung und die Zugriffskontrolle liegen in der Verantwortung des Betreibers; der In-Memory-Store ist die einzige mitgelieferte Implementierung.
• MonitorResult ist ein final readonly Wertobjekt; seine acht Eigenschaften sind public, einschließlich checkedAt, der Wanduhrzeit der Prüfung.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich das von außen beobachtbare Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Evidence — die Funktionsseite mit Anleitung zum Arbeitsablauf.
• Validation — Ausführliche Referenz
• Compliance — Ausführliche Referenz
• AST-Audit-Trail — Ausführliche Referenz
• Spezifikationen: PAdES