compat-legacy configureren

In het kort

De adapter biedt u drie configuratievlakken:

Strict mode — een auditschakelaar die stilzwijgend parameterverlies omzet in excepties. Deze is standaard uitgeschakeld.
Legacy-constanten — de TCPDF K_* / PDF_*-constanten, automatisch gedefinieerd met de standaardwaarden van 6.2.13 zodat legacy-code die ze leest, blijft werken.
AdaptationConfig — een modern, immutable configuratieobject dat configuratie op basis van constanten vervangt.

De meeste documentinstellingen configureert u nog steeds via de TCPDF-methoden die u al aanroept (SetMargins(), SetFont(), enzovoort). De onderstaande secties behandelen alleen wat specifiek voor de compatibiliteitslaag is.

Strict mode

Strict mode is de belangrijkste instelling voor een migratie. Deze verandert niets aan de weergegeven uitvoer, maar bepaalt of een aanroep die het TCPDF-gedrag niet kan reproduceren expliciet faalt of stilzwijgend degradeert.

<?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

Deze uitkomsten worden geverifieerd door tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Modus	Aangeroepen methode met stilzwijgend genegeerde parameters	Resultaat
Uit (standaard)	e.g. `Image()` met extra parameters	Wordt uitgevoerd; genegeerde parameters hebben geen effect
Aan	dezelfde aanroep	Werpt `TcpdfNotImplementedException` met vermelding van de genegeerde parameters
Aan	een stilzwijgend-negerende methode aangeroepen met uitsluitend ondersteunde parameters	Werpt geen exceptie (e.g. `SetProtection([], 'u', 'o', 0, [])`)

Strict mode is additief. Wanneer een methode een parameter ondersteunt, vindt de delegatie nog steeds plaats; strict mode voegt alleen een exceptiecontrole toe voor parameters die worden weggelaten. Gebruik deze in een aparte continuous integration (CI)-taak of een eenmalige auditronde, niet in productie. Dit volgt het fail-explicitly-principe uit de foutafhandeling van Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 (clausule reference_id vastgelegd in de RAG-sidecar): een aanroeper moet kunnen zien wanneer zijn intentie niet is gehonoreerd.

Lever geen productiecode op waarin strict mode aanstaat. Een stilzwijgend genegeerde parameter is een probleem in de ontwikkelaarservaring, geen runtimefout, en een exceptie in een productie-renderpad is erger dan gedegradeerde uitvoer. Voer de audit uit, herstel de problemen en schakel strict mode daarna uit — zie /integrations/tcpdf-compat/migration/.

Legacy TCPDF-constanten

Legacy TCPDF leest configuratie uit de constanten K_* en PDF_*. De adapter definieert deze bij constructie automatisch alleen als ze nog niet zijn gedefinieerd, met de standaardwaarden van TCPDF 6.2.13. Als uw applicatie een constante al definieert (bijvoorbeeld een aangepaste K_PATH_FONTS), blijft uw waarde behouden.

Een selectie van standaardwaarden (volledige lijst: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Constante	Standaard	Opmerking
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	gebruikerseenheden
`PDF_MARGIN_TOP`	`27`	gebruikerseenheden
`PDF_MARGIN_BOTTOM`	`25`	gebruikerseenheden
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	gehard — altijd false; markup kan geen PHP-uitvoering activeren
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	gehard — `Error()` werpt altijd een exceptie; nooit `die()`
`K_TIMEZONE`	`UTC`

Om veiligheidsredenen zijn twee daarvan bewust vastgezet; ze kunnen niet via configuratie worden versoepeld: K_TCPDF_CALLS_IN_HTML is altijd false, en K_TCPDF_THROW_EXCEPTION_ERROR is in de praktijk altijd true. Als legacy-code afhankelijk is van een van deze twee onveilige legacy-gedragingen, moet die code worden gewijzigd — zie /integrations/tcpdf-compat/security-and-operations/.

Definieer aangepaste constanten vóór de eerste constructie van de adapter, doorgaans in de bootstrap van uw applicatie:

<?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.

Het moderne AdaptationConfig-object

Als u niet op globale constanten wilt vertrouwen, gebruik dan het immutable configuratie-value-object NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Het is final readonly en elk veld heeft standaard de waarde van TCPDF 6.2.13. U kunt het construeren met alleen de velden die u wilt wijzigen.

U kunt het ook opbouwen uit de legacy-constanten die op dat moment zijn gedefinieerd:

<?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 is het migratiedoel voor configuratie. Naarmate u aanroeplocaties naar de moderne API verplaatst, vervangt u constantenopzoekingen door expliciete AdaptationConfig-velden. De configuratie blijft getypeerd en lokaal in plaats van globaal.

Resolutievolgorde van configuratie

Bij het construeren van een document lost de adapter de configuratie in deze volgorde op. Latere stappen overschrijven eerdere stappen niet:

Constructorargumenten (orientation, unit, format, …) — hoogste prioriteit voor de waarden die zij dekken.
Reeds bestaande, door de applicatie gedefinieerde legacy-constanten.
Standaardconstanten van TCPDF 6.2.13, automatisch gedefinieerd door LegacyDefaults voor elke constante die nog niet is gedefinieerd.

De constructorargumenten unicode, encoding en diskcache worden geaccepteerd voor signatuurcompatibiliteit en hebben geen effect. NextPDF is altijd Unicode en UTF-8 en heeft geen paginacache op schijf. De constructorvlag pdfa wordt eveneens geaccepteerd, maar PDF/A-archiveringsconformiteit vereist een commerciële editie (zie /integrations/tcpdf-compat/security-and-operations/).

Zie ook

src/Compat/Tcpdf/Config/LegacyDefaults.php — gezaghebbende standaardwaarden voor constanten
src/Compat/Tcpdf/Config/AdaptationConfig.php — modern configuratieobject
/integrations/tcpdf-compat/migration/ — configuratie loskoppelen van globale constanten
/integrations/tcpdf-compat/security-and-operations/ — de twee geharde, niet-configureerbare vlaggen