TCPDF 6.x'ten NextPDF'e geçiş

Bir bakışta

Geçişi net bir sırayla yapın. Önce mümkün olan en küçük değişiklikle NextPDF motoruna geçin. Zaten çalışan kısmı doğrulayın. Çalışmayan kısmı denetleyin. Her çağrı noktasını düzeltin. Ardından bağdaştırıcıyı kaldırın. Uyumluluk katmanı ikinci ile dördüncü adımlar arasını destekler; nihai hedef değildir.

Bu sayfa stratejiyi anlatır. Tek tek yöntemlerin tam davranışı için yetkili depo içi matris olan docs/TCPDF_COVERAGE.md dosyasını ve /integrations/tcpdf-compat/method-coverage/ adresini birlikte kullanın.

Geçiş modeli

Diagram

Her aşama uygulamayı dağıtıma hazır durumda tutar. Tek seferde toplu geçiş yapmanız asla gerekmez.

Aşama 1 — Bağımlılığı değiştirin

Önce nextpdf/compat-legacy paketini kurun (bkz. /integrations/tcpdf-compat/install/). Sakın tecnickcom/tcpdf paketini henüz kaldırmayın; iki paketi birlikte tutmak sonuçları karşılaştırmanızı sağlar.

Eski çağrı noktalarında sınıfın nasıl çözümleneceğine karar verin:

Tercih edilen: her dosyadaki use/require ifadesini use NextPDF\Compat\Tcpdf\TCPDF; olarak değiştirin. Bu yöntem açıktır ve aramayla kolay bulunur.
Çağrı noktalarına henüz dokunamadığınızda: başlangıçta bir kez LegacyBootstrap::enableAliases() ile isteğe bağlı genel takma adları etkinleştirin (bkz. /integrations/tcpdf-compat/boot-and-discovery/). Bu işlem \TCPDF sınıfını ve dört yardımcı sınıfı bağdaştırıcıya çözümler.

Bu iki strateji pratikte birbirini dışlar. Gerçek TCPDF kütüphanesi otomatik yüklenebilir durumdaysa ve genel takma adları etkinleştirirseniz, bir \TCPDF sınıfı zaten mevcut olduğunda takma ad atlanır. Bu durumda fark etmeden eski TCPDF’i kullanmaya devam edebilirsiniz. Aşama 1 sırasında, her çağrı noktasının hangi sınıfı kullandığını tam olarak bilmek için dosya başına içe aktarmaları tercih edin. Bkz. /integrations/tcpdf-compat/troubleshooting/.

Aşama 2 — Mevcut test paketini değiştirmeden çalıştırın

Başka hiçbir şeyi değiştirmeden tam test paketinizi bağdaştırıcıya karşı çalıştırın. Devralınan yöntemlerin çoğu (incelenen ~120 yöntemden 94’ü) uyumlu davranır. Öngörülebilir iki başarısızlık sınıfıyla karşılaşmayı bekleyin:

Bayt düzeyinde doğrulamalar. Tam PDF baytlarını karşılaştıran testler başarısız olur, çünkü motor bağımsız bir uygulamadır. Bu beklenen bir durumdur, kusur değildir. Bunları Aşama 4’e erteleyin.
Dönüş değeri dalları. Birkaç yöntem, hesaplanmış değerler yerine uyumluluk yer tutucuları döndürür. En belirgin örnek olarak, MultiCell() 1 döndürür ve Write() 0 döndürür. Bu dönüş değerlerine göre dallanan kodun düzenlenmesi gerekir.

Her başarısızlığı kayda geçirin. Her birini bayt temel çizgisi, dönüş değeri veya gerçek davranışsal boşluk olarak sınıflandırın.

Aşama 3 — Katı mod denetimi

Bu aşama geçişi güvenli hâle getirir. Test paketini veya temsili bir üretim akışını katı mod etkinleştirilmiş olarak çalıştırın:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

function renderInvoice(TCPDF $pdf): void
{
    // ... your existing rendering code, unchanged ...
}

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->setStrictMode(true);

try {
    renderInvoice($pdf);
    $pdf->Output(__DIR__ . '/audit.pdf', 'F');
} catch (TcpdfNotImplementedException $e) {
    // Each message names the method, the ignored parameters, and a hint.
    fwrite(STDERR, 'MIGRATION GAP: ' . $e->getMessage() . "\n");
}

Her TcpdfNotImplementedException istisnasını bir iş öğesi olarak ele alın. İleti size yöntemi, yok sayılan parametrelerin tam listesini ve bir geçiş ipucunu verir. İstisna fırlatan yöntem kümesi tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php içinde listelenir ve testlerle doğrulanır. Her gerekçe docs/TCPDF_COVERAGE.md dosyasında yer alır.

Katı modu üretimde değil, özel bir sürekli tümleştirme (CI) işi olarak çalıştırın. Amaç, üretimde istisna fırlatmak değil, boşlukları görünür kılmaktır.

Aşama 4 — Çağrı noktalarını düzeltin

Her boşluk için doğru ve en düşük maliyetli çözümü seçin:

Boşluk türü	Çözüm
Yok sayılan parametre önemli değil (e.g. davranışına hiç bağlı olmadığınız bir TCPDF `$align` parametresi)	Parametreyi kaldırın. Çağrı tamamen uyumlu hâle gelir.
Yok sayılan parametre önemliydi (e.g. tıklanabilir bir `Image()` bağlantısı)	Bunu modern API ile yeniden ifade edin. Görüntüyü çizin, ardından dikdörtgenin üzerine `Document::link()` ekleyin.
Yöntem uygulanmamış (`setSignature()`, `endPage()`)	`endPage()` / `Open()`: çağrıyı kaldırın. İmzalama için bkz. /integrations/tcpdf-compat/security-and-operations/; bunun için ticari bir sürüm gerekir.
Uygulanamaz yöntem (`setPDFVersion()`, `setUserRights()`)	Çağrıyı kaldırın. Çıktı her zaman PDF 2.0’dır; kullanıcı hakları (user-rights) PDF 2.0’da kullanımdan kaldırılmıştır.
Dönüş değeri dalı	Değeri kendiniz hesaplayın veya o mantığı modern API’ye taşıyın.

TCPDF’nin API yüzeyi ihtiyacınız olanı ifade edemediğinde kaçış yolunu kullanın:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();

// Legacy path stays as-is for the parts that work:
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Header line', 0, 1);

// Modern path for what the TCPDF surface cannot express here:
$document = $pdf->getDocument();
$document->image('logo.png', 10, 30, 40, 0);
$document->link(10, 30, 40, 20, 'https://example.com');

Bayt düzeyindeki testler için temel çizgiyi yeniden belirleyin

Tam bayt doğrulamalarını gerçekten önemli olanı doğrulayan kontrollerle değiştirin:

Çıktı %PDF ile başlar ve ayrıştırılabilir (duman testi düzeyi).
İşlenen metin içeriği mevcuttur (metni çıkarın ve üzerinde doğrulama yapın).
Yapısal özellikler (sayfa sayısı, sayfa boyutu ve bir ana hattın varlığı) eşleşir.

Bu tek seferlik maliyet, gelecekteki motor yükseltmelerinden etkilenmeden geçerliliğini koruyan testler kazandırır.

Aşama 5 — TCPDF bağımlılığını kaldırın

Katı mod denetimi geçtikten, üretimde katı mod kapalı olduktan ve test paketi temel çizgisi yeniden belirlenmiş doğrulamalarda yeşile döndükten sonra tecnickcom/tcpdf paketini kaldırın:

composer remove tecnickcom/tcpdf

Test paketini yeniden çalıştırın. Herhangi bir şey hâlâ gerçek TCPDF sınıfına çözümleniyorsa, Aşama 1’deki takma ad uyarısı gerçekleşmiş demektir; kalan çağrı noktalarını bağdaştırıcıyı açıkça içe aktaracak şekilde düzeltin.

Aşama 6 — Bağdaştırıcıyı kullanımdan kaldırın

Bağdaştırıcı, kalıcı bir katman değil, bir geçiş yardımcısıdır. TCPDF kaldırıldıktan ve motor doğrulandıktan sonra, bağdaştırıcıyı kademeli olarak kullanımdan kaldırın:

Her modülde, new TCPDF(...) ifadesini modern NextPDF\Core\Document kurulumuyla değiştirin.
TCPDF yöntem çağrılarını modern karşılıklarıyla değiştirin (Aşama 4’te zaten eklediğiniz getDocument() çağrıları örnek şablon sağlar).
Bir modül artık bağdaştırıcıya başvurmadığında, uyumluluk içe aktarmalarını silin.
Hiçbir modül bağdaştırıcıya başvurmadığında, nextpdf/compat-legacy paketini composer.json dosyasından kaldırın.

Bu noktada, uyumluluk katmanı olmadan modern PDF 2.0 API’sini kullanıyor olursunuz.

Geçiş kontrol listesi

nextpdf/compat-legacy kuruldu; motor bağlantısı doğrulandı.
Çağrı noktaları bağdaştırıcıyı açıkça içe aktarıyor (veya gerçek TCPDF otomatik yükleme yolundan kaldırılmışken takma adlar etkinleştirildi).
Tam test paketi bağdaştırıcıya karşı çalıştırıldı; başarısızlıklar sınıflandırıldı.
Katı mod CI işi eklendi; her boşluk kayda geçirildi.
Her boşluk düzeltildi (parametreyi kaldır / modern API / çağrıyı kaldır).
Bayt düzeyindeki doğrulamaların temel çizgisi içerik ve yapıya göre yeniden belirlendi.
tecnickcom/tcpdf kaldırıldı; test paketi yeşil.
Bağdaştırıcı modül modül kullanımdan kaldırıldı; bağımlılık kaldırıldı.

Ayrıca bkz.

/integrations/tcpdf-compat/method-coverage/ — yöntem bazında davranış ve yerine koyma rehberliği
docs/TCPDF_COVERAGE.md — yetkili, testlerle doğrulanmış matris
/integrations/tcpdf-compat/configuration/ — yapılandırmayı genel sabitlerden uzaklaştırma
/integrations/tcpdf-compat/security-and-operations/ — geçiş sırasında şifreleme ve imzalama
/integrations/tcpdf-compat/troubleshooting/ — alias/real-TCPDF çakışması ve diğer tuzaklar