Bir TCPDF 6.x kod tabanını NextPDF'e taşıma

Bir bakışta

NextPDF core motoru üzerinde, nextpdf/compat-legacy paketi TCPDF 6.x genel yöntem adlarını, parametre sırasını ve varsayılanlarını NextPDF\Compat\Tcpdf\TCPDF bağdaştırıcısı aracılığıyla sunar. Taşımayı şu sırayla yapın: en küçük değişiklikle motora geçin, hâlihazırda çalışanı doğrulayın, çalışmayanları bulmak için katı kipi açın, çağrı noktalarını teker teker düzeltin ve ardından bağdaştırıcıyı devreden çıkarıp modern API’yi kullanın. Bağdaştırıcı taşımayı destekler; nihai hedef değildir.

Ön koşullar şunlardır:

• NextPDF core ve nextpdf/compat-legacy kurulu.
• Test paketi bulunan mevcut bir TCPDF 6.x kod tabanınız var. Bu test paketi, aşağıdaki her aşamanın güvenlik ağıdır.

Bu, bir nasıl-yapılır kılavuzudur. Belirli bir TCPDF çağrısının yöntem düzeyindeki davranışı için yöntem kapsamı sayfasını okuyun. Kod örnekleriyle, dosya dosya ilerleyen eksiksiz strateji için ana taşıma sayfasını okuyun. Her iki bağlantı da Ayrıca bakınız bölümündedir.

Kurulum

Bağdaştırıcıyı core ile birlikte kurun. Gerçek TCPDF kitaplığını henüz kaldırmayın — ikisini birlikte tutmak, taşıma sırasında çıktıları karşılaştırmanıza olanak tanır.

composer require nextpdf/compat-legacy

Herhangi bir kodu değiştirmeden önce, motor bağımlılığının çözümlendiğini (nextpdf/core ^3.0) ve test paketinin hâlâ çalıştığını doğrulayın.

Kavramsal genel bakış

Bağdaştırıcı bir uyumluluk katmanıdır; TCPDF’in bir çatallaması veya bayt düzeyinde birebir kopyası değildir. İncelenen yaklaşık 120 TCPDF 6.x genel yönteminden yaklaşık 94 tanesi doğrudan bir NextPDF\Core\Document işlemine karşılık gelir ve belgelenmiş parametreler için uyumlu davranır. Sınırlı bir bölüm ise ya motorun dikkate almadığı eski parametreleri kabul eder (sessizce yoksayma) ya da çıktı üretmez (uygulanmamış veya uygulanamaz). Bağlayıcı, testle doğrulanmış kapsam matrisi, paket deposunda docs/TCPDF_COVERAGE.md konumundadır. Bu kılavuz ile o matris çeliştiğinde matris geçerlidir.

Taşımanın tamamını iki olgu belirler:

• Çıktı baytları farklıdır. Motor, bağımsız bir PDF 2.0 uygulamasıdır; bu nedenle görsel sonuç aynı olsa bile, üretilen baytlar TCPDF çıktısından farklıdır. Tam PDF baytları üzerinde doğrulama yapan testlerin, işlenen içeriğe veya yapısal özelliklere yeniden dayandırılması gerekir.
• Katı kip, denetim aracınızdır. Katı kip kapalıyken (varsayılan), TCPDF davranışını yeniden üretemeyen yöntemler sessizce daha sınırlı davranır. Katı kip açıkken, bu çağrılar hangi parametrelerin yoksayıldığını ve bir taşıma ipucunu açıkça belirterek TcpdfNotImplementedException fırlatır. Katı kipi yalnızca ayrı bir denetim geçişinde çalıştırın; üretimde asla çalıştırmayın.

Bağdaştırıcı ayrıca sarmalanmış motor belgesini getDocument() aracılığıyla sunar; bu da NextPDF\Core\Document döndürür. Bunu kaçış yolu olarak kullanın: bağdaştırıcıyı kaldırabilene kadar çağrı noktalarını teker teker modern API’ye taşıyın.

API yüzeyi

Konu	Yüzey
Oluşturma	new NextPDF\Compat\Tcpdf\TCPDF('P', 'mm', 'A4')
İsteğe bağlı genel takma adlar	NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()
Denetimi etkinleştirme	TCPDF::setStrictMode(true)
Denetim istisnası	NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException
Modern API’ye kaçış yolu	TCPDF::getDocument(): NextPDF\Core\Document
Çıktı	TCPDF::Output(string $name, string $dest) — S, F, E, I, D

LegacyBootstrap::enableAliases() idempotenttir. \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS ve \TCPDF_IMAGES sınıflarını yalnızca bu sınıflar henüz mevcut değilken kaydeder. Ayrıca bakınız bölümünde bağlantısı verilen yöntem kapsamı ve hızlı başlangıç sayfaları, yöntem başına tam davranışı ve çıktı hedeflerini ele alır.

Kod örneği — Hızlı başlangıç

İçe aktarmayı değiştirin, TCPDF tarzı çağrıları koruyun ve bir PDF üretin.

quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

Output($name, 'F') dosyayı yazar ve boş bir dize döndürür. Eski TCPDF’in aksine, bağdaştırıcının Output() yöntemi etkin çıktı arabelleğine yankılamaz; bu nedenle, kendi yanıtını denetleyen bir kuyruk işçisi veya bir HTTP işleyicisi içinde güvenle çağırabilirsiniz.

Genel ad alanında new \TCPDF(...) oluşturan çağrı noktalarını değiştiremediğinizde, isteğe bağlı takma adları başlatma sırasında bir kez etkinleştirin.

quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

Gerçek TCPDF kitaplığı hâlâ otomatik yüklenebilir durumdayken takma adları etkinleştirmeyin. Bir \TCPDF sınıfı zaten mevcut olduğunda takma ad atlanır; bu yüzden farkında olmadan eski TCPDF’i kullanmaya devam edebilirsiniz. Taşıma sırasında dosya düzeyinde açık içe aktarmaları tercih edin.

Kod örneği — Üretim

Taşımada güvenli ilerleme adımı, katı kip denetimidir. Temsili bir üretim yolunu veya test paketini katı kip açıkken çalıştırın ve her TcpdfNotImplementedException istisnasını toplayın. Her istisna bir iş kalemidir: yöntemi, yoksayılan parametreleri ve bir ipucunu adlandırır.

migration-audit.php

<?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 $exception) {
    // Each message names the method, the ignored parameters, and a hint.
    fwrite(STDERR, 'MIGRATION GAP: ' . $exception->getMessage() . "\n");
}

Her boşluk için en ucuz doğru düzeltmeyi seçin: bağlı olmadığınız bir parametreyi düşürün ya da amacı getDocument() aracılığıyla modern API üzerinden ifade edin. Kaçış yolu, TCPDF yüzeyinin ifade edemediği her şeyi ele alır.

migration-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

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

// Modern path for what the TCPDF surface cannot express here —
// for example a clickable image (the legacy Image() link parameter
// is one of the silently ignored parameters):
$document = $pdf->getDocument();
$document->image('logo.png', 10, 30, 40, 0);
$document->link(10, 30, 40, 20, 'https://example.com');

Katı kipi ayrı bir sürekli tümleştirme (CI) işi olarak çalıştırın, ardından kapatıp denetlenmiş kod yolunu dağıtın. Kodda yeniden düzenleme yaptıkça gerilemeleri yakalamak için düzenli bir katı kip CI işi tutun.

Uç durumlar & tuzaklar

• MultiCell() 1 döndürür, Write() 0 döndürür. Bunlar uyumluluk yer tutucularıdır, hesaplanmış değerler değildir. Bu dönüş değerlerine göre dallanan her kodu uyarlayın.
• Error() die() çağırmak yerine fırlatır. Bağdaştırıcı RuntimeException oluşturur. Süreci sonlandırmaya dayanan kodun istisnayı yakalaması gerekir.
• Sessizce yoksanan parametreler. Image(), writeHTML(), SetProtection() ve Bookmark() gibi yöntemler, yoksanan eski parametreleri kabul eder. Bunları bulmak için katı kipi kullanın. Tıklanabilir bir görüntü için, görüntüyü çizin, ardından aynı dikdörtgenin üzerine Document::link() ekleyin.
• Uygulanmamış yöntemler. setSignature(), addEmptySignatureAppearance() ve endPage() katı kipte istisna fırlatan boş işlemlerdir; Open() ise asla fırlatmayan güvenli bir boş işlemdir. endPage() ve Open() yöntemlerini kaldırın. İmzalama, modern imza API’si aracılığıyla ticari bir NextPDF sürümü gerektirir.
• PDF sürümü sabittir. setPDFVersion() daha eski bir PDF sürümünü hedef alamaz; çıktı her zaman PDF 2.0’dır. setUserRights() PDF 2.0’da kullanımdan kaldırılmıştır ve bir bildirimle birlikte yoksanır.
• Takma ad çakışması. tecnickcom/tcpdf paketini kaldırdıktan sonra bir çağrı hâlâ gerçek TCPDF sınıfına çözümleniyorsa, takma ad uyarısı geçerlidir — bağdaştırıcıyı o çağrı noktalarında açıkça içe aktarın.

Performans

Bağdaştırıcı işi motora devreder; belge oluşturma maliyeti, bağdaştırıcı katmanıyla değil içerikle ölçeklenir. Bağdaştırıcının Output() yöntemi çıktı arabelleğine yazmadığından, bir kuyruk işçisi içinde güvenlidir — ağır TCPDF tarzı üretimi, herhangi bir NextPDF üretimini taşıdığınız gibi istek iş parçacığının dışına taşıyın. Bayt düzeyindeki testleri işlenen içeriğe yeniden dayandırmak tek seferlik bir maliyettir ve size gelecekteki motor yükseltmelerinde de geçerliliğini koruyan testler kazandırır.

Güvenlik notları

• Şifreleme. SetProtection() eski mode ve pubkeys parametrelerini yoksayar; motor, standart işleyici için AES-256 kullanır. Sertifika tabanlı şifreleme için, eski parametreleri değil, bağdaştırıcı üzerinde sunulan modern genel anahtar şifreleme giriş noktasını kullanın.
• İmzalama kısıtlıdır. Temel imza desteği, modern imza API’si aracılığıyla ve bir sertifika değer nesnesiyle erişilen, ticari sürüme özgü bir yetenektir; eski setSignature() bir boş işlemdir. Bu kılavuz, hiçbir sürüm için uzun vadeli doğrulama veya zaman damgalı imza profilleri hakkında bir iddiada bulunmaz.
• Denetim sırasında açıkça başarısız olun. Katı kip, sessiz parametre kaybını görünür kılar; böylece bağdaştırıcının çağıranın amacını ne zaman dikkate almadığını bilirsiniz. Toplanan istisnaları üretim davranışı olarak değil, taşıma iş listesi olarak değerlendirin.
• Asla boş bir catch bloğu yazmayın. Denetim örneği TcpdfNotImplementedException istisnasını yakalar ve tanımlı bir iş kalemi satırı yazar.

Taşıma sırasındaki tam şifreleme ve imza yaklaşımı, compat-legacy güvenlik ve operasyonlar sayfasındadır.

Uyumluluk

Bu kılavuz kendi başına normatif bir standart iddiasında bulunmaz. Bağdaştırıcı, PDF 2.0 (ISO 32000-2) çıktısı yazar ve daha eski bir sürümü hedef alamaz. Bu davranış ve ilgili maddesi, ana kaynak yöntem kapsamı sayfasında sabitlenmiştir; bu sayfa ayrıca katı kipin ardındaki OWASP açıkça-başarısız-ol ilkesini ve kapsam denetiminin ISO/IEC 25023 işlevsel-bütünlük çerçevelendirmesini de kaydeder. Bu Cookbook sayfası kullanımı yeniden ifade eder ve ilgili alıntıları kaynak sayfaya bırakır.

Ayrıca bakınız

• Bir denetleyiciden üretilen bir PDF döndürme — bağdaştırıcı çıktısını bir HTTP yanıtı olarak döndürün.
• compat-legacy hızlı başlangıç — ilk belge, çıktı hedefleri ve kaçış yolu.
• TCPDF yöntem kapsamı — yöntem başına denetim ve bağlayıcı matris.
• TCPDF 6.x’ten NextPDF’e taşıma — kod örnekleriyle eksiksiz altı aşamalı strateji.