NextPDF compat-legacy için önyükleme ve keşif

Genel bakış

nextpdf/compat-legacy, NextPDF motoruna devreden TCPDF uyumlu bir cephe olan NextPDF\Compat\Tcpdf\TCPDF sınıfını sunar. Bu bir uyumluluk katmanıdır, doğrudan yerine geçen bir klon değildir. İncelenen yaklaşık 120 TCPDF 6.x yönteminden 94’ünü doğrudan devreder. Kalan yöntemlerde belgelenmiş davranışsal farklılıklar vardır; bkz. /integrations/tcpdf-compat/method-coverage/.

Burada otomatik yükleme sırasında genel bağlama yapılmaz. Paketi dahil etmek varsayılan olarak genel bir \TCPDF sınıfı oluşturmaz. Genel takma adları açıkça etkinleştirmeniz veya geçiş sırasında tercihen bağdaştırıcı sınıfını her dosyada içe aktarmanız gerekir.

TCPDF cephesi nasıl sunulur

Cephe, standart PHP Standard Recommendation 4 (PSR-4) üzerinden otomatik yüklenen bir sınıftır:

Öğe	Değer
Cephe sınıfı	NextPDF\Compat\Tcpdf\TCPDF
PSR-4 ön eki	NextPDF\Compat\Tcpdf\ şu dizine eşlenir: src/Compat/Tcpdf/
Paylaşılan sözleşme	NextPDF\Compat\Contracts\CompatAdapterInterface
Çıkış noktası	TCPDF::getDocument(), sarmalanan nesneyi döndürür: NextPDF\Core\Document

Sınıf bilinçli olarak final değildir. Eski TCPDF kullanıcıları genellikle TCPDF sınıfından türeterek Header() ve Footer() yöntemlerini geçersiz kılar; bağdaştırıcı da bu genişletme noktasını korur. Dahili olarak sınıf bir cephe gibi davranır. Tek sorumluluk ilkesine göre ayrılmış 25 ilgi alanı trait’ini bir araya getirir ve tüm Portable Document Format (PDF) işlemlerini, cephe oluşturulduğunda oluşturulan bir Document nesnesine devreder.

Önyükleme dizisi

Diagram

Tek “önyükleme” adımı oluşturma aşamasıdır. Paketin kendisi hiçbir hizmet konteyneri kaydetmez ve hiçbir çatı önyüklemesi gerçekleştirmez. Çatı entegrasyonunu ince bir katman olarak siz eklersiniz; bkz. /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() idempotent davranır: bir sabiti yalnızca o sabit henüz tanımlanmamışsa tanımlar. İlk oluşturma aşamasından önce tanımlarsanız, uygulama tarafından tanımlanan sabitler her zaman önceliklidir; bkz. /integrations/tcpdf-compat/configuration/ § Yapılandırma çözümleme sırası.

İsteğe bağlı genel sınıf takma adları

Kod tabanınız genel ad alanında new \TCPDF(...) çağırıyorsa ve bu çağrı yerlerini henüz değiştiremiyorsanız, uygulama önyüklemesi sırasında genel takma adları bir kez kaydedin:

examples/boot-aliases.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() şunları kaydeder: \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS ve \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php bu davranışı doğrular:

• Bu işlem idempotent davranır: iki kez çağrılması hata fırlatmaz ve kaydı yalnızca bir kez yapar.
• LegacyBootstrap::isRegistered() kaydın etkin olup olmadığını bildirir.
• Kayıttan sonra new \TCPDF() bağdaştırıcının bir örneğini oluşturur.

Gerçek bir TCPDF kurulumuyla çakışmaların önlenmesi

Bu sayfadaki en önemli kural budur.

enableAliases() bir takma adı yalnızca o ada sahip bir sınıf henüz mevcut değilse kaydeder (class_exists($alias, autoload: false)). Bu nedenle:

• Eğer tecnickcom/tcpdf kuruluysa ve paketin \TCPDF sınıfı önce yüklenirse, takma ad sessizce atlanır ve kodunuz bağdaştırıcıyı değil, eski TCPDF’yi kullanmaya devam eder.
• Her iki kitaplığın aynı süreçte, genel takma adlar etkinleştirilmişken çalıştırılması desteklenmez ve belirsiz davranış üretir.

Geçiş sırasında her dosyada açık içe aktarmaları tercih edin (use NextPDF\Compat\Tcpdf\TCPDF;). Bunların aranması kolaydır ve belirsizlik içermezler. Katı kip denetimi geçtikten sonra tecnickcom/tcpdf paketini kaldırın; bkz. /integrations/tcpdf-compat/migration/ Aşama 5. \TCPDF yanlış sınıfa çözümlendiğinde, tanılama bilgilerini /integrations/tcpdf-compat/troubleshooting/ adresinde bulabilirsiniz.

Konteyner bağlamaları

Paket, çatı konteyner bağlamaları içermez. Cepheyi bir konteynerde bağlarsanız, her belge için yeni bir NextPDF\Compat\Tcpdf\TCPDF döndüren bir fabrika bağlayın. Belge durumu örnek düzeyindedir ve birbiriyle ilgisiz belgeler arasında paylaşılmamalıdır; bkz. /integrations/tcpdf-compat/production-usage/ § Eşzamanlılık. /integrations/tcpdf-compat/integration/ tipik bir bağlamayı gösterir.

Yapılandırma çözümleme sırası

Oluşturma sırasında bağdaştırıcı, yapılandırmayı şu sırayla çözümler: önce yapıcı bağımsız değişkenleri, ardından uygulama tarafından tanımlanmış mevcut eski sabitleri ve son olarak henüz tanımlanmamış her sabit için LegacyDefaults TCPDF 6.2.13 varsayılanlarını. Tüm ayrıntılar ve modern AdaptationConfig nesnesi için bkz. /integrations/tcpdf-compat/configuration/.

Tanılama

Cephenin bağlandığını ve motor bağlantısının çözümlendiğini doğrulamak için bir bağdaştırıcı oluşturun, tek sayfalık bir PDF üretin ve %PDF ön ekini kontrol edin. Paketin çıktı testleri aynı davranış yüzeyini doğrular. Çalıştırılabilir kontrol /integrations/tcpdf-compat/install/ § Kurulumu doğrulayın bölümündedir.

Takma adları etkinleştirmeden önce gerçek TCPDF çakışmasını saptamak için, genel bir \TCPDF sınıfının, enableAliases() çağıracağınız noktada zaten var olup olmadığını kontrol edin. Varsa, takma ad atlanacaktır. Çakışmayı açık içe aktarmalarla çözün veya bağdaştırıcıya güvenmeden önce gerçek TCPDF’yi kaldırın.

TCPDF API kapsamı

Yetkili ve testlerle doğrulanmış kapsam matrisi, depo içindeki docs/TCPDF_COVERAGE.md dosyasıdır. Sessizce yoksayılan ve uygulanmamış yöntem listeleri dahil olmak üzere okuyucuya yönelik özet /integrations/tcpdf-compat/method-coverage/ adresindedir. Bu paket, “doğrudan yerine geçen bir alternatif” veya “%100 TCPDF uyumlu” olduğunu iddia etmez; bilinen, test edilmiş bir uyumluluk yüzeyine ve belgelenmiş davranışsal farklılıklara sahip TCPDF uyumlu bir alternatiftir.

Ayrıca bkz.

• docs/TCPDF_COVERAGE.md — yetkili kapsam kaynağı (depo içi)
• /integrations/tcpdf-compat/integration/ — cephenin bir application/framework içine bağlanması
• /integrations/tcpdf-compat/method-coverage/ — yöntem başına davranış ve boşluklar
• /integrations/tcpdf-compat/migration/ — aşamalı geçiş stratejisi
• /integrations/tcpdf-compat/troubleshooting/ — alias/real-TCPDF çakışma tanılaması
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — takma ad davranışı oracle’ı