PDF motorunuzun neden bir yan birime değil, PHP'ye ait olduğu

Spec: ISO/IEC 25010:2023, §3.7Spec: ISO 32000-2, §7

Bir bakışta

Bir PDF’in yapılabileceği iki yer vardır: PHP sürecinizin içinde ya da işletmeniz gereken başka bir yerde. NextPDF onu içeride yapar. Bu sayfa, o tercihin gerekçesidir — süreç içi bir motorun neden genellikle doğru varsayılan olduğu ve “başka bir yer” deseninin üretime girdiğinde gerçekte neye mal olduğu.

Bu, çerçeve açısı değil, mimari açıdır. Aynı motorun Laravel, Symfony, CodeIgniter ve bağımsız koda nasıl ulaştığı farklı bir hikâyedir ve tek motor, her çerçeve bölümünde anlatılır.

Bunun neden önemli olduğu

Bir PDF özelliği nadiren işlettiğiniz bir sistem olarak başlar. Bir denetleyicide bir satır olarak başlar: şu faturayı işle, şu raporu döndür. Yan birim deseni, o satırı altyapıya dönüştürür. Belgeyi çizmek için artık ikinci bir şey çalıştırırsınız — harici bir ikili, başsız bir tarayıcı, ayrı bir mikrohizmet — ve o ikinci şeyin ihtiyaç duyduğu her şey de sizin sorununuz olur: sürümü, belleği, kapsayıcısı, ağı, başarısızlık biçimleri, sabah 2’deki nöbet çağrısı.

Maliyet, demoda görünmez ve üretimde kaçınılmazdır. Sürecinizde yaşayan bir belge motorunda bunların hiçbiri yoktur. Soru “bir yan birim bir PDF yapabilir mi” değildir — elbette yapabilir. Soru “oraya varmak için neyi işletmeyi üstlendiniz ve buna ihtiyacınız var mıydı” sorusudur.

Kısa özet

Süreç içi, ikinci bir çalışma zamanı olmaması demektir. NextPDF, PDF’i isteği işleyen aynı PHP işçisinin içinde çizer. Üretilecek bir alt süreç, dağıtılacak bir hizmet ve ayakta tutulacak fazladan hiçbir şey yoktur.
Bir yan birim, sahip olmadığınız bir işletimsel yüzey ekler. Pakete dahil bir tarayıcı ya da harici bir ikili, kendi sürümünü, kendi güvenlik ayak izini ve kendi kapsayıcısını getirir — bunların tümünü artık siz yamalar ve izlersiniz.
İşlerin ters gittiği yer süreç sınırlarıdır. Soğuk başlangıçlar, zaman aşımları, kırılgan süreçler arası tesisat ve verinin sürecinizi terk etmesi, süreç içi bir çağrının yalnızca sahip olmadığı başarısızlık biçimleridir.
Süreç içi, test edilebilir ve belirlenimcidir. Motor, birim testi yapabileceğiniz, sahteleyebileceğiniz ve hakkında akıl yürütebileceğiniz türlenmiş PHP’dir — yalnızca çalıştırıp çıktıya bakarak yoklayabileceğiniz opak bir işleyici değil.
Gerçek bir tarayıcının hâlâ gerçek kullanımları vardır. Keyfi modern web sayfalarının piksel düzeyinde sadık işlenmesi için başsız bir tarayıcı dürüst araçtır — ve NextPDF buna bilerek devredebilir. Bu, bir dikiş yeridir, varsayılan değil.

NextPDF buna nasıl yaklaşır

İki mimariyi yan yana tutun. Süreç içi yol bir işlev çağrısıdır. Yan birim yolu, küçük ölçekte dağıtık bir sistemdir — ve kutuları arasındaki her ok, kodunuzdan bağımsız olarak başarısız olan bir yerdir.

In-process: call the enginewriteHtml() or the document API runs inside the current PHP worker — no subprocess, no socket.
In-process: receive PDF bytesThe engine returns native PDF content directly; nothing left the process.
Sidecar: serialize and shipMarkup or a request is marshalled out of your process to a binary, browser, or remote service.
Sidecar: cross the boundaryA process spawn or network hop — with a cold start, a timeout, and an IPC contract that can break.
Sidecar: run a second runtimeAn external renderer with its own version, memory profile, and security surface to operate and patch.
Sidecar: deserialize backMarshal the result back in and translate the renderer’s errors into yours.

Süreç içi yola karşı yan birim yolu. Süreç içinde PDF, aynı PHP işçisinin içinde türlenmiş bir çağrıyla üretilir ve doğrudan döndürülür. Yan birim yolu ise bir serileştirme adımı, bir süreç veya ağ sınırı, kendi sürümü ve ayak izine sahip harici bir çalışma zamanı ve geri bir seriden çıkarma adımı ekler — her biri, süreç içi çağrının sahip olmadığı ayrı bir başarısızlık biçimi.

İşletilecek ikinci bir çalışma zamanı yoktur. Yan birim deseni, tek bir özelliğin kostümünü giymiş iki sistemdir. Pakete dahil bir wkhtmltopdf, başsız bir Chromium hizmeti, ayrı bir işleme mikrohizmeti — her biri kendi sürüm temposu ve kendi hatalarıyla bir çalışma zamanıdır. Hepsini devralırsınız. Süreç içi motor bir Composer bağımlılığı olarak gelir; composer.json dosyanızdaki her kütüphane gibi yükseltilir, dağıtımınıza eklenen hiçbir artalan işlemi, görüntü ya da yuva olmadan.

Sürüm kayması ve daha geniş bir güvenlik yüzeyi. Pakete dahil bir tarayıcı, istikrarlı bir güvenlik uyarı akışına sahip büyük, hızlı hareket eden bir kod tabanıdır. Sabitlerseniz çürür; izlerseniz çalkalanır. Her iki durumda da, tek bir belgeyi beslemek için tedarik zincirinizde oturan, bir işleyicinin tüm web platformudur. Süreç içi bir PHP motoru ise okuyabileceğiniz odaklanmış bir kod kütüphanesidir; güvenlik yüzeyi, ayrıca işlettiğiniz ikinci bir platform değil, zaten çalıştırdığınız PHP’dir.

Veri, süreç sınırınızın içinde kalır. Dışarıya devrettiğinizde, belge içeriği — ki bu çoğu zaman tam olarak bir PDF’in taşımak için var olduğu hassas veridir — bir sınırı geçer. Bir borua, bir argümana, bir geçici dosyaya ya da bir hizmete giden bir ağ yuvasına yazılır. Bunların her biri sızdırılacak, kazara günlüğe yazılacak ya da geride bırakılacak bir yerdir. Süreç içinde veri, onu sahiplenen işçiyi asla terk etmez. Patlama yarıçapı bir filo değil, tek bir süreçtir.

Kırılgan tesisat, soğuk başlangıçlar ve zaman aşımları. Süreçler arası ve ağ çağrıları, bir işlev çağrısının yapamayacağı biçimlerde başarısız olur: başlamayan alt süreç, asılı kalan yuva, yanlış tahmin ettiğiniz zaman aşımı, bir trafik sıçraması altındaki soğuk başlangıç. Her biri bir yeniden deneme politikası, bir devre kesici ve bir bütçe gerektirir. Süreç içi bir işleme ya bayt döndürür ya da bir sonraki satırda yakaladığınız türlenmiş bir istisna fırlatır. Uzlaştırılacak kısmi bir ağ durumu yoktur.

Gözlemlenebilirlik ve test, sınırın ötesinde zorlaşır. Bir yan birimdeki bir başarısızlık, bir çıkış kodu, kesik bir günlük satırı ya da denetlemediğiniz bir hizmetten gelen bir 500 olarak gelir. Onu yeniden üretmek, o ortamın tamamını yeniden üretmek demektir. Süreç içi bir motor, zaten kullandığınız araçlarla gözlemlenebilirdir — bir yığın izi, bir hata ayıklayıcı, bir profilleyici — ve PHP’nizin geri kalanı gibi test edilebilir. O test edilebilirlik, adı konmuş bir yazılım kalitesi özelliğidir: ISO/IEC 25010 onu sürdürülebilirlik altına yerleştirir (Spec: ISO/IEC 25010:2023, §3.7) ve süreç içi bir kütüphane, yalnızca başlatarak çalıştırabileceğiniz bir işleyiciye göre onu çok daha doğrudan karşılar.

O testlerin üzerinde doğrulama yaptığı PDF, bir kara kutu değil, tanımlı bir yapıdır. Bir PDF dosyasının belirtilmiş bir nesne ve dosya düzeni vardır (Spec: ISO 32000-2, §7) ve süreç içi bir motor, o yapıyı okuyabileceğiniz koddan yayar — böylece bir altın dosya ya da yapısal test, yalnızca gözlemleyebileceğiniz harici bir programın çıktısını değil, bilinen bir işlevin ürettiği baytları denetler.

Pratik örnek

Bütün mesele birkaç satıra sığar. Ne bir istemci, ne bir taban URL, ne bir sağlık denetimi, ne de bir yeniden deneme politikası vardır — çünkü ikinci bir sistem yoktur.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// The engine runs inside this very process. No subprocess is spawned,
// no socket is opened, and the report data never leaves the worker.
$document = Document::createStandalone();
$document->setTitle('Quarterly Report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Quarterly Report</h1>
<p>Rendered <strong>in-process</strong> by PHP — no browser, no sidecar.</p>
HTML;

$document->writeHtml($html);

// PDF bytes are returned directly. There is no boundary to marshal across,
// so there is no timeout, cold start, or deserialization step to handle.
$bytes = $document->getPdfData();

Yan birim sürümünün biçimini karşılaştırın — kodunu değil, işletimsel biçimini. Kurulu ve erişilebilir bir ikili ya da hizmet, serileştirilip gönderilen bir istek, seçilen bir zaman aşımı, işleyici soğuk ya da çökmüş olduğunda bir başarısızlık yolu ve geri seriden çıkarılan bir sonuç gerektirir. Bunların hiçbiri yukarıdaki parçada yoktur; çünkü motor bir kütüphane olduğunda hiçbiri var olmaz.

Yaygın yanlış anlama

Sık karşılaşılan varsayım, “gerçek” PDF işlemenin bir tarayıcı anlamına gelmesi gerektiğidir; dolayısıyla süreç içi, oyuncak sürüm olmalıdır. Bu, ödünleşimi tersine alır. Bir tarayıcı, keyfi modern web içeriğinin tam, piksel düzeyinde sadık işlenmesine ihtiyaç duyduğunuzda doğru araçtır. Çoğu ekibin gerçekte yaptığı belge biçimindeki iş için ise yanlış varsayılandır — faturalar, raporlar, ekstreler, sözleşmeler — düzenin bilindiği, verinin sizin olduğu ve doğruluğun gözle değil bir doğrulayıcıyla denetlendiği yerde. Bu iş için, bir yan birimin işletimsel ağırlığı, süreç içi motorun zaten vermediği hiçbir şeyi size kazandırmaz ve yukarıdaki bölümlerdeki her şeye mal olur.

Ayna yanlış anlama, bu sayfanın işlemekten özenle kaçındığıdır: süreç içi bir motorun bir tarayıcı gibi “tüm web’i” işlediğini iddia etmek. İşlemez ve NextPDF işlediğini ileri sürmez. Süreç içi HTML işlem hattı, belge yerleşimine odaklanan, belgelenmiş sınırlara sahip, belirtime uyumlu bir alt kümedir — dürüst kapsam, HTML işlem hattı bölümünde ortaya konur. Tam tarayıcı doğruluğuna gerçekten ihtiyaç duyduğunuzda, bu, sessiz bir geri dönüş değil, kasıtlı, isteğe bağlı bir devretmedir.

Sınırlar ve kapsam

Süreç içi, doğru varsayılandır. Bir alt sürecin asla gerekçeli olmadığına dair evrensel bir iddia değildir. Bir belgenin, süreç içi motorun kapsamadığı keyfi modern CSS’in tam işlenmesini gerçekten gerektirdiği yerde, başsız bir tarayıcıya devretmek doğru tercihtir — ve NextPDF bu yolu, ağ erişimi kısıtlanmış olarak, varsayılan değil bir dikiş yeri olarak, bilerek destekler. İkisi rakip değildir; farklı işler için farklı araçlardır.

Bu sayfa, bir CSS destek matrisini değil, mimariyi tartışır. Süreç içi işlem hattının tam olarak hangi HTML ve CSS’i kapsadığı, motorun kodu ve uygunluk testleriyle tanımlanır ve o işlem hattıyla birlikte belgelenir — burada vaat edilmez. “Süreç içi”, varsayılan işleme yolunu tanımlar; her olası yolun bir alt süreçten kaçındığı iddiası değildir.

Yetenek yüzeyi basit kalır: süreç içi motor Core’dur ve tarayıcı devretme yolu, sürümden bağımsız, isteğe bağlı bir uzantıdır.

Where the PDF is rendered — edition availability
Edition	Availability
Core	Core, PDF’i PHP’de süreç içinde işler — varsayılan olarak alt süreç, ikili ya da yan birim yoktur.
Pro	Başsız tarayıcı devretme yolu, sürüm katmanından bağımsız, isteğe bağlı bir eklenti uzantısıdır.
Enterprise	Başsız tarayıcı devretme yolu, sürüm katmanından bağımsız, isteğe bağlı bir eklenti uzantısıdır.

İlgili belgeler

HTML işlem hattı — süreç içi motorun dürüst kapsamı ve bir tarayıcıya devretmenin tam olarak ne zaman doğru olduğu.
Tek motor, her çerçeve — tamamlayıcı eksen: aynı süreç içi motorun, yığın başına farklı bir kütüphane olmadan her PHP çerçevesine nasıl ulaştığı.
NextPDF’i üretimde işletmek — süreç içi bir motoru çalıştırmanın günlük olarak nasıl göründüğü, işletilecek fazladan bir çalışma zamanı olmadan.
Bellek ve akış — motorun süreç içi üretimi yük altında nasıl sınırlı tuttuğu.

Sözlük

Süreç içi üretim — PDF’i, isteği işleyen aynı PHP işçisinin içinde, alt süreç, yuva ya da harici hizmet olmadan üretmek.
Yan birim — uygulamanızın yanında tek bir işi yapmak için çalışan ayrı bir çalışma zamanı; burada, PDF’i sürecinizin dışında işleyen harici bir ikili, başsız tarayıcı ya da mikrohizmet.
Soğuk başlangıç — bir alt süreç ya da hizmetin ilk isteği sunabilmesi için sıfırdan başlatılması gerektiğinde oluşan gecikme ve kaynak sıçraması.
IPC — süreçler arası iletişim: ayrı bir sürece veri geçirmek için kullanılan borular, yuvalar, geçici dosyalar ya da ağ çağrıları ve kırılgan, hata ayıklanması zor başarısızlıkların yinelenen bir kaynağı.
Tarayıcı devretme dikiş yeri — tam doğruluk için bir işlemi, alt kaynak ağ erişimi engellenmiş başsız bir tarayıcıya teslim eden, isteğe bağlı, devreye alınabilir yol; varsayılan değil, kasıtlı bir tercih.