compat-legacy hızlı başlangıç

Bir bakışta

Bu sayfa, kurulu bir paketten tamamlanmış bir PDF’ye ve ardından taşıma öncesinde çalıştıracağınız katı kip denetimine kadar size yol gösterir. Her kod bloğu, paketin test paketi tarafından doğrulanan davranışla eşleşir; bu nedenle burada gösterilen çıktı, testlerin denetlediği çıktıyla aynıdır.

Başlamadan önce

Paketi kurun ve motor bağlantısını /integrations/tcpdf-compat/install/ yönergelerini izleyerek doğrulayın. PHP 8.4 gereklidir ve nextpdf/core ^3.0 çözümlenmiş olmalıdır.

1. İlk belgenizi üretin

İçe aktarmayı değiştirin ve TCPDF tarzındaki çağrılarınızı koruyun. Bu, tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php tarafından doğrulanan yüzeyin tamamıdır.

examples/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');

echo "Wrote quickstart.pdf\n";

Çalıştırın:

php examples/quickstart-first.php

Oluşan quickstart.pdf dosyası geçerli bir PDF 2.0 belgesidir. Test paketi, eşleşen dizge çıktısının %PDF ile başladığını; bunun S, F ve E hedefleri ile getPDFData() için geçerli olduğunu doğrular.

Çıktı hedefleri

Output($name, $dest), TCPDF hedef kodlarını güvenli bir çıktı köprüsü aracılığıyla eşler. Test paketi bu davranışı sınar:

$dest	Davranış	Döndürülen değer
'S'	PDF’i dizge olarak döndürür	PDF baytları (%PDF…)
'F'	PDF’i belirtilen yola yazar	boş dizge
'E'	base64 MIME gövdesi döndürür	bir Content-Type: application/pdf bloğu
'I'	Satır içi (varsayılan)	çıktı köprüsüne göre
'D'	İndirme	çıktı köprüsüne göre

Eski TCPDF’nin aksine Output() doğrudan etkin çıktı arabelleğine yazmaz. Bunu bir kuyruk işleyicisinin içinde ya da kendi yanıtını yöneten bir HTTP işleyicisinin içinde güvenle çağırabilirsiniz. Bkz. /integrations/tcpdf-compat/production-usage/.

2. Mevcut TCPDF kodunu değiştirmeden çalıştırın

Gerçek bir taşımada, yalnızca içe aktarmayı veya takma adı değiştirip mevcut kodunuzu çalıştırarak başlayın. Kod tabanınız genel ad alanında new \TCPDF(...) çağırıyorsa, açılışta isteğe bağlı takma adları bir kez etkinleştirin (/integrations/tcpdf-compat/boot-and-discovery/ sayfasında ele alınmıştır):

examples/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');

LegacyBootstrap::enableAliases() birden fazla kez çağrılabilir; sonuç değişmez. \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS ve \TCPDF_IMAGES takma adlarını yalnızca bu sınıflar henüz mevcut değilse kaydeder. Paket testi tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php, takma adların kaydedildiğini, çağrının yinelenebilir olduğunu ve new \TCPDF() ifadesinin bir bağdaştırıcı örneği olduğunu doğrular. Gerçek TCPDF kitaplığı aynı süreçte yüklüyse takma adları etkinleştirmeyin; bkz. /integrations/tcpdf-compat/troubleshooting/.

3. Katı kip ile denetleyin

Bu adım, taşımayı daha güvenli hale getirir. Katı kip kapalıyken (varsayılan), TCPDF davranışını yeniden üretemeyen yöntemler sessizce hiçbir şey yapmaz. Katı kip açıkken, yok sayılan parametrelerin tam listesiyle birlikte TcpdfNotImplementedException fırlatırlar. Bunu özel bir denetim geçişinde çalıştırın, asla üretimde çalıştırmayın.

examples/quickstart-strict-audit.php

<?php

declare(strict_types=1);

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

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

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Paket testi tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php, bu tam çağrının katı kipte özel durum fırlattığını ve varsayılan kipte sessiz kaldığını, ayrıca iletinin yöntem adını ve yok sayılan parametreleri içerdiğini doğrular. Toplanan özel durumları taşıma iş listeniz olarak kullanın — bkz. /integrations/tcpdf-compat/migration/.

4. Gerektiğinde modern API’ye erişin

Her bağdaştırıcı örneği, altta yatan motor belgesini erişime açar. TCPDF karşılığı bulunmayan modern NextPDF yöntemlerini çağırmak için bunu kullanın:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument(), bağdaştırıcının sardığı NextPDF\Core\Document belgesini döndürür. Önerilen geçiş yolu budur: bağdaştırıcıyı kaldırabilecek duruma gelene kadar çağrı noktalarınızı birer birer modern API’ye taşıyın.

Hemen beklemeniz gereken davranış farkları

• MultiCell(), işlenmiş hücre sayısını değil, 1 döndürür. MultiCell() dönüş değerine göre dallanan kodun ayarlanması gerekir.
• Error(), RuntimeException fırlatır; die() çağırmaz. Süreç sonlandırmasına dayanan kodun bu özel durumu yakalaması gerekir.
• PDF baytlarının tam içeriği, TCPDF çıktısından farklıdır. Bayt düzeyindeki test doğrulamalarınızın taban çizgisini yeniden belirleyin; böylece baytlar yerine işlenmiş içeriği denetlerler.

Yöntem bazındaki listenin tamamı şurada bulunur: /integrations/tcpdf-compat/method-coverage/.

Sonraki adımlar

• /integrations/tcpdf-compat/migration/ — dosya dosya eksiksiz taşıma stratejisi.
• /integrations/tcpdf-compat/configuration/ — katı kip, varsayılanlar ve modern yapılandırma nesnesi.
• /integrations/tcpdf-compat/production-usage/ — işleyiciler, çıktı arabellekleri ve başarım.
• /integrations/tcpdf-compat/security-and-operations/ — şifreleme ve imzalama yaklaşımı.

Ayrıca bkz.

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — çıktı davranışı için doğruluk kaynağı
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — katı kip için doğruluk kaynağı
• docs/TCPDF_COVERAGE.md — yetkili kapsama matrisi