compat-legacy'yi üretimde çalıştırma

Bir bakışta

Bağdaştırıcı, Köprü metni aktarım protokolü (HTTP) işleyicilerinde, kuyruk işçilerinde ve uzun süre çalışan işlemlerde güvenle çalıştırılabilir. Eski TCPDF 6.2.13 sürümünden daha güvenli çalışır; çünkü üretimde karşılaşma olasılığınızın en yüksek olduğu iki riski ortadan kaldırır: çıktıyı doğrudan ara belleğe yazma ve hata durumunda die() çağırma. Bağdaştırıcıyı doğru şekilde çalıştırmak için bu sayfayı kullanın.

Üretime geçmeden önce /integrations/tcpdf-compat/migration/ bölümündeki katı mod denetimini tamamlayın ve dağıtımı katı mod kapalı olacak şekilde yapın.

İşçilerde ve işleyicilerde çıktı işleme

Eski TCPDF Output() yöntemi doğrudan etkin çıktı ara belleğine yazar. Bu durum, HTTP çerçevelerindeki yanıtları bozabilir ve kuyruk işçilerini işlevsiz bırakabilir. Bağdaştırıcı ise çıktıyı bunun yerine güvenli bir hedef köprüsü üzerinden yönlendirir.

Çağırana uygun olan hedefi seçin:

Bağlam	Hedef	Neden
Depolama alanına yazan kuyruk işçisi	`Output($path, 'F')`	Dosyayı yazar ve boş bir dize döndürür. Ara bellekle etkileşime girmez.
Oluşturma ve ardından attach/upload	`Output($name, 'S')`	Taşınabilir belge biçimi (PDF) baytlarını döndürür; baytların nereye gideceğini siz denetlersiniz.
E-posta eki	`Output($name, 'E')`	base64 ile kodlanmış, `Content-Type: application/pdf` içeren bir Çok amaçlı internet posta uzantıları (MIME) gövdesi döndürür.
Sizin denetlediğiniz HTTP yanıtı	`Output($name, 'S')`	Baytları alır; ardından kendi başlıklarınızı ve gövdenizi siz ayarlarsınız.

<?php

declare(strict_types=1);

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

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

/**
 * Render an invoice in a queue worker. Returns the storage path.
 *
 * @throws \RuntimeException on a render failure (Error() throws, not die()).
 */
function renderInvoiceJob(array $invoice, string $storageDir): string
{
    $pdf = new TCPDF('P', 'mm', 'A4');
    $pdf->SetFont('helvetica', '', 12);
    $pdf->AddPage();
    $pdf->Cell(0, 10, 'Invoice ' . $invoice['number'], 0, 1);

    $path = $storageDir . '/invoice-' . $invoice['number'] . '.pdf';

    try {
        $pdf->Output($path, 'F'); // writes file, no buffer pollution
    } catch (TcpdfNotImplementedException $e) {
        // Only reachable if strict mode is on — it must NOT be in production.
        throw new \RuntimeException('Adapter strict-mode gap in production: ' . $e->getMessage(), 0, $e);
    } catch (\RuntimeException $e) {
        // Error() throws RuntimeException instead of die().
        throw new \RuntimeException('PDF render failed: ' . $e->getMessage(), 0, $e);
    }

    return $path;
}

Bir HTTP işleyicisinde 'S' seçeneğini tercih edin ve başlıkları kendiniz ayarlayın:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Report');

$bytes = $pdf->Output('report.pdf', 'S');

header('Content-Type: application/pdf');
header('Content-Length: ' . strlen($bytes));
header('Content-Disposition: inline; filename="report.pdf"');
echo $bytes;

Hata işleme

Error() bir RuntimeException fırlatır; hiçbir zaman die() çağırmaz. Bu, eski TCPDF’ye kıyasla en önemli işlevsel değişikliktir.

Her işleme giriş noktasını try/catch ile sarmalayın.
Özel durumu uygulamanızın hata sözleşmesine eşleyin; örneğin HTTP 5xx, başarısız iş, yeniden deneme veya dead-letter gibi.
Bir işleme hatasında işlemin sona ereceğini varsaymayın; sona ermez.

Düzenli aralıklarla çalışan katı mod sürekli tümleştirme (CI) işinde (önerilir) görülen bir TcpdfNotImplementedException, gerçek bir bulgudur. Bu, bir kod yolunun desteklenmeyen bir TCPDF parametresine dayandığı anlamına gelir. Bunu kararsız bir test olarak değil, geçiş için ele alınması gereken bir iş öğesi olarak değerlendirin.

Yaşam döngüsü ve kaynak işleme

Belge, PDF baytlarını ilk çıktı çağrısında geç değerlendirme ile oluşturur. Close() isteğe bağlıdır; çağrılması baytları önbelleğe alır. Open() güvenli bir işlemsiz çağrıdır.
endPage() hiçbir şey yapmaz; çünkü sayfa yaşam döngüsünü NextPDF yönetir. Sık çalışan döngülerden kaldırın; herhangi bir değer katmaz.
İşler arasında bağdaştırıcıyı PHP’nin çöp toplamasına bırakın. _destroy() bağdaştırıcının önbelleğe alınmış verilerini sıfırlar; ancak normal işçi döngülerinde bunu açıkça çağırmanız gerekmez.
Her belge için yeni bir bağdaştırıcı oluşturun. Uzun süre çalışan bir işçide tek bir bağdaştırıcı örneğini birbiriyle ilgisiz belgeler arasında yeniden kullanmayın; belge durumu örnek düzeyindedir.

Performans yönergeleri

Bağdaştırıcı, ince bir devretme katmanıdır; maliyeti bağdaştırıcı değil, motor belirler.
Eski sabitleri açılışta bir kez tanımlayın. LegacyDefaults::register() ve LegacyBootstrap::enableAliases() idempotent ve korumalıdır; bu nedenle yinelenen çağrılar düşük maliyetlidir. Sabitleri her istekte tanımlamak boşuna iş harcar.
Tarayıcı dışı bağlamlarda Output(..., 'S') veya 'F' seçeneğini, 'I'/'D' yerine tercih edin. inline/download yolları, bir işçide genellikle istemediğiniz, çerçeveden bağımsız çıktı üretir.
Yüksek hacimli üretim için bağdaştırıcıyı değil, motoru profilleyin. Bağdaştırıcının kendi ek yükü için sayfa başına bütçe, işleme maliyetine kıyasla küçüktür.

Eşzamanlılık

Her bağdaştırıcı örneği bağımsızdır ve kendi belge durumunu tutar. Her iş birimi kendi bağdaştırıcı örneğini kullandığında, işlem veya işçi düzeyindeki eşzamanlılık güvenlidir.
İdempotency korumaları, LegacyBootstrap ve LegacyDefaults içinde işlem yerelinde statik durum kullanır; tipik PHP per-request/per-worker modelleri altında güvenlidir. İş parçacıkları arasında değiştirilebilir durumu paylaşmak için tasarlanmamışlardır.

Üretim öncesi denetim listesi

Katı mod denetimi tamamlandı; üretim, katı mod kapalı olarak çalışır.
Tüm işleme giriş noktaları try/catch ile RuntimeException için sarmalandı (die() çağrısına güvenilmiyor).
İşçiler Output(..., 'F') veya 'S' kullanır, hiçbir zaman inline yolunu kullanmaz.
Eski sabitler açılışta, ilk oluşturma işleminden önce bir kez tanımlandı.
Gerilemeleri yakalamak için düzenli aralıklarla çalışan bir katı mod CI işi yürürlükte.
Bayt düzeyindeki test doğrulamaları yeniden temellendirildi (bkz. /integrations/tcpdf-compat/migration/).

Ayrıca bkz.

/integrations/tcpdf-compat/security-and-operations/ — şifreleme, imzalama yaklaşımı ve sıkılaştırma
/integrations/tcpdf-compat/troubleshooting/ — üretimdeki hata düzenleri ve çözümleri
/integrations/tcpdf-compat/configuration/ — katı mod ve sabit hijyeni
/integrations/tcpdf-compat/migration/ — üretimden önce yapılması gereken denetim