compat-legacy sorunlarını giderme

Genel bakış

Çoğu geçiş sorunu sınırlı sayıda kalıba uyar. Aşağıdaki her madde belirtiyi, nedeni ve çözümü listeler. Belirli bir yöntemden emin olmadığınızda /integrations/tcpdf-compat/method-coverage/ sayfasını ve depodaki yetkili kapsam matrisi docs/TCPDF_COVERAGE.md dosyasını denetleyin.

İşlem eskiden PDF hatasında dururdu; artık özel durum dışarı sızıyor

Belirti. Hatalı bir işlemde eskiden duran kod, artık yakalanmamış bir RuntimeException fırlatıyor ve istek ya da iş hata bildiriyor.

Neden. Eski TCPDF’de Error() çağrıları die() çalıştırır. Bağdaştırıcı ise tasarım gereği bunun yerine RuntimeException fırlatır; böylece hatalar gözlemlenebilir olur.

Çözüm. İşleme giriş noktalarınızı try/catch ile sarmalayın ve özel durumu kendi hata sözleşmenize eşleyin. die() davranışını geri getirmeyin. /integrations/tcpdf-compat/production-usage/ § Hata işleme bölümüne bakın.

`new \TCPDF()` hâlâ gerçek TCPDF kitaplığına çözümleniyor

Belirti. LegacyBootstrap::enableAliases() çağrısını etkinleştirdiniz ancak çıktı hâlâ eski TCPDF gibi görünüyor ya da davranış değişmedi.

Neden. enableAliases(), yalnızca o ada sahip bir sınıf henüz yoksa takma ad kaydeder. tecnickcom/tcpdf otomatik yükleme kapsamında kalır ve onun \TCPDF sınıfı önce yüklenirse takma ad atlanır; kodunuz eski TCPDF’yi kullanmayı sürdürür.

Çözüm. Geçiş sırasında her dosyada açık içe aktarmalar (use NextPDF\Compat\Tcpdf\TCPDF;) kullanın; böylece her çağrı noktası belirsizlikten uzak olur. Denetimi tamamladıktan sonra tecnickcom/tcpdf paketini kaldırın (bkz. /integrations/tcpdf-compat/migration/ Aşama 5). Genel takma adlar etkinken her iki kitaplığı aynı süreçte birlikte çalıştırmayın.

Bir yöntem “çalışıyor” ama geçirdiğim parametre yoksayılıyor

Belirti. Bir çağrı başarılı olur ve bir Taşınabilir Belge Biçimi (PDF) dosyası üretir, ancak geçirdiğiniz bir seçeneğin (resim bağlantısı, hizalama, inç başına nokta (DPI), yer imi rengi, …) hiçbir etkisi olmaz.

Neden. Yöntem, sessizce yoksayılanlar kümesindedir. Kaynak uyumluluğu için parametreyi kabul eder, ardından onu atar. Bu, bir hata değil belgelenmiş bir davranıştır; bkz. /integrations/tcpdf-compat/method-coverage/ §2.

Çözüm. Bu tür her çağrıyı bulmak için katı kipte bir denetim ç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;

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

try {
    $pdf->Image('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Ardından parametreyi atın ya da /integrations/tcpdf-compat/migration/ Aşama 4’te gösterildiği gibi modern API üzerinden yeniden ifade edin ($pdf->getDocument()).

`MultiCell()` dönüş değeri her zaman 1

Belirti. MultiCell() dönüş değerine göre dallanan kod (örneğin kullanılan yüksekliği ya da satır sayısını hesaplamak için) yanlış davranıyor.

Neden. Bağdaştırıcının MultiCell() yöntemi, işlenen hücre sayısını ya da satır sayısını değil, uyumluluk yer tutucusu olan 1 değerini döndürür. Write() de benzer şekilde 0 döndürür.

Çözüm. Bu dönüş değerlerine göre dallanmayın. İşlenen yükseklik gerekiyorsa bunu getStringHeight() / getNumLines() üzerinden hesaplayın ya da bu mantığı modern API’ye taşıyın.

`setPDFVersion('1.4')` bir PDF 1.4 dosyası üretmedi

Belirti. Daha eski bir PDF sürümü istediniz; çıktı yine de PDF 2.0.

Neden. Bağdaştırıcı her zaman PDF 2.0 (ISO 32000-2) çıktısı verir. setPDFVersion(), uygulanamayanlar kümesindedir; bağdaştırıcı bir bildirim yayımlar ve devam eder.

Çözüm. Çağrıyı kaldırın. Akış aşağısındaki bir tüketici daha eski bir PDF sürümü gerektiriyorsa bu gereksinimi ayrıca çözün; bağdaştırıcı daha düşük sürüme hedefleyemez.

`setSignature()` hiçbir şey yapmadı — PDF imzalanmamış

Belirti. setSignature() yöntemini bir sertifikayla çağırdınız; çıktı PDF’sinde imza yok.

Neden. Çekirdek altyapı, bu bağdaştırıcı aracılığıyla setSignature() yöntemini gerçeklemez. Varsayılan kipte hiçbir işlem yapmaz; katı kipte ise özel durum fırlatır.

Çözüm. İmzalama, ticari bir NextPDF sürümünü ve modern imza API’sini gerektirir. /integrations/tcpdf-compat/security-and-operations/ § Sayısal imzalar bölümüne bakın. Eski setSignature() çağrısının herhangi bir şeyi imzalamasını beklemeyin.

`Output()` HTTP yanıtımı ya da işçi çıktımı bozdu

Belirti. PDF baytları bir Köprü Metni Aktarım Protokolü (HTTP) yanıtında görünüyor ya da işçi günlüğü PDF baytlarıyla kirleniyor.

Neden. Yanıtı kendiniz denetlerken çıktı yoluna yazan bir çıktı hedefi (I/D) kullandınız. Bağdaştırıcı, eski TCPDF’nin yaptığı gibi arabelleğinize yankılamaz, ancak I/D yine de altyapı çıktısını yönlendirir.

Çözüm. Denetlediğiniz işçilerde ve işleyicilerde, dosya yazmak için Output($path, 'F') kullanın ya da baytları alıp kendiniz yaymak için Output($name, 'S') kullanın. tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php, hedef eşlemesinin büyük/küçük harfe duyarsız olduğunu ve boşlukların kırpıldığını doğrular:

Kod	Döndürür	Yan etki
`S`	PDF baytları (`%PDF…`)	yok
`F`	boş dize	dosya yazar
`E`	base64 MIME gövdesi	yok
`FI` / `FD`	boş dize	dosya yazar, ardından altyapı çıktısı
`I` / `D` / bilinmeyen	boş dize	altyapı çıktısı (satır içi/indirme)

Geçişten sonra bayt düzeyindeki PDF onaylamaları başarısız oluyor

Belirti. Ham PDF baytlarını karşılaştıran anlık görüntü testleri genelinde başarısız oluyor.

Neden. Altyapı, bağımsız bir PDF 2.0 gerçeklemesi kullanır. Devredilen yöntemler görünürde uyumlu çıktı üretir, ancak baytlar farklıdır. Bu beklenen bir durumdur.

Çözüm. Testlerinizi, işlenen içeriği (ayıklanan metin), yapıyı (sayfa sayısı, sayfa boyutu) ya da bir duman denetimini (str_starts_with($bytes, '%PDF')) doğrulayacak biçimde güncelleyin. /integrations/tcpdf-compat/migration/ Aşama 4’e bakın.

Eski bir `K_` / `PDF_` sabiti yanlış değere sahip

Belirti. Bir sabit aracılığıyla ayarladığınız özel yol ya da varsayılan değer etkili olmuyor.

Neden. Bağdaştırıcı bir sabiti yalnızca henüz tanımlı değilse otomatik tanımlar ve bunu ilk örnek oluşturma sırasında yapar. define() çağrınız ilk bağdaştırıcı oluşturulduktan sonra çalışırsa bağdaştırıcının varsayılanı zaten etkindir.

Çözüm. Her özel K_* / PDF_* sabitini, herhangi bir bağdaştırıcı örneği oluşturulmadan önce önyükleme kodunuzda tanımlayın. /integrations/tcpdf-compat/configuration/ § Yapılandırma çözümleme sırası bölümüne bakın.

Oluşturma sırasında altyapı sürümü uyuşmazlığı

Belirti. Bir bağımlılık güncellemesinden sonra oluşturma başarısız oluyor veya davranış beklenmedik biçimde değişiyor.

Neden. Bağdaştırıcı nextpdf/core ^3.0 gerektirir. Bu aralığın dışında çözümlenen bir çekirdek sürümü desteklenmez.

Çözüm. composer show nextpdf/core çalıştırın ve altyapıyı ^3.0 sürümüne sabitleyin. /integrations/tcpdf-compat/install/ § Altyapı sürümünü doğrulayın bölümüne bakın.

Hızlı tanılama başvurusu

Soru	Nereye bakmalı
X yöntemi burada gerçekte ne yapıyor?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Hangi çağrılarım parametre kaybediyor?	Katı kip denetimi (bu sayfa; /integrations/tcpdf-compat/migration/)
İşlem hata sırasında neden durmadı?	/integrations/tcpdf-compat/security-and-operations/ § Sıkılaştırılmış davranışlar
Çıktı neden imzalanmamış / PDF/A değil?	/integrations/tcpdf-compat/security-and-operations/
Takma ad ile açık içe aktarma çakışması	Bu sayfa; /integrations/tcpdf-compat/boot-and-discovery/

Ayrıca bkz.

/integrations/tcpdf-compat/migration/ — yukarıdakilerin çoğunu önleyen aşamalı geçiş
/integrations/tcpdf-compat/method-coverage/ — yöntem bazında davranış başvurusu
/integrations/tcpdf-compat/boot-and-discovery/ — takma ad kaydı ve çakışmadan kaçınma
docs/TCPDF_COVERAGE.md — yetkili kapsam matrisi