compat-legacy yapılandırması

Genel bakış

Bağdaştırıcı size üç yapılandırma yüzeyi sağlar:

1. Katı mod — sessiz parametre kaybını özel durum hâline getiren bir denetim anahtarı. Varsayılan olarak kapalıdır.
2. Eski sabitler — TCPDF K_* / PDF_* sabitleri; bunları okuyan eski kodun çalışmaya devam etmesi için 6.2.13 varsayılanlarıyla otomatik olarak tanımlanır.
3. AdaptationConfig — sabit tabanlı yapılandırmanın yerini alan modern ve değişmez bir yapılandırma nesnesi.

Belge ayarlarının çoğunu, zaten çağırdığınız TCPDF yöntemleriyle yapılandırırsınız (SetMargins(), SetFont() ve benzeri). Aşağıdaki bölümler yalnızca uyumluluk katmanına özgü konuları kapsar.

Katı mod

Katı mod, geçiş sürecindeki en önemli ayardır. Oluşturulan çıktıyı değiştirmez. TCPDF davranışını yeniden üretemeyen bir çağrının görünür biçimde başarısız olup olmayacağını veya sessizce bozulup bozulmayacağını denetler.

examples/config-strict.php

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

Bu sonuçlar tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php tarafından doğrulanır:

Mod	Sessizce yok sayan yöntem çağrısı	Sonuç
Kapalı (varsayılan)	örn. Image() ek parametrelerle	Çalışır; yok sayılan parametrelerin etkisi olmaz
Açık	aynı çağrı	Yok sayılan parametreleri belirten bir TcpdfNotImplementedException oluşturur
Açık	yalnızca desteklenen parametrelerle çağrılan, sessizce yok sayan bir yöntem	Özel durum oluşturmaz (örn. SetProtection([], 'u', 'o', 0, []))

Katı mod ek bir güvence olarak çalışır. Bir yöntem bir parametreyi desteklediğinde çağrı yine de devredilir; katı mod yalnızca atlanan parametreler için özel durum tabanlı bir koruma ekler. Bunu üretimde değil, ayrı bir sürekli tümleştirme (CI) işinde veya tek seferlik bir denetim turunda kullanın. Bu, Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 hata işleme bölümündeki açıkça başarısız olma ilkesini izler (madde reference_id RAG yan dosyasında kayıtlıdır): çağıran taraf, amacının gerçekleşmediğini gözlemleyebilmelidir.

Üretim kodunu katı mod açıkken yayınlamayın. Sessizce yok sayılan bir parametre, bir çalışma zamanı arızası değil, geliştirici deneyimi sorunudur ve bir üretim işleme yolunda oluşan özel durum, bozulmuş çıktıdan daha kötüdür. Denetleyin, düzeltin ve ardından kapatın — bkz. /integrations/tcpdf-compat/migration/.

Eski TCPDF sabitleri

Eski TCPDF, yapılandırmayı K_* ve PDF_* sabitlerinden okur. Bağdaştırıcı bunları, oluşturma sırasında yalnızca henüz tanımlanmamışlarsa TCPDF 6.2.13 varsayılanlarıyla otomatik olarak tanımlar. Uygulamanız bir sabiti zaten tanımlıyorsa (örneğin özel bir K_PATH_FONTS), sizin değeriniz korunur.

Seçili varsayılanlar (tam liste: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Sabit	Varsayılan	Not
PDF_PAGE_FORMAT	A4
PDF_PAGE_ORIENTATION	P
PDF_UNIT	mm
PDF_MARGIN_LEFT / RIGHT	15	kullanıcı birimi
PDF_MARGIN_TOP	27	kullanıcı birimi
PDF_MARGIN_BOTTOM	25	kullanıcı birimi
PDF_FONT_NAME_MAIN	helvetica
PDF_FONT_SIZE_MAIN	10
K_CELL_HEIGHT_RATIO	1.25
K_TCPDF_CALLS_IN_HTML	false	sıkılaştırılmış — her zaman false; biçimlendirme PHP yürütmesini tetikleyemez
K_TCPDF_THROW_EXCEPTION_ERROR	true	sıkılaştırılmış — Error() her zaman özel durum oluşturur; asla şunu yapmaz: die()
K_TIMEZONE	UTC

Bunlardan ikisi güvenlik için bilinçli olarak sabitlenmiştir ve yapılandırma yoluyla gevşetilemez: K_TCPDF_CALLS_IN_HTML her zaman false, K_TCPDF_THROW_EXCEPTION_ERROR ise fiilen her zaman true’tur. Eski kod bu güvensiz eski davranışlardan birine bağlıysa o kodun değişmesi gerekir — bkz. /integrations/tcpdf-compat/security-and-operations/.

Özel sabitleri, ilk bağdaştırıcıyı oluşturmadan önce, genellikle uygulama önyüklemenizde tanımlayın:

examples/config-constants.php

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

Modern AdaptationConfig nesnesi

Genel sabitlere güvenmek istemiyorsanız değişmez yapılandırma değer nesnesi olan NextPDF\Compat\Tcpdf\Config\AdaptationConfig’i kullanın. final readonly olarak tanımlıdır ve her alan varsayılan olarak TCPDF 6.2.13 değerini alır. Bu nesneyi yalnızca değiştirmek istediğiniz alanlarla oluşturabilirsiniz.

Ayrıca bu nesneyi, o anda tanımlı olan eski sabitlerden de oluşturabilirsiniz:

examples/config-adaptation.php

<?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, yapılandırma için geçiş hedefidir. Çağrı noktalarını modern API’ye taşıdıkça sabit aramalarını açık AdaptationConfig alanlarıyla değiştirin. Yapılandırma, genel sabitlere yayılmak yerine tipli ve yerel kalır.

Yapılandırma çözümleme sırası

Bağdaştırıcı bir belge oluşturduğunda yapılandırmayı aşağıdaki sırayla çözümler. Sonraki adımlar önceki adımları geçersiz kılmaz:

1. Yapıcı bağımsız değişkenleri (orientation, unit, format, …) — kapsadıkları değerler için en yüksek önceliğe sahiptir.
2. Önceden var olan, uygulama tarafından tanımlanmış eski sabitler.
3. Henüz tanımlanmamış herhangi bir sabit için LegacyDefaults tarafından otomatik olarak tanımlanan TCPDF 6.2.13 varsayılan sabitleri.

Yapıcı bağımsız değişkenleri unicode, encoding ve diskcache imza uyumluluğu için kabul edilir ve hiçbir etkileri yoktur. NextPDF her zaman Unicode ve UTF-8 kullanır ve diskte sayfa önbelleği tutmaz. pdfa yapıcı bayrağı da kabul edilir, ancak PDF/A arşivleme uygunluğu ticari bir sürüm gerektirir (bkz. /integrations/tcpdf-compat/security-and-operations/).

Ayrıca bkz.

• src/Compat/Tcpdf/Config/LegacyDefaults.php — sabit varsayılanları için yetkili kaynak
• src/Compat/Tcpdf/Config/AdaptationConfig.php — modern yapılandırma nesnesi
• /integrations/tcpdf-compat/migration/ — yapılandırmayı genel sabitlerden taşıma
• /integrations/tcpdf-compat/security-and-operations/ — sıkılaştırılmış, yapılandırılamayan iki bayrak