compat-legacy konfigurieren

Auf einen Blick

Der Adapter bietet drei Konfigurationsbereiche:

Strict-Modus – ein Audit-Schalter, der stillen Parameterverlust zu geworfenen Exceptions macht. Standardmäßig deaktiviert.
Legacy-Konstanten – die TCPDF-Konstanten K_* / PDF_*, die automatisch mit den Standardwerten von 6.2.13 definiert werden, damit Legacy-Code, der sie liest, weiterhin funktioniert.
AdaptationConfig – ein modernes, unveränderliches Konfigurationsobjekt, das die konstantenbasierte Konfiguration ersetzt.

Den Großteil der Dokumentkonfiguration nehmen Sie weiterhin über dieselben TCPDF-Methoden vor, die Sie ohnehin schon aufrufen (SetMargins(), SetFont() und so weiter). Die folgenden Abschnitte behandeln das, was speziell für die Kompatibilitätsschicht gilt.

Strict-Modus

Der Strict-Modus ist die wichtigste Einstellung für die Migration. Er beeinflusst die gerenderte Ausgabe nicht. Er steuert, ob ein Aufruf, für den sich das TCPDF-Verhalten nicht reproduzieren lässt, sichtbar fehlschlägt oder still degradiert.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

Verhalten, das in tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php abgesichert ist:

Modus	Aufgerufene Methode	Ergebnis
Aus (Standard)	z. B. `Image()` mit zusätzlichen Parametern	Läuft; ignorierte Parameter haben keine Wirkung
Ein	derselbe Aufruf	Wirft `TcpdfNotImplementedException` und benennt die ignorierten Parameter
Ein	eine Methode, die Parameter still ignorieren kann, aber nur mit unterstützten Parametern aufgerufen wird	Wirft nicht (z. B. `SetProtection([], 'u', 'o', 0, [])`)

Der Strict-Modus ist additiv. Wenn eine Methode einen Parameter tatsächlich unterstützt, wird dieser weiterhin delegiert; der Strict-Modus ergänzt lediglich eine Exception-Prüfung für Parameter, die verworfen werden. Empfohlen ist der Einsatz in einem dedizierten CI-Job oder einem einmaligen Audit-Durchlauf, nicht in der Produktion. Die Begründung folgt dem Prinzip des expliziten Fehlschlagens aus der OWASP-ASVS-5.0-Fehlerbehandlung (Klausel reference_id im RAG-Sidecar vermerkt): Eine aufrufende Stelle muss erkennen können, wann ihre Absicht nicht erfüllt wurde.

Setzen Sie keinen Produktionscode mit aktiviertem Strict-Modus ein. Ein still ignorierter Parameter betrifft die Entwicklererfahrung, ist aber kein Laufzeitfehler, und eine Exception in einem Produktions-Renderpfad ist gravierender als eine degradierte Ausgabe. Auditieren, beheben, dann ausschalten – siehe /integrations/tcpdf-compat/migration/.

Legacy-TCPDF-Konstanten

Legacy-TCPDF liest die Konfiguration aus den Konstanten K_* und PDF_*. Der Adapter definiert sie bei der Konstruktion automatisch, aber nur, wenn sie nicht bereits definiert sind, und verwendet dabei die Standardwerte von TCPDF 6.2.13. Wenn Ihre Anwendung eine Konstante bereits definiert (zum Beispiel ein angepasstes K_PATH_FONTS), bleibt Ihr Wert erhalten.

Ausgewählte Standardwerte (vollständige Liste: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Konstante	Standardwert	Hinweis
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	Benutzereinheiten
`PDF_MARGIN_TOP`	`27`	Benutzereinheiten
`PDF_MARGIN_BOTTOM`	`25`	Benutzereinheiten
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	gehärtet – immer false; Markup kann keine PHP-Ausführung auslösen
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	gehärtet – `Error()` wirft immer; niemals `die()`
`K_TIMEZONE`	`UTC`

Aus Sicherheitsgründen sind zwei davon bewusst festgelegt und können nicht über die Konfiguration gelockert werden: K_TCPDF_CALLS_IN_HTML ist immer false, und K_TCPDF_THROW_EXCEPTION_ERROR ist faktisch immer true. Wenn Legacy-Code auf ein solches unsicheres Legacy-Verhalten angewiesen ist, muss dieser Code geändert werden – siehe /integrations/tcpdf-compat/security-and-operations/.

Wenn Sie eigene Konstanten setzen möchten, definieren Sie sie vor der ersten Konstruktion des Adapters (typischerweise im Bootstrap Ihrer Anwendung):

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

Das moderne AdaptationConfig-Objekt

Für Code, der ohne globale Konstanten auskommen soll, stellt das Paket ein unveränderliches Konfigurationswertobjekt bereit, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Es ist final readonly; jedes Feld nimmt standardmäßig den Wert von TCPDF 6.2.13 an. Sie können es problemlos nur mit den Feldern konstruieren, die Sie ändern möchten.

Sie können es auch aus den aktuell definierten Legacy-Konstanten erzeugen:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

AdaptationConfig ist das Migrationsziel für die Konfiguration. Während Sie Aufrufstellen auf die moderne API umstellen, ersetzen Sie Konstanten-Lookups durch explizite AdaptationConfig-Felder, sodass die Konfiguration typisiert und lokal vorliegt statt global.

Reihenfolge der Konfigurationsauflösung

Wenn der Adapter ein Dokument konstruiert, wird die Konfiguration in folgender Reihenfolge aufgelöst (spätere Schritte überschreiben frühere nicht):

Konstruktorargumente (orientation, unit, format, …) – höchste Priorität für die Werte, die sie abdecken.
Bereits vorhandene, von der Anwendung definierte Legacy-Konstanten.
Die Standardkonstanten von TCPDF 6.2.13, die von LegacyDefaults für jede noch nicht definierte Konstante automatisch definiert werden.

Die Konstruktorargumente unicode, encoding und diskcache werden aus Gründen der Signaturkompatibilität akzeptiert und haben keine Wirkung. NextPDF arbeitet immer mit Unicode und UTF-8 und verwendet keinen Seiten-Cache auf der Festplatte. Das Konstruktorflag pdfa wird ebenfalls akzeptiert, aber die Archivkonformität gemäß PDF/A erfordert eine kommerzielle Edition (siehe /integrations/tcpdf-compat/security-and-operations/).

Siehe auch

src/Compat/Tcpdf/Config/LegacyDefaults.php – maßgebliche Standardwerte der Konstanten
src/Compat/Tcpdf/Config/AdaptationConfig.php – modernes Konfigurationsobjekt
/integrations/tcpdf-compat/migration/ – Konfiguration aus globalen Konstanten heraus verlagern
/integrations/tcpdf-compat/security-and-operations/ – die beiden gehärteten, nicht konfigurierbaren Flags