Üretimde Artisan

Bir bakışta

Üretimde yapılandırılmış bir işleyici ve bir PHP Standartları Önerisi 3 (PSR-3) günlükleyicisi enjekte edin; işlemeler arasında canlı Chrome sürecini yeniden kullanın, çok öğeli belgeler için belirgin yükseklik değerleri ayarlayın ve işleme yolunu yukarı akıştaki bir zaman aşımıyla sınırlayın.

Kavramsal genel bakış

BrowserPool tek bir Chrome sürecini canlı tutar (keepAlive: true) ve bellek büyümesini sınırlamak için onu her 100 işlemede bir yeniden başlatır; bu, uzun ömürlü Chrome DevTools Protocol (CDP) istemcilerinde bilinen bir birikim örüntüsüdür. Çok sayıda belge işleyen bir iş sürecinde, her istek için yeni bir işleyici yerine tek ve uzun ömürlü bir işleyici kullanın; böylece Chrome başlatma maliyetini yalnızca ara sıra ödersiniz.

Kod örneği — üretim

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\Exception\ChromeNotAvailableException;
use NextPDF\Artisan\Exception\ChromeRenderException;
use Psr\Log\LoggerInterface;

final class ReportRenderer
{
    private ChromeHtmlRenderer $renderer;

    public function __construct(LoggerInterface $logger)
    {
        $config = ChromeRendererConfig::fromArray([
            'chrome_binary'  => getenv('CHROME_BINARY') ?: null,
            'render_timeout' => 45,
            'max_html_size'  => 2_000_000,
            'no_sandbox'     => (bool) getenv('CHROME_NO_SANDBOX'),
        ]);

        $this->renderer = new ChromeHtmlRenderer($config, $logger);
    }

    public function render(string $html, float $widthPt, float $heightPt = 0.0): string
    {
        try {
            return $this->renderer->render($html, $widthPt, $heightPt)->getPdfData();
        } catch (ChromeNotAvailableException $e) {
            // Deployment fault: Chrome runtime missing. Page the on-call owner.
            throw $e;
        } catch (ChromeRenderException $e) {
            // Render-time fault: timeout, crash, empty output. Retryable once.
            throw $e;
        }
    }

    public function shutdown(): void
    {
        $this->renderer->close();
    }
}

İşleyiciyi bir kez oluşturun, ardından yeniden kullanın. Chrome sürecini yıkıcıyı beklemeden belirleyici biçimde serbest bırakmak için iş süreci kapanırken close() çağrısını yapın. İki catch kolu, bir dağıtım hatasını (eksik çalışma zamanı) bir işleme zamanı hatasından (yeniden denenebilir) ayırır. Boş catch blokları kullanmayın.

Bunu bir kapsayıcıya tekil nesne olarak bağlayın:

$container->singleton(ReportRenderer::class, fn ($c) =>
    new ReportRenderer($c->get(Psr\Log\LoggerInterface::class)));

Yükseklik işleme

Yüksekliği belirtmediğinizde köprü, içerik yüksekliğini Chrome içinde ölçer (body/document kaydırma ve ofset yükseklikleri arasındaki max değeri), bunu noktalara dönüştürür ve ~0.2 inç (~14.4 pt) bir güvenlik tamponu ekler. Tampon, Chrome’un görüntü alanı yerleşimi ile yazdırma yerleşiminin yeniden akışı arasındaki farkı kapatır. Tampon olmadan printToPDF, içeriği PageImporter (yalnızca sayfa 0) tarafından kırpılacak ikinci bir sayfaya taşıyabilir. Köprü, 0.1 inçlik bir asgari kâğıt yüksekliğini zorunlu kılar. ChromeHtmlRendererTest::renderUsesAutoFitHeightByDefault, ::renderAutoFitBufferIsAddedNotSubtracted ve ::renderAppliesMinimumHeightOf0Point1InchForTinyExplicitHeight testleri bu davranışı doğrular.

Sabit yerleşimli belgeler (faturalar, sertifikalar) için nokta cinsinden belirgin bir yükseklik geçirin. Yükseklik belirgin olduğunda tampon eklenmez ve çıktı, istenen kâğıt boyutuyla tam olarak eşleşir (::renderHonorsExplicitHeightWithoutAutoBuffer tarafından doğrulanır).

Toplu iş süreçleri

İş süreci başına tek bir işleyici oluşturun ve onu yeniden kullanın. BrowserPool canlı tarayıcıyı yeniden kullanır ve 100 işleme sınırında otomatik olarak yeniden başlar.
100 işleme sınırına gelmeden yeni bir Chrome süreci istediğinizde, iş süreci kapanışında ve büyük toplu işler arasında close() çağrısını yapın.
Yıkıcı close() çağrısını yapar; ancak açıkça yapılan bir close() çağrısı belirleyicidir ve uzun süre çalışan süreçlerde tercih edilir.
Yeniden başlatma bildirimleri, işleme sayısıyla birlikte notice düzeyinde günlüğe kaydedilir; artan bir yeniden başlatma oranı, beklenenden daha ağır belgeleri gösterdiği için bu durumda uyarı verin.

Gözlemlenebilirlik

Bir PSR-3 günlükleyicisi enjekte edin. İşleyici şu olayları ve düzeyleri yayar:

Olay	Düzey	Bağlam
İşleme başlangıcı	`debug`	`size`, `width`, `height`
İşleme tamamlandı	`debug`	`pdfSize`, `contentHeight`
Tarayıcı başlatma	`info`	`binary`
Tarayıcı yeniden başlatma	`notice`	`count`
Tarayıcı kapatma	`debug`	`renderCount`

Hiçbir HTML, PDF baytı veya çıkarılan metin günlüğe kaydedilmez. Bu, yükleri işletim günlüklerinin dışında tutar ve Ulusal Standartlar ve Teknoloji Enstitüsü Özel Yayını (NIST SP) 800-92 günlük içeriği rehberliğiyle uyumludur. Gecikme hizmet düzeyi hedeflerini (SLO’lar) start/complete çiftinden; yeniden başlatma oranı uyarısını ise notice olaylarından oluşturun.

Dağıtım örüntüleri

Yan birim olarak Chrome: Chrome’u PHP iş süreciyle aynı kapsayıcıda çalıştırın; chrome_binary değerini sabitleyin. Korumalı alan özelliği olan bir kapsayıcı sağlayın; bkz. /integrations/artisan/chrome-renderer-setup/.
Kapsayıcısız / CLI: Artisan’ın bağımlılık enjeksiyonu kapsayıcısı yoktur. Komut satırı arabirimi (CLI) çalıştırıcılarında Premium e-fatura sözleşmeleri için EInvoiceServiceFactory kullanın; bkz. /integrations/artisan/boot-and-discovery/.
Kaynak sınırlama: render_timeout değerini yukarı akıştaki bir istek bütçesiyle ve bir ana makine cgroup/ulimit sınırıyla eşleştirin. Tehdit modeli için bkz. /integrations/artisan/security-and-operations/.

Uç durumlar ve tuzaklar

İşleme sırasında istisna yakalansa bile işleyici Chrome sayfasını yine kapatır (finally) ve havuz kullanılabilir durumda kalır.
Tek bir işleyiciyi threads/processes arasında yeniden kullanmak desteklenmez; bir işleyici tek bir Chrome sürecine sahiptir.
100 işlemlik yeniden başlatma sabittir; gecikme sıçramalarının öngörülebilir kalması için toplu işleri bunu göz önünde bulundurarak boyutlandırın.

Performans

Kararlı durum maliyetini köprü ek yükü değil, girdinin Chrome yerleşimi ile printToPDF toplamı belirler. keepAlive başlatma maliyetini işlemelere yayar. Her 100. işlemede bir gecikme sıçraması bekleyin (süreç yeniden başlatma); bunu ayrı bir olay gibi ele almak yerine SLO’larda gösterin.

Güvenlik notları

Üretim yolları güvenilmeyen HTML kabul eder. Yeniden okuyun: /integrations/artisan/security-and-operations/. Ağ engelleri yapılandırmadan bağımsız olarak geçerliliğini korur, ancak no_sandbox: true, Chrome süreç yalıtımını kaldırır ve girdiye duyulan güven gereksinimini artırır.

Ticari bağlam

Kapsayıcısız iş süreçlerinde Premium kurulu değilken EInvoiceServiceFactory null döndürür, böylece açık kaynak işleme yolu değişmeden devam eder. İşlenen belgede e-fatura gömme ve doğrulamayı etkinleştirmek için Pro/Enterprise sürümünü kurun.

Ayrıca bkz.

/integrations/artisan/quickstart/
/integrations/artisan/configuration/
/integrations/artisan/security-and-operations/
/integrations/artisan/chrome-renderer-setup/
/integrations/artisan/troubleshooting/