NextPDF'i üretimde işletme

Spec: ISO 9241-112:2025, §6.1.2.3 Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Evidence: Artifact-backed

Bir bakışta

Bir PDF motorunu üretimde çalıştırmak, “çağır ve baytları gönder” demek değildir. Bir işleme sağlıklı olduğunda size ne söylediği, sağlıklı olmadığında ne yaptığı, gözlemlenebilirlik için nereden bağlandığınız ve hangi tehlikeli işlemleri sessizce gerçekleştirmeyi reddettiği sizin sorumluluğunuzdadır. Bu sayfa işletim yüzeyini açıklar: NextPDF’in üretim ortamında çalıştığı gün bir ekibin üstlendiği dikişleri ve özellikleri.

Bunun neden önemli olduğu

Bir belge motoru, tipik bir hizmetten farklı biçimde başarısız olur. Hatalar çoğunlukla sessizdir: yine de dosya üreten bozulmuş bir yerleşim, çıktıyı değiştiren engellenmiş bir dış kaynak, imzalı görünen imzasız bir belge. Motor bunları gizlerse, bunları gösterge panosunda değil, müşteriden öğrenirsiniz. Motor bunları açığa çıkarırsa, bir olaya değil, uyarıya ve çalıştırma kılavuzu girdisine dönüşürler.

Bu nedenle işletilebilirlik, sonradan eklediğiniz bir özellik değildir. Motorun her işleme hakkında size gerçeği söyleyecek biçimde inşa edilip edilmediğiyle ilgilidir; NextPDF de bu biçimde inşa edilmiştir.

Kısa özet

Her işleme, yapılandırılmış bir rapor üretir. Başarı, sayfa sayısı, işleme süresi, en yüksek bellek, uyarı kodları, geri çekilme örnekleri, engellenmiş dış kaynaklar — gösterge panonuz için JSON olarak serileştirilebilir.
Motor, türlenmiş yaşam döngüsü olayları yayar — hiçbir dinleyici yokken sıfır ek yük getiren bir PSR-14 dağıtıcısı üzerinden; denetim ve metrik kancalarınız oraya bağlanır.
Hata kipleri sessiz değil, açıktır. Bozulmuş eşlik raporlanır. Üst düzey imza yüzeyi hızla başarısız olur. Çıktı atomik olarak yazılır. Süreç içi HTML yolunda dış alt kaynak getirme işlemi, tasarımı gereği kapalıdır.
Connect’te tehlikeli işlemler bir insan gerektirir. NextPDF yapay zekâ aracılarına açıldığında, yıkıcı veya gizlilik açısından kritik araçlar bir onay sorgulamasının arkasına alınır — en önemli işletim özelliği, sizin göreceğiniz yerde açıkça belirtilir (ISO 9241-112 §6.1.2.3).

NextPDF buna nasıl yaklaşır

İşletim modeli tek bir ilkeye dayanır: bir işleme, ne yaptığı konusunda asla yalan söylememelidir. Bunu somutlaştıran üç mekanizma vardır — bir rapor, bir olay akışı ve bir dizi arıza-emniyetli davranış. Motor bir aracı tarafından sürüldüğünde dördüncü mekanizma devreye girer.

Observe each render Collect the per-render report — success, timing, peak memory, warnings, fallbacks, blocked-resource counts — into your telemetry sink.
Subscribe to lifecycle events Attach PSR-14 listeners for document, security, and serialization events for audit logging and metrics.
Detect degradation Treat degraded-parity and fallback signals as health indicators, not noise. They mean the output differs from the ideal render.
Gate the dangerous path In Connect, route destructive or privacy-critical operations through the human confirmation gate before they execute.

İşletim yüzeyi uçtan uca: araçlandırma isteğe bağlıdır ve kullanılmadığında sıfır maliyetlidir; hata kipleri veri ya da hızlı hata olarak açığa çıkar, asla sessizce yanlış bir dosya olarak değil.

Rapor, toplanmak üzere tasarlanmış değişmez bir anlık görüntüdür. İşlemenin başarılı olup olmadığını, ne kadar sürdüğünü, en yüksek bellek kullanımını, kod başına uyarı sayılarını, güvenli bir işleme kipinin etkin olup olmadığını, kaç dış kaynak isteğinin reddedildiğini ve hangi yerleşim geri çekilmelerinin gerçekleştiğini taşır. Bu son grup, işletim açısından önemlidir. Bir filo genelinde “flex, block’a geri çekildi” sayısının yükselmesi, bir şablonun değiştiğine dair sinyaldir ve bunu herhangi bir kullanıcı şikâyet etmeden önce görürsünüz.

Olay dikişi PSR-14 uyumludur ve bilinçli olarak hafiftir. Bir olay sınıfı için kayıtlı dinleyici yoksa dağıtıcı hemen geri döner. Bu nedenle, dikişi eklemek siz onu kullanana kadar hiçbir maliyet getirmez. Belge oluşturma ve çıktı, sayfa ekleme, içerik ve yazı tipi yükleme, şifreleme uygulama, imza uygulama ve PDF serileştirme için türlenmiş olaylar vardır. Bunlar, bir denetim günlüğünün ya da metrik sayacının gerçekten önemsediği noktalardır. Gözlemlenebilirlik sözleşmeleri (metrik sayacı, ölçer, histogram, izleme aralığı, HSM denetim günlüğü) işlem yapmayan uygulamalarla birlikte gelir. Bu nedenle motor, sıfır telemetri bağlantısıyla tam işlevseldir ve gerçek uygulamaları bağladığınızda gözlemlenebilir hâle gelir.

Akılda tutulması gereken tek özellik şudur: NextPDF, sessizce yanlış bir belge üretmek yerine yüksek sesli, hızlı bir hatayı veya dürüst bir bozulma raporunu yeğler. Üst düzey imza çağrısı, imzasız bir dosya yaymaktansa hızla başarısız olur. Çıktı atomik olarak yazılır, böylece eşzamanlı bir okuyucu eski dosyayı ya da yeni dosyayı görür, asla yarı yazılmış bir dosya görmez. Süreç içi HTML işleyicisi, uzak alt kaynakları getirecek biçimde yapılandırılamaz. Sunucu taraflı istek sahteciliği ve bulut üst veri yoklamaları, hatırlamanız gereken bir ayarla değil, tasarımı gereği kaldırılmıştır. İşletim açısından uyarılarınız, hatanın aşağı yöndeki sonucunda değil, hatanın kendisinde tetiklenir.

Kanıtların söylediği

Bu sayfa yapıt desteklidir: işletim yüzeyi, bugün bağlayabileceğiniz gerçek sınıflar ve sözleşmelerdir. Evidence: Artifact-backed

Rapor koddur: RenderReport, tam olarak tanımlanmış alanlara sahip değişmez, JSON olarak serileştirilebilir bir değer nesnesidir — başarı, sayfa sayısı, işleme süresi, en yüksek bellek, kod başına uyarı sayıları, güvenli kip bayrağı, dış kaynak reddetmeleri, geri çekilme örnekleri, zaman damgası. Olay dikişi koddur: sıfır ek yüklü bir hızlı yola ve belge, güvenlik, içerik ve yazıcı olaylarını kapsayan türlenmiş bir olay hiyerarşisine sahip bir PSR-14 EventDispatcher. Arıza-emniyetli davranışlar koddur. Atomik çıktı yazımı, belgelenmiş bir time-of-check/time-of-use açığını kapatır. Süreç içi HTML yolunun uzak-alt-kaynak-yok güvencesi, tasarımı gereği uygulanan bir @security sözleşmesidir. Üst düzey imza yüzeyi, imzasız bir PDF yaymaktansa engelleyici bir tanılama yükseltir.

Aracı güvenliği özelliği, NextPDF Connect içinde kodla uygulanır: Evidence: Code-backed dört düzeyli bir risk modeli (güvenli, dikkat, inceleme, onay-gerekli) ve onay-gerekli düzeyindeki bir araç için tek kullanımlık bir sorgulama belirteci veren ve siz o belirteci geri iletene kadar ilerlemeyi reddeden bir onay geçidi. Bir aracın riski tam olarak iki kaynaktan gelir: kendi bildirimi ve riski yalnızca yükseltebilen işletmen tarafından yapılan geçersiz kılma. Bu nedenle tehlikeli yüzey sessizce genişletilemez.

Bu sayfanın düzenlenme biçimi de standart desteklidir: Spec: ISO/IEC/IEEE 26514:2022, §3.x162 işletim bilgisinin, okuyucunun gerçekleştirdiği görevlere göre yapılandırılmasını önerir, bu yüzden dört aşama gözlemleme, abone olma, saptama ve geçit denetimine eşlenmiştir.

Uygulamalı örnek

Aşağıdaki kod gözlemlenebilirlik dikişini gösterir: yaşam döngüsü olaylarını ve işleme raporunu telemetriye dönüştüren bir PSR-14 dinleyicisi. Burada amaç dikişi örneklemektir. Metrik havuzu sizindir.

<?php

declare(strict_types=1);

use NextPDF\Event\Document\DocumentOutputEvent;
use NextPDF\Event\Security\SignatureAppliedEvent;
use Psr\Log\LoggerInterface;

/**
 * Audit + metrics listener for production operation.
 *
 * Attaching this costs nothing until events fire — the dispatcher
 * short-circuits when no listener is registered for an event class.
 */
final readonly class OperationsListener
{
    public function __construct(
        private LoggerInterface $logger,
    ) {}

    public function onSignatureApplied(SignatureAppliedEvent $event): void
    {
        // Compliance trail: who signed, at what level, why.
        $this->logger->info('pdf.signature.applied', [
            'level'  => $event->signatureLevel,
            'signer' => $event->signerName,
            'reason' => $event->reason,
        ]);
    }

    public function onDocumentOutput(DocumentOutputEvent $event): void
    {
        // Pair this with the engine's RenderReport for the full picture:
        // success, render_time_ms, peak_memory_bytes, fallback_occurrences.
        $this->logger->info('pdf.document.output', [
            'event' => $event::class,
        ]);
    }
}

Burada önemli olan gövde değil, dikiştir. Motor size türlenmiş olaylar ve yapılandırılmış bir rapor verir. Neyi ileteceğiniz, örnekleyeceğiniz ya da neye dair uyarı oluşturacağınız, motorun bilinçli olarak size bıraktığı bir işletim kararıdır.

Yaygın yanlış anlama

İşletim açısından yaygın yanlış anlama şudur: “bayt döndürdüyse, çalışmıştır.” Bir işleme başarılı olabilir ve yine de bozulmuş olabilir. Bir yerleşim geri çekilmiş, bir dış görüntü engellenip sessizce kaybolmuş, bir özellik etkin kipte desteklenmemiş olabilir. Baytlar vardır. Ancak belge, şablonun amaçladığı belge değildir. Motor bunları uyarılar ve geri çekilme sayıları olarak raporlar; tam da “bayt döndü” ifadesi “doğru işlendi” ile karıştırılmasın diye. Dönüş değerini tek başarı sinyali olarak ele almak, bu yüzeyin önlemek için var olduğu hatadır.

Connect’e özgü ikinci yanlış anlama da şudur: PDF araçları yalnızca “salt işleme” yaptığı için bunları bir aracıya açmak güvenlidir. Yıkıcı, üzerine yazan veya gizlilik açısından kritik işlemler, bir nedenle bir insan onay sorgulamasının arkasına alınmıştır. Bu geçidi atlamak ya da otomatik yanıtlamak, tam olarak ortadan kaldırdığı riski yeniden ortaya çıkarır.

Sınırlar ve kapsam

Motor araçlandırma sağlar; gözlemlenebilirlik yığınınızı çalıştırmaz. Bir rapor ve türlenmiş olaylar yayar; toplama, uyarı verme, gösterge panoları ve saklama sizindir.
İşlem yapmayan gözlemlenebilirlik varsayılandır. Metrikler, izlemeler ve HSM denetim günlükleri, gerçek uygulamaları bağlayana kadar etkisizdir — tasarım gereği, böylece motor sıfır bağlantıyla çalışır. Ancak bu, siz katılmayı seçene kadar hiçbir şeyin kaydedilmediği anlamına gelir.
SSRF arıza-emniyeti, süreç içi HTML yoluna uygulanır. Dış işleyici köprüleri (browser/Office) doğaları gereği dışarı giden çağrılar yapar ve kendi taşıma sıkılaştırmalarını beraberinde getirir. Bu güvence özellikle süreç içi yolla ilgilidir.
İnsan onayı geçidi bir NextPDF Connect özelliğidir. Aracı tarafından sürülen çağrıyı yönetir. Genel bir PDF özelliği değildir ve bağımsız değişken karmasına değil, araç adı ile bir nonce üzerine bağlanır.
Üst düzey imza yüzeyi hızla başarısız olur. Bağlanmış bir imzalayıcı değildir. İşletim açısından, tanılamasını sinyal olarak ele alın ve asıl imzalamayı yapmak için bağlanmış alt düzey yolu kullanın.
Bu sayfa yapıt desteklidir: adı geçen her dikiş gerçek bir sınıf ya da sözleşmedir, ancak bunları iyi işletmek sizin sorumluluğunuzdadır.

Observability and operational seams — edition availability
Edition	Availability
Core	`RenderReport`, PSR-14 olay dağıtıcısı ve türlenmiş olay hiyerarşisi, işlem yapmayan gözlemlenebilirlik sözleşmeleri, atomik çıktı yazımları ve süreç içi SSRF arıza-emniyetinin tümü Core’dadır.
Pro	İmzalama kullanıma girdiğinde işletim açısından anlam taşıyan güvenlik yaşam döngüsü olayları (şifreleme/imza uygulandı) ekler.
Enterprise	HSM denetim günlüğü dikişini ve doğrulama bulgularını işletim sinyalleri olarak ekler; NextPDF Connect, aracı tarafından sürülen, yüksek riskli işlemler için insan onayı geçidini ekler.

İlgili belgeler

Boru hattı modeli — bu gözlemlenebilirlik dikişlerini mümkün kılan aşamalı yapı ve nerede yer aldıkları.
HSM destekli imzalama — donanım destekli anahtarların işletim biçimi ve denetim sınırının nerede yer aldığı.
Yüksek hacimli belge üretimi — işleme başına raporu ölçekte kapasite ve sağlık sinyallerine dönüştürme.

Sözlük

RenderReport — birincil sağlık sinyali olarak kullanılan, motorun işleme başına ürettiği değişmez, JSON olarak serileştirilebilir metrik anlık görüntüsü.
PSR-14 — bir olay dağıtıcısı için PHP standardı; NextPDF’in dağıtıcısı uyumludur ve kullanılmadığında sıfır ek yüklüdür.
Bozulmuş eşlik — tamamlanan ancak bir özellik geri çekildiği ya da desteklenmediği için çıktısı ideal olandan farklı olan bir işleme.
Geri çekilme örneği — yerleşim motorunun daha basit bir davranışla değiştirdiği, kayıt altına alınmış bir örnek (örneğin flex’in block olarak işlenmesi).
SSRF (Server-Side Request Forgery) — bir sunucunun kandırılarak iç hedeflere istek yapmasının sağlandığı bir saldırı. Süreç içi HTML yolunda tasarımı gereği kaldırılmıştır.
Onay geçidi — yüksek riskli, aracı tarafından çağrılan bir araç çalışmadan önce insan tarafından iletilen tek kullanımlık bir belirteç gerektiren NextPDF Connect mekanizması.
Atomik yazma — eşzamanlı bir okuyucunun ya önceki dosyayı ya da eksiksiz yeni dosyayı gördüğü, asla kısmi bir dosya görmediği bir çıktı yazımı.