NextPDF compat-legacy katmanında TCPDF metot kapsamı

Bir bakışta

nextpdf/compat-legacy bir uyumluluk katmanıdır; TCPDF’nin bir çatallaması (fork) ya da davranışı bire bir kopyalamayı garanti eden bir katman değildir. TCPDF 6.x genel metot adlarını, parametre sırasını ve varsayılan değerlerini NextPDF çekirdek motoru üzerinde sunar. Çağrıların çoğu doğrudan bir NextPDF Document işlemine eşlenir. Az sayıdaki metot ise, NextPDF’in dikkate almadığı veya hiçbir etkisi olmayan eski parametreleri kabul eder.

Bu sayfa, metot bazındaki denetimi okuyucular için özetler. Esas alınacak, testle doğrulanmış kapsam matrisi depoda docs/TCPDF_COVERAGE.md dosyasında bulunur. Bu sayfa ile depodaki matris çeliştiğinde, test paketi tarafından doğrulandığı için depodaki matris geçerlidir.

Geçiş yapmadan önce şu tek soruyu yanıtlamak için bu sayfayı kullanın: kod tabanımın çağırdığı her TCPDF metodu için adaptör gerçekte ne yapar?

Kapsam özeti

Denetim, yaklaşık 120 TCPDF 6.x genel metodunu inceledi. Her metot tam olarak dört kategoriden birine yerleştirildi.

Kategori	Sayı	Sizin için anlamı
Yansıtılan — tamamen devredilmiş	94	Çağrı doğrudan bir NextPDF Document metoduna eşlenir. Belgelenen parametreler için davranış uyumludur.
Sessizce yok sayan — kısmi	15	Metot çalışır ve çıktı üretir, ancak bir veya daha fazla TCPDF parametresinin hiçbir etkisi olmaz. Bu, belgelenmiş bir davranış farkıdır.
Gerçeklenmemiş — işlem yapmayan gövde	4	Metot, kaynak uyumluluğu için vardır ancak hiçbir şey yapmaz.
Uygulanamaz	7	TCPDF metodunun PDF çıktısına hiçbir etkisi yoktur; kasıtlı olarak hariç tutulmuştur.
Eklenen modern API kayması metotları	17	Karma API kodunun derlenebilmesi için adaptörde sunulan NextPDF v5.1+ Document metotları. Bunların TCPDF 6.x karşılığı yoktur.

Bu rakamlar docs/TCPDF_COVERAGE.md §Summary kaynağından gelir. Test paketi, matrisi tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php ve tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php ile doğrular.

Sözcük seçimi notu. Bu paket, “doğrudan yerine takılabilen bir çözüm” ya da “%100 TCPDF uyumlu” olma iddiasında değildir. İncelenen ~120 TCPDF metodundan 94’ünü doğrudan devretme yoluyla kapsar. Kalan metotlarda aşağıda açıklanan, belgelenmiş davranış farkları vardır. Doğru tanım, bilinen, test edilmiş bir uyumluluk yüzeyine sahip bir TCPDF uyumlu alternatiftir.

Metot sayıları hakkında bir not

Adaptör, toplamda 273 genel metot sunan 25 tek sorumluluklu concern özelliğinden (src/Compat/Tcpdf/Concerns/) ve TCPDF sınıfının kendisinde bulunan az sayıda yaşam döngüsü ve kaçış yolu metodundan oluşur. Yukarıdaki kapsam kategorileri, adaptörün toplam genel metot sayısını değil, ayrı TCPDF 6.x API yüzeyi metotlarını (~120) sayar. Bu iki sayı farklı şeyleri ölçer: API yüzeyi kapsamı ve gerçekleme boyutu. Paketin README.md dosyası daha küçük bir özellik sayısı veya metot sayısı belirtiyorsa, docs/TCPDF_COVERAGE.md dosyasını ve bu sayfayı esas alın. README özeti, AdaptsDriftV51 özelliğinden öncesine aittir.

1. Yansıtılan metotlar — uyumlu devretme

Doksan dört metot, alt katmandaki NextPDF\Core\Document örneğine doğrudan eşlenir. Motorun camelCase kullandığı yerlerde, PascalCase TCPDF adları camelCase NextPDF adlarına eşlenir. Adaptör, ileri ve geri uyumluluk için her iki yazımı da kabul eder.

Temsili gruplar (tam tablo: docs/TCPDF_COVERAGE.md §1):

TCPDF alanı	Örnek metotlar	Adaptör özelliği
Yaşam döngüsü	Output(), Close(), getPDFData()	AdaptsLifecycle
Sayfalar	AddPage(), getNumPages(), deletePage()	AdaptsPageManagement
Metin	Cell(), MultiCell(), Write(), Text(), Ln()	AdaptsTextOutput
Yazı tipleri	SetFont(), SetFontSize(), AddFont()	AdaptsFonts
Renkler	SetTextColor(), SetDrawColor(), SetFillColor()	AdaptsColors
Çizim	Line(), Rect(), Circle(), Polygon(), Arrow()	AdaptsDrawing
Dönüşümler	Rotate(), Scale(), Translate(), Skew(), Mirror*()	AdaptsTransforms
Gezinme	AddLink(), Annotation(), addTOC()	AdaptsNavigation

Bu metotlarda, NextPDF tarafından belgelenen parametreler için gözlemlenen davranış TCPDF 6.x ile uyumludur. Adaptör, bayt düzeyinde özdeş PDF çıktısı taahhüt etmez. Alt katmandaki motor bağımsız bir PDF 2.0 gerçeklemesidir; bu nedenle görünür sonuç eşdeğer olsa bile baytlar farklı olabilir. Testleriniz işlenen içerik yerine tam PDF baytlarını doğruluyorsa, bu doğrulamaları yeniden temellendirmeyi bekleyin. Önerilen yeniden temellendirme stratejisi için /integrations/tcpdf-compat/migration/ adresine bakın.

2. Sessizce yok sayan metotlar — belgelenmiş davranış farkları

Bu 15 metot çalışır ve çıktı üretir, ancak en az bir TCPDF parametresi kaynak uyumluluğu için kabul edilir ve ardından yok sayılır. Geçiş yapmadan önce bu bölümü okuyun. Bu çağrılar başarısız olmaz; TCPDF’deki özgün karşılıklarından sessizce daha azını yaparlar.

TCPDF metodu	Yok sayılan parametreler	Uyumlu alternatif
Image()	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF image() file, x, y, width, height parametrelerini alır. Tıklanabilir bir görsel için görseli çizin, ardından aynı dikdörtgenin üzerine Document::link() ekleyin. Görsel maskeleme ve alternatif görseller desteklenmez.
writeHTML()	ln, fill, reseth, cell, align	NextPDF writeHtml() yalnızca içerik üzerinde çalışır. Yerleşim denetimi için HTML’yi modern API aracılığıyla konumlandırılmış bir blok içine sarın.
writeHTMLCell()	border (dize biçimi), ln, fill, reseth, autopadding	Genişlik, yükseklik, konum ve boolean kenarlık değeri dikkate alınır; daha zengin hücre yerleşiminin bir karşılığı yoktur.
ImageEps()	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Yalnızca konum ve boyut.
ImageSVG()	link, align, palign, border, fitonpage	Yalnızca konum ve boyut.
SetProtection()	mode (sıfır dışı), pubkeys (boş değil)	NextPDF standart işleyici için her zaman AES-256 kullanır. Sertifika tabanlı şifreleme için adaptörde sunulan modern setPublicKeyEncryption() metodunu kullanın (bkz. /integrations/tcpdf-compat/security-and-operations/).
Bookmark()	style, color, x, isNamedDest	Başlık, düzey ve y konumu dikkate alınır.
setDestination()	page, x	Ad ve y konumu dikkate alınır.
Link()	spaces	TCPDF’ye özgü boşluk izleme; motor karşılığı yoktur.
Annotation()	Subtype dışındaki seçenek anahtarları, spaces	Tür, konum ve metin dikkate alınır.
SetLineStyle()	genişlik dışındaki tire deseni ayrıntıları	Temel çizgi özellikleri eşlenir.
setAlpha()	kısmi karışım modu eşlemesi	Bazı karışım modu adlarının motor karşılığı yoktur.
Polycurve()	tüm parametre listesi	Varsayılan modda işlem yapmaz; motor karşılığı yoktur.
PieSectorXY()	tüm parametre listesi	Kısmi eşleme (merkezden çevreye çizgiler farklıdır).
RoundedRectXY()	köşe başına yarıçap	Yalnızca tek tip köşe yarıçapı.

Adaptörün bu farkları nasıl yüzeye çıkardığı katı moda bağlıdır (bkz. /integrations/tcpdf-compat/configuration/). Geriye dönük uyumlu varsayılan olan katı mod kapalıyken, bu çağrılar sessizce etkisiz kalır. Katı mod açıkken, bir parametreyi yok sayan her çağrı, yok sayılan parametrelerin tam listesiyle ve bir geçiş ipucuyla birlikte TcpdfNotImplementedException fırlatır. Katı mod bir denetim aracıdır, bir üretim ayarı değildir.

Katı mod tasarımı, bir çağıranın niyetinin dikkate alınmadığı durumu gözlemleyebilmesi gerektiği ilkesini izler. OWASP ASVS 5.0 §16.5.3, uygulamaların zarif ve güvenli bir biçimde başarısız olması ve fail-open durumlarını önlemesi gerektiğini belirtir. Sessiz parametre kaybı bir güvenlik açığından çok bir geliştirici deneyimi tuzağıdır, ancak aynı açıkça başarısızlık ilkesi geçerlidir. Sabitlenmiş madde özeti, sayfa ön bilgisindeki citations alanındadır.

3. Gerçeklenmemiş metotlar — işlem yapmayan gövdeler

Eski kaynak kodun derlenebilmesi için dört metot sağlanır, ancak gövdeleri hiçbir şey yapmaz. Katı mod açıkken üçü TcpdfNotImplementedException fırlatır. Dördüncüsü (Open()), eski koddan her zaman güvenle kaldırabileceğiniz için asla istisna fırlatmayan, bilinçli ve güvenli bir işlem yapmayan metottur.

TCPDF metodu	Davranış	Yerine kullanım
setSignature()	İşlem yapmaz (işleme alınabilecek hiçbir şey saklamaz). Katı modda fırlatır.	Dijital imzalama, ticari bir NextPDF sürümü gerektirir. Bir CertificateInfo değer nesnesiyle modern imza API’sini kullanın; bkz. /integrations/tcpdf-compat/security-and-operations/.
addEmptySignatureAppearance()	İşlem yapmaz. Katı modda fırlatır.	Ticari sürüm kapısı setSignature() ile aynıdır.
endPage()	İşlem yapmaz. Katı modda fırlatır.	NextPDF sayfa yaşam döngüsünü otomatik olarak yönetir. Çağrıyı kaldırın.
Open()	Güvenli, işlem yapmayan metot. Asla fırlatma yapmaz.	NextPDF belgeyi otomatik olarak açar. Çağrıyı kaldırmak her zaman güvenlidir.

İmzalama, bu adaptör aracılığıyla çekirdek motorda kullanılamaz. Adaptör, motora devreden modern bir imza giriş noktası sunar. Temel imza desteği, ticari bir sürümle sınırlandırılmıştır. Bu belge, herhangi bir sürüm için uzun vadeli doğrulama veya zaman damgalı imza profilleri hakkında hiçbir iddiada bulunmaz. Kesin, ihtiyatlı ifade için /integrations/tcpdf-compat/security-and-operations/ adresine bakın.

4. Uygulanamaz metotlar

Yedi TCPDF metodunun PDF çıktısına hiçbir etkisi yoktur ve kasıtlı olarak hariç tutulmuştur. Bunları güvenle çağırabilirsiniz.

TCPDF metodu	Neden hariç tutuldu
setDocCreationTimestamp() / setDocModificationTimestamp()	Durum adaptörde tutulur ancak belgenin XMP üst verisine bağlanmaz. Çıktıda görünmez.
setSRGBmode()	NextPDF renk yönetimi bu bayraktan bağımsızdır.
setPDFVersion()	NextPDF PDF sürümünü kendi conformance/output profilinden seçer; doğrudan bir ayarlayıcı yoktur. Adaptör bir uyarı yayar ve devam eder.
setDocInfoUnicode()	NextPDF her zaman Unicode’dur; bu bayrak tasarım gereği işlem yapmaz.
setDefaultMonospacedFont()	Motor karşılığı yoktur; bunun yerine HTML/CSS biçimlendirmesi geçerlidir.
setFontSubsetting()	NextPDF gömülü yazı tiplerini her zaman alt küme olarak gömer; bu bayrak fiilen her zaman açıktır.

PDF sürümü motor tarafından sabitlenir. Çıktı PDF 2.0 olarak yazılır (ISO 32000-2). ISO 32000-2 §7.5.2, uyumlu bir yazıcının belge sürümünü — dosya başlığında veya katalog Version girdisinde — 2.0 olarak belirttiğini şart koşar. Ayrıca, bir dosyayı kaydetmenin dosyanın sürümünü düşürmediğini şart koşar. Bu, adaptörün davranışıyla uyumludur: setPDFVersion('1.4') gibi çağrılar, bu adaptör aracılığıyla daha eski bir PDF sürümünü hedef alamaz. Sabitlenmiş madde özeti, sayfa ön bilgisindeki citations alanındadır.

5. Modern API kayması metotları

TCPDF API’sini modern API ile birleştiren kodun yine de derlenebilmesi için NextPDF çekirdeğinin v5.1+ sürümünden on yedi metot adaptörde sunulur (AdaptsDriftV51 özelliği). Bunların TCPDF 6.x karşılığı yoktur. Örnekler: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Bunları TCPDF uyumluluk sözleşmesinin bir parçası olarak değil, modern API olarak ele alın.

6. Kullanımdan kaldırma ve yerine kullanım rehberliği

Kodunuz şunu çağırıyorsa…	Durum	Bunu yapın
Error()	Davranış değişti (sertleştirildi)	Adaptör, TCPDF’nin die() çağrısını fırlatılan bir RuntimeException ile değiştirir. Riskli çağrıları try/catch ile sarın; süreç sonlandırmasına güvenmeyin.
setPDFVersion()	Uygulanamaz	Kaldırın. Çıktı her zaman PDF 2.0’dir.
setUserRights()	PDF 2.0’de kullanımdan kaldırıldı	Kaldırın. Çağrı bir E_USER_DEPRECATED uyarısı yayar ve yok sayılır.
setSignature()	Çekirdekte gerçeklenmemiş	Ticari bir sürümde modern imza API’sine geçin.
Image(...) ek parametrelerle	Sessizce yok sayan	file, x, y, w, h ile sınırlayın; tıklanabilir görseller için Document::link() ekleyin.
endPage() / Open()	Gerçeklenmemiş / işlem yapmaz	Kaldırın.

7. Güvenli geçiş adımları

1. Paketi kurun ve mevcut test paketinizi kod değişikliği olmadan adaptöre karşı çalıştırın. Bkz. /integrations/tcpdf-compat/install/ ve /integrations/tcpdf-compat/quickstart/.
2. Katı modu özel bir denetim çalışmasında etkinleştirin (üretimde değil): $pdf->setStrictMode(true);. Her TcpdfNotImplementedException istisnasını toplayın. Her biri, yok sayılan parametrelerin tam adlarını ve bir geçiş ipucunu belirtir.
3. Her istisna fırlatma noktası için, yok sayılan parametreyi atmayı ya da o çağrıyı $pdf->getDocument() aracılığıyla modern API’ye taşımayı seçin.
4. Tam PDF baytlarını doğrulayan testleri yeniden temellendirin; bunun yerine işlenen içeriği veya yapısal özellikleri doğrulayın.
5. Katı modu kapatın ve denetlenen kod yolunu dağıtın. Yeniden düzenleme yaparken gerilemeleri yakalamak için düzenli bir katı mod CI işi tutun.

Kodla birlikte tam yordam: /integrations/tcpdf-compat/migration/.

Ayrıca bkz.

• docs/TCPDF_COVERAGE.md — esas alınacak, testle doğrulanmış kapsam matrisi (depo içi)
• /integrations/tcpdf-compat/migration/ — uçtan uca TCPDF’den NextPDF’e geçiş stratejisi
• /integrations/tcpdf-compat/configuration/ — katı mod ve adaptör yapılandırması
• /integrations/tcpdf-compat/security-and-operations/ — şifreleme ve imza duruşu
• /integrations/tcpdf-compat/integration/ — adaptörün bir uygulamaya bağlanması
• /integrations/tcpdf-compat/boot-and-discovery/ — sınıf takma adı kaydı ve cephe sunumu