Tek motor, her çerçeve

SpecSpec: PSR-11 Container, §1.1.2PSR-11 Container §1.1.2SpecSpec: PSR-4 Autoloader, §3PSR-4 Autoloader §3

Bir bakışta

Büyüyen çoğu PHP ortamı, sonunda birden fazla çerçeveyle karşı karşıya kalır. NextPDF, her birini kendi koşullarında karşılayan tek bir PDF motorudur: Laravel, Symfony ve CodeIgniter için kendine özgü köprüler, artı hiçbirinde çalışmayan kod için bir bağımsız yol. Belge modeli paylaşılır. Yalnızca onu çağırma biçiminiz değişir.

Bu neden önemli

Her yığın için farklı bir PDF kitaplığı, sessiz bir vergidir. Her birinin kendi gariplikleri, kendi yazı tipi işleyişi, geçerlinin ne demek olduğuna dair kendi fikri vardır. Laravel hizmetinden doğru işlenen bir fatura, Symfony işçisinden ince bir farkla işlenebilir, çünkü onu farklı bir kitaplık çizmiştir. Şimdi arşivleme hedefiniz, imza yerleştirmeniz ve erişilebilirlik etiketleriniz, belgeyi hangi ekibin gönderdiğine bağlıdır. Hata raporu “PDF yanlış” der ve cevap, üç motordan hangisinin onu ürettiğine bağlıdır.

Tek bir motor üzerinde standartlaşmak, o yüzeyi çökertir. Bir PDF/A profilinin kararlaştırıldığı tek bir yer, sertifikalanacak tek bir yazı tipi hattı, güvenilecek tek bir doğrulayıcı vardır. İçinde bulunduğunuz çerçeve, belgenin doğru olup olmadığı sorusunda bir değişken olmaktan çıkar.

Kısa açıklama

• Çekirdek motor çerçeveden bağımsızdır. nextpdf/core, HTTP, yönlendirme veya konteyner kablolaması hakkında hiçbir şey bilmez. O bir PDF 2.0 motorudur ve başka bir şey değildir.
• Her köprü uyarlar, yeniden uygulamaz. Laravel, Symfony ve CodeIgniter paketleri size bir cephe ya da fabrika, bir HTTP yanıt yardımcısı ve bir kuyruğa alınmış ya da eşzamansız üretim yolu verir — aynı motorun üzerinde.
• Bir köprü belgenizi değil, çerçevenizi izler. Motoru nasıl çağırdığınızı değiştirir, motorun neler üretebileceğini asla.
• Bağımsız yol her zaman kullanılabilir. Bir CLI aracının, bir art alan sürecinin ya da bir kitaplığın köprü kuracağı bir çerçevesi yoktur; bir belgeyi doğrudan oluşturur.
• Tek bir belge modeli, dördünün hepsinde dolaşır. Aynı değer nesneleri, numaralandırmalar ve çıktı sözleşmesi her yerde görünür; böylece bir belge, çağrı noktaları arasında değişmeden hareket eder.

NextPDF buna nasıl yaklaşıyor

Mimari, kasıtlı bir ayrımdır. Motor varlıktır; köprü, bir çerçevenin deyimlerini konuşan ince bir bağdaştırıcıdır. Bir köprü, standart otomatik yükleme aracılığıyla paylaşılan çekirdeğin üzerine küçük bir ad alanı kaydeder (SpecSpec: PSR-4 Autoloader, §3PSR-4 Autoloader §3) ve konteyner sözleşmesi aracılığıyla bir belge geri verir (SpecSpec: PSR-11 Container, §1.1.2PSR-11 Container §1.1.2). Buradaki sessiz kahraman, o sözleşmedir: aynı tanımlayıcının iki çözümlemesinin farklı örnekler döndürmesine izin verir; bir köprünün size istek başına yeni, tek kullanımlık bir belge verirken ayrıştırılmış yazı tipi kaydını ve görüntü önbelleğini süreç genelinde tekil nesneler olarak tutması da tam olarak böyledir. Uzun ömürlü işçiler — Octane, RoadRunner, Swoole, Messenger — yapı gereği, istekler arası durum sızıntısı olmadan amorti edilmiş yazı tipi ayrıştırması elde eder.

Dört deyim yalnızca yüzeyde farklılaşır:

1. Core enginenextpdf/core — the framework-agnostic PDF 2.0 engine; the single shared document model, value objects, and output contract.
2. Laravel bridgenextpdf/laravel — auto-discovered provider, a Pdf facade, a PdfResponse helper, and a queued GeneratePdfJob.
3. Symfony bridgenextpdf/symfony — an auto-registered bundle, an injectable PdfFactory, a PdfResponse, and an optional Messenger handler.
4. CodeIgniter bridgenextpdf/codeigniter — a service and pdf() helper, a Pdf library over a disposable Document, and a PdfResponse.
5. StandaloneNo framework to bridge from — construct a Document directly in a CLI tool, daemon, or library.

One framework-agnostic core engine reached through four idiomatic surfaces: a Laravel facade, an injected Symfony factory, a CodeIgniter service, or a directly constructed standalone document — each handing back the same disposable Document model.

Diyagramı soldan sağa okuyun; ders, simetridir. Her yüzey aynı Document’a çözümlenir. Laravel cephesi, Symfony fabrikası, CodeIgniter hizmeti ve bağımsız yapıcı, tek bir odaya açılan dört kapıdır.

Pratik örnek

Her deyimle ifade edilmiş aynı üç niyet satırı. Belgeyi oluşturan gövde — sayfalar, yazı tipleri, hücreler, imzalama, uygunluk — dördünde de aynıdır, çünkü o aynı motordur.

<?php

declare(strict_types=1);

// Laravel — resolve a fresh document from the container.
use NextPDF\Contracts\PdfDocumentInterface;
$document = app(PdfDocumentInterface::class);

// Symfony — inject the factory, then ask it for a document.
use NextPDF\Symfony\Service\PdfFactory;
$document = $factory->create(); // PdfFactory injected into your service

// CodeIgniter — pull it from the Services layer.
use NextPDF\CodeIgniter\Config\Services;
$document = Services::pdfDocument();

// Standalone — no framework; construct it directly.
use NextPDF\Core\Document;
$document = Document::createStandalone();

// From here, the code is identical regardless of how $document arrived.
$document->addPage();
$document->cell(0, 10, 'One engine, every framework', newLine: true);
$bytes = $document->getPdfData();

İlk satırlar tek farktır. Sonrasındaki her şey taşınabilirdir: belge oluşturan bir hizmeti Symfony’den bağımsız bir işçiye taşıyın; işleme kodu değişmez, çünkü dayandığı sözleşme değişmemiştir.

Human-factors note:Human-factors note

Standartlaşmak, teknik olmaktan çok bir ekip kararıdır. Her yığın PDF’leri aynı motorla çizdiğinde, yazı tipi hattındaki bir düzeltme ya da arşivleme profilinin sıkılaştırılması bir kez iner ve herkese ulaşır. İnceleyiciler tek bir API öğrenir. Yeni bir hizmet, sertifikalı yolu bedava devralır. Maliyet, çerçeve başına tek bir bağımlılık benimsemektir; kazanç ise “PDF yanlış” ifadesinin, onu hangi kitaplığın çizdiği hakkında bir soru olmaktan çıkmasıdır.

Yaygın yanlış anlama

Sık yapılan varsayım, çerçeve köprüsünün yetenekler açtığıdır — motoru doğrudan çağırmak yerine nextpdf/laravel’i kurduğunuz için uzun vadeli imza doğrulamasının ya da yapılandırılmış e-faturalamanın geldiği. Gelmez. Bir köprü çağrı noktasını değiştirir, motorun erişimini asla. PDF/A çıktısı ve PAdES temel imzalaması gibi çekirdek yetenekler açık kaynaklıdır ve her yüzeye ulaşır; gelişmiş yetenekler bir sürümle açılır ve sonra herhangi bir köprü ya da bağımsız yol aracılığıyla eşit biçimde kullanılabilir. Bir çerçeve entegrasyonu seçmek, bir özellik kümesi seçmek değildir.

Aynanın öbür yüzündeki yanlış anlama, “tek motor”un her belge için tek bir işleme yolu anlamına gelmesi gerektiğidir. Gelmez. Süreç içi motor PDF’i doğrudan işler; bir belge gerçekten tarayıcı düzeyinde bir yerleşim motoruna gereksindiğinde, bir işleyici paketi bununla ilgilenir. İşleme ve çağırma, ayrı eksenlerdir — entegrasyon karar kılavuzu, onları eşleştiren yerdir.

Sınırlar ve kapsam

Bir köprü, motorun neler işleyebileceğini genişletmez. Dürüst sınır budur ve asıl mesele de odur: yetenek, çekirdekte ve katmanda yaşar, ona ulaştığınız bağdaştırıcıda değil.

Framework bridges over one engine — edition availability

Edition	Availability
Core	○ Every bridge (Laravel, Symfony, CodeIgniter) and the standalone path are Apache-2.0 and work against Core. They adapt or expose the engine; they do not gate features and do not change what it can produce.
Pro	○ Advanced capabilities such as long-term signature validation (PAdES B-LT and B-LTA) are unlocked by an edition, then reached identically through any bridge or standalone — never by switching framework. PDF/A archival output and PAdES baseline signing (B-B and B-T) are already in Core, available the same way through every surface.
Enterprise	○ Structured e-invoicing (EN 16931) and deeper compliance tooling are edition capabilities too, likewise the same whichever surface calls the engine, while conformance validation itself ships in Core.

Açıkça belirtmeye değer iki sınır daha vardır. İlk olarak, her köprü kendi çerçevesinin güncel bir ana sürümünü izler — Laravel, Symfony ve CodeIgniter’in her biri desteklenen bir aralığı sabitler; dolayısıyla “her çerçeve”, her geçmiş sürümü değil, her birinin desteklenen sürümünü ifade eder; her paketin kendi belgelerini, API’si için yetkili olarak ele alın. İkinci olarak, köprüler çerçeve bağdaştırıcılarıdır, işleme arka uçları değil. Bir belge tam bir tarayıcı yerleşim motoruna gereksindiğinde, bu, motoru hangi çerçevenin çağırdığından bağımsız bir işleyici seçimidir.

İlgili belgeler

• Entegrasyon karar kılavuzu — standartlaşmak yerine karar vermeniz gerektiğinde, işleyiciler ve Connect hizmet yüzeyi dâhil, kullanım durumundan pakete eşleme.
• Açık çekirdek, bağımlılık yok — motorun neden varlık olduğu ve köprülerin neden ince olduğu, böylece standartlaşmanın sizi tuzağa düşürmemesi.
• HTML hattı — süreç içi motorun neyi kapsadığı, böylece bir tarayıcı işleyicisinin ne zaman ayrı bir soru olduğunu bilmeniz.
• PHP 8.4 temelleri — her köprünün ve bağımsız yolun paylaştığı çalışma zamanı tabanı.

Sözlük

• Çekirdek motor — nextpdf/core, her köprünün ve bağımsız yolun üzerine inşa edildiği çerçeveden bağımsız PDF 2.0 motoru.
• Çerçeve köprüsü — motoru bir çerçevenin deyimlerine — cephe, fabrika, yanıt, kuyruğa alınmış iş — yeteneklerini değiştirmeden uyarlayan bir entegrasyon paketi (Laravel, Symfony, CodeIgniter).
• Bağımsız yol — çekirdek motoru, hiçbir çerçeve olmadan, bir Document’ı kendiniz oluşturarak doğrudan kullanmak; CLI araçları, art alan süreçleri ve kitaplıklar için yol.
• Tek kullanımlık belge — tek kullanımlık Document sözleşmesi: oluştur, yay, at. Her konteyner çözümlemesi yeni bir tane döndürür; böylece uzun ömürlü bir işçide istekler arasında hiçbir durum sızmaz.
• PAdES — PDF Advanced Electronic Signatures, PDF imzalaması için ETSI profil ailesi. Temel imzalama (B-B ve B-T) Core’dadır; uzun vadeli doğrulama (B-LT ve B-LTA) gelişmiş bir sürüm yeteneğidir. Her ikisi de herhangi bir yüzey aracılığıyla erişilir ve imzalama sayfalarında ayrıntılı olarak ele alınır.