Entegrasyon karar kılavuzu

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

Genel bakış

NextPDF ekosistemi, küçük bir çekirdek motor ve odaklı paketlerden oluşur: framework köprüleri, iki HTML işleyici, bir edge işleyici ve bir yürütme sunucusu. Bu sayfa, gerçek kullanım senaryolarını her paketin gerçekten sunduklarına dayanarak uygun pakete eşler. Seçim sizde kalır; bu seçim belgelerin ima ettiğine değil, kanıta dayanır.

Bunun önemi

Yanlış entegrasyonu seçmek, maliyeti hemen görünmeyen bir karara dönüşür. Sürecin içindeki motor belgeyi doğru işleyebilecekken uzak bir tarayıcı işleyicisi seçerseniz, her PDF’ye bir ağ adımı ve bir erişilebilirlik bağımlılığı eklemiş olursunuz. Gerçekten tam bir tarayıcı yerleşim motoruna ihtiyaç duyan bir belge için sürecin içindeki motoru seçerseniz, zor fark edilen biçimde hatalı bir dosya elde edersiniz. Seçtiğiniz paket gecikmeyi, hata biçimlerini ve operasyonel yüzeyi şekillendirir; bu nedenle kararın açıkça verilmesi gerekir.

Kısa özet

• Çekirdek motorla başlayın. Diğer her şey ek katmandır. Sürecin içindeki motor belgenizi doğru işliyorsa, hiçbir işleyici paketine ihtiyacınız yoktur.
• framework köprüsü, belgenizi değil, framework’ünüzü izler. Laravel, Symfony ve CodeIgniter entegrasyonları, bir facade ya da factory, bir PDF yanıtı, kuyruğa alınmış oluşturma ve otomatik keşif elde etmeniz için vardır — motorun ne işleyebileceğini değiştirmezler.
• İşleyiciyi yalnızca CSS’e bağlı gereksinimler bir tarayıcı gerektirdiğinde kullanın. Artisan (yerel Chrome) ve Cloudflare (edge tarayıcı) tam da bunun için vardır; Gotenberg, Office belgelerini içe almak için vardır.
• Çağıran taraf bir servis ya da yapay zeka aracısıysa ve bir PHP çağrısı değilse Connect’i kullanın. Motoru MCP, REST ve gRPC üzerinden, tehlikeli işlemler için insan onayı kapısıyla açar.

NextPDF buna nasıl yaklaşır

Ekosistem, her paketin tek bir işi olacak biçimde bilinçli olarak katmanlandırılmıştır. Çekirdek motor PDF’yi süreç içinde işler. Bir framework köprüsü, o motoru bir framework’ün deyimlerine uyarlar. Bir işleyici paketi, süreç içindeki motor doğru araç olmadığında HTML ya da Office yerleşimini harici bir motora devreder. Connect, motoru bir ağ servisine dönüştürür. Bu paketlerden hiçbiri bir diğerinin sorumluluğuyla örtüşmez; kararı anlaşılır kılan da budur. Birbiriyle rekabet eden araçlar arasında seçim yapmıyorsunuz. Birbirini tamamlayan araçları bir araya getiriyorsunuz.

Kararı kullanım senaryosuna göre verin. Tablo, her senaryoyu uygun pakete eşler ve kabul ettiğiniz ödünleşimi belirtir.

Kullanım senaryosu	Uygun paket	Gerçekte ne sunar	Kabul ettiğiniz ödünleşim
Laravel uygulamasında PDF	nextpdf/laravel	Otomatik keşfedilen servis sağlayıcı, Pdf facade, PdfResponse (satır içi/indirme/akış, OWASP başlıkları), kuyruğa alınmış bir GeneratePdfJob (tries/timeout/backoff ile), Octane açısından güvenli kilitli kayıt defterleri	Bir Laravel 12 bağımlılığı; motorun yetenekleri değişmez
Symfony uygulamasında PDF	nextpdf/symfony	Otomatik kaydedilen bundle, enjekte edilebilir PdfFactory, PdfResponse, eşzamansız oluşturma için isteğe bağlı bir Messenger işleyicisi	Bir Symfony 7.2 bundle bağımlılığı; yetenekler değişmez
CodeIgniter 4 uygulamasında PDF	nextpdf/codeigniter	service('pdf') / pdf() yardımcısı, bir Pdf kitaplığı (atılabilir bir Document nesnesini sarar), bir PdfResponse, isteğe bağlı kuyruğa alınmış bir iş	Bir CodeIgniter 4.6 bağımlılığı; yetenekler değişmez
Belge, sürece yakın çalışan tam tarayıcı CSS’si (flex/grid/web yazı tipleri) gerektiriyor	nextpdf/artisan	CDP üzerinden headless Chrome; işlendikten sonra metin seçilebilir kalsın diye bir Form XObject olarak geri içe aktarılır; bir tarayıcı havuzu	Ana makinenizde bir Chrome çalışma ortamı ve bunun memory/process maliyeti
Office belgeleri (.docx, .xlsx) PDF’ye	nextpdf/gotenberg	SSRF’ye karşı sağlamlaştırılmış, IP’ye sabitlenmiş aktarımla bir Gotenberg mikroservisine PSR-18 köprüsü	Harici bir Gotenberg servisi ve bir ağ bağımlılığı
Edge’de HTML→PDF / yerel Chrome yok	nextpdf/cloudflare	Sabitlenmiş aktarım üzerinden Cloudflare Browser Rendering; isteğe bağlı yerel Chrome yedeğiyle	Bir Cloudflare hesabı ve bir ağ bağımlılığı; yedek için Artisan gerekir
Motorun bir servis ya da yapay zeka aracısı tarafından kullanılması	nextpdf/server (Connect)	Tek motor; MCP (stdio), REST (OpenAPI 3.1) ve gRPC üzerinden; isteğe bağlı bağımlılıkla araç keşfi; yüksek riskli araçlar için bir insan onayı kapısı	Bir servis yüzeyinin işletilmesi; belirlenimci yürütme disiplini

Human-factors note: Human-factors note

Bunlar iki bağımsız karardır; ekipler bunları sık sık aynı soru gibi ele alır. Bir framework köprüsü, zaten kullandığınız framework tarafından belirlenir — motorun neyi işlediğini genişletmez ya da kısıtlamaz. İşleyici ise belge tarafından belirlenir. Belirleyici soru, sürecin içindeki CSS motorunun yeterli olup olmadığı ya da belgenin gerçekten bir tarayıcı yerleşim motoru gerektirip gerektirmediğidir. Bir framework köprüsüne ihtiyaç duyup işleyiciye duymayabilir, bir işleyiciye duyup köprüye duymayabilir, her ikisine ya da hiçbirine duymayabilirsiniz. Bunları tek bir soru gibi ele almak en yaygın entegrasyon hatasıdır; bu sayfanın bunları ayırmasının nedeni de budur.

Kanıtlar ne diyor

Bu sayfa editöryel niteliktedir — bir yönlendirme kararıdır — ama yönlendirme, her paketin manifestinde ve ana sınıflarında bulunanlara dayanır.

Evidence ¶ Editorial Evidence: Editorial

Köprüler somuttur ve paralel bir yapıdadır. Her biri, framework bağımlılığını ve otomatik kayıt mekanizmasını kendi composer.json dosyasında bildirir (extra.laravel.providers, extra.symfony.bundles, CodeIgniter Registrar). Her biri ayrıca bir PdfResponse, atılabilir bir belge bağlaması ve isteğe bağlı kuyruğa alınmış bir iş sunar. Hiçbiri bir işleme yeteneği eklemez — aynı motoru uyarlarlar. İşleyiciler somuttur ve birbirinden farklıdır. Artisan, chrome-php/chrome paketine bağımlıdır ve metni seçilebilir tutmak için Chrome PDF’sini bir Form XObject olarak geri içe aktarır. Gotenberg ve Cloudflare, açıkça SSRF’ye karşı sağlamlaştırılmış, IP’ye sabitlenmiş aktarımlara sahip PSR-18 HTTP köprüleridir. Worker erişilemez olduğunda Cloudflare, Artisan’a geri dönebilir. Connect’in composer.json dosyası, üç aktarımı ve araçların kendi paketleri kuruldukça ortaya çıktığı bir isteğe bağlı bağımlılık modelini bildirir; bu model, insan onayı kapısı bulunan dört düzeyli bir risk modeliyle yönetilir.

Bu sayfanın sizi yönlendirme biçimi, yapısal olarak standart desteklidir: Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 okuyucuların, içeriğin amaçlarına hizmet edip etmediğini hızla belirleyebilmesi gerektiğini söyler ve Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 bağlantıların ve referansların hedeflerini belirtmesini gerektirir — bu nedenle tablo, belirsiz biçimde “bir entegrasyon”a atıfta bulunmak yerine somut paketi ve ödünleşimi adlandırır.

Pratik örnek

Karar, bir özellik karşılaştırması değil, doğrudan sorulardan oluşan bir dizidir. Aşağıdaki akış, yaygın durumları çözer.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

Akışın anlattığı ders budur: işleme ve çağırma ayrı eksenlerdir. Bunları birlikte yanıtlamak, ekiplerin ihtiyaç duymadıkları bir uzak işleyiciyle ya da bağımlılık sorunlarını çözmeyen bir köprüyle nasıl baş başa kaldığını açıklar.

Yaygın yanlış anlama

En yaygın yanlış anlama şudur: “PDF oluşturmak için bir işleyici paketine ihtiyacım var.” İhtiyacınız yok. Çekirdek motor, PDF’yi süreç içinde oluşturur. İşleyici paketleri yalnızca tarayıcı düzeyinde bir yerleşim motorunun gerektiği ya da kaynağın bir Office belgesi olduğu özel durumlar için vardır. Sürecin içindeki motor zaten doğru dosyayı ürettiğinde, refleks olarak bir işleyici benimsemek, hiçbir fayda sağlamadan bir çalışma zamanı bağımlılığı ve bir hata biçimi ekler.

Bunun ters yöndeki karşılığı olan yanlış anlama şudur: “framework köprüsü yeni yetenekler açar.” Açmaz. Bir köprü, motoru nasıl çağırdığınızı değiştirir — facade, factory, yanıt, kuyruğa alınmış iş — onun ne üretebileceğini değil. İmzalama, PDF/A ve yapılandırılmış faturalar, bir köprü üzerinden mi yoksa doğrudan mı çağırdığınızdan bağımsız olarak aynı kalan, katman ve motor meseleleridir.

Sınırlar ve kapsam dışılıklar

• Bu sayfa yönlendirir; karşılaştırma ölçütü oluşturmaz ya da sıralama yapmaz. Her paketin ne sunduğunu ve ödünleşimi belirtir. Bunlar arasında seçim yapmak, kendi kısıtlarınıza göre sizin kararınızdır.
• Paket yetenekleri, belirli bir andaki manifestlerinden ve ana sınıflarından okunur. Her paketin güncel API’si için kendi belgelerini yetkili kabul edin. Bu kılavuz bir haritadır, spesifikasyon değildir.
• Hiçbir rakip karşılaştırması sunulmaz ya da ima edilmez. Tek konu, NextPDF ekosistemi ve parçalarının birbirine nasıl uyduğudur.
• framework köprüsü ile işleyici bağımsız seçimlerdir. Bir köprü motor yeteneğini genişletmez; bir işleyici bir framework’e bağımlı değildir.
• Harici işleyiciler bir erişilebilirlik bağımlılığı ekler. Gotenberg ve Cloudflare bir ağ çağrısı ve işletilecek bir servis getirir; bu, gizli bir maliyet değil, kabul edilen ödünleşimdir.
• Katman-kapılı yetenekler entegrasyondan bağımsızdır. Ticari özellikler herhangi bir köprü ya da işleyici tarafından değil, katman tarafından açılır; aşağıdaki kapsam sınırına bakın.

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ Her entegrasyon paketi (köprüler, Artisan, Gotenberg, Cloudflare, Connect) Core ile çalışır ve Apache-2.0 lisanslıdır. Motoru uyarlar ya da dışa açarlar; özellikleri kapılayan taraf onlar değildir.
Pro	○ Ticari yetenekler (PAdES baseline imzalama, PDF/A, gelişmiş barkodlar) katman tarafından açılır ve ardından entegrasyonu değiştirerek değil, herhangi bir entegrasyon üzerinden kullanılabilir hale gelir.
Enterprise	○ Yapılandırılmış faturalar, doğrulama ilkeleri ve Connect yüksek riskli araçlar için insan onayı kapısı katman yetenekleridir, aynı şekilde entegrasyondan bağımsızdır.

İlgili belgeler

• HTML işlem hattı — sürecin içindeki CSS motorunun neyi kapsadığı; böylece bir tarayıcı işleyicisine gerçekte ne zaman ihtiyaç duyulduğunu bilirsiniz.
• NextPDF ne zaman kullanılmamalı — motorun doğru araç olmadığı belge sorunlarına ilişkin dürüst bir sınır.
• PHP 8.4 temelleri — her paketin paylaştığı çalışma zamanı tabanı ve geri taşıma yolunun neyi koruduğu.

Sözlük

• Çekirdek motor — nextpdf/core, diğer her paketin üzerine kurulduğu, sürecin içindeki PDF 2.0 motoru.
• framework köprüsü — motoru, yeteneklerini değiştirmeden bir framework’ün deyimlerine uyarlayan bir entegrasyon paketi (Laravel/Symfony/CodeIgniter).
• İşleyici paketi — sürecin içindeki motor doğru araç olmadığında HTML ya da Office yerleşimini harici bir motora (Artisan/Cloudflare/Gotenberg) devreden bir paket.
• Form XObject — yeniden kullanılabilir bir PDF içerik parçası; Artisan, tarayıcıda işlenmiş bir sayfayı, metni seçilebilir kalsın diye bunlardan biri olarak içe aktarır.
• NextPDF Connect — nextpdf/server, motoru belirlenimci bir yürütme yüzeyiyle MCP, REST ve gRPC üzerinden açan paket.
• İsteğe bağlı bağımlılık — Connect’in, isteğe bağlı NextPDF paketleri kuruldukça araçların kod değişikliği olmadan otomatik olarak ortaya çıktığı modeli.