Contracts: 41 genel arabirim (SPI)

Bir bakışta

NextPDF\Contracts, genel hizmet sağlayıcı arabirimi (SPI) yüzeyidir: src/Contracts/ altında, açık bir @stability etiketine ve geriye dönük uyumluluk taahhüdüne sahip 41 arabirim ve numaralandırma bulunur. Eklenti paketleri, çerçeve köprüleri ve Pro ile Enterprise sürümleri bu tiplere bağımlıdır; hiçbir zaman somut sınıflara bağımlı değildir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Motor iki ayrı yüzey sunar. src/Core/, src/Html/ ve src/Writer/ altındaki somut sınıflar için uyumluluk taahhüdü yoktur ve bunlar minör sürümler arasında değişebilir. Contracts ad alanı farklı çalışır. Bu ad alanı, bildirdiği kararlılık katmanı için imzaları dondurulmuş, özenle seçilmiş bir tip kümesidir. Motorun dışındaki her şey bu ad alanına bağımlıdır ve daha derindeki uygulama sınıflarına inmez. Buna Laravel, Symfony ve CodeIgniter köprüleri, compat-tcpdf uyumluluk katmanı, NextPDF Server ve Pro ile Enterprise sürümleri dahildir.

Her sözleşme PHPDoc içinde dört katmandan birini bildirir. stable bir sözleşme, minör veya yama sürümünde hiçbir kırıcı değişikliğe izin vermez. Yeni metotlar yalnızca varsayılan uygulamalarla birlikte gelir. experimental bir sözleşme, kullanımdan kaldırma bildirimiyle minör sürümde değişebilir. deprecated bir sözleşme, yerini alacak sözleşmeyi belirtir. Az sayıda tip yalnızca sözleşme olarak vardır; örneğin StreamingWriterInterface ve CursorInterface. Bu tipler yayımlanmış ve dondurulmuştur, ancak henüz herhangi bir üretim uygulamasıyla gönderilmez.

Katmanlar için yetkili liste docs/extension-points.json dosyasıdır (manifest sürümü 3.0.0, Contracts ve Event genelinde 67 yayımlanmış nokta). Makine tarafından doğrulanabilir bir test olan tests/Unit/Contracts/StabilityContractTest.php, bu manifest dosyasını okur ve beş koşul altında derlemeyi başarısız kılar. Birincisi, listelenen bir tip eksiktir. İkincisi, yansıtma ile bulunan bir tür manifest dosyasıyla uyuşmaz. Üçüncüsü, bir @stability PHPDoc etiketi manifest dosyasındaki değerden sapar. Dördüncüsü, src/Contracts/ altındaki bir sözleşme manifest dosyasında yoktur. Beşincisi, bir @internal tip sözleşme yüzeyine sızmıştır. Bu sayede sözleşme yüzeyi fark edilmeden sapamaz.

Sözleşmeler dokuz alana ayrılır ve her biri kendisine ayrılmış bir sayfada ele alınır: belge oluşturma, imzalama, barkod kodlama, tipografi, güvenlik politikası, çıkarma, gözlemlenebilirlik ve akış. Bu ayrım, motoru benimseme biçiminizi yansıtır. Taşınabilir belge biçimi (PDF) dosyaları oluştururken belge sözleşmesine bağımlı olursunuz. İmza eklerken imzalama sözleşmelerine bağımlı olursunuz. Güvenilmeyen HTML’yi kısıtlarken güvenlik politikası sözleşmelerine bağımlı olursunuz.

İsteğe bağlı uygulama çözümlemesi, motor genelinde tek bir kalıbı izler. Çekirdek, class_exists() ile somut bir sınıfı denetler ve onu sözleşmeye bağlar. LtvManagerInterface ve PdfAManagerInterface için Pro uygulamaları bu şekilde çözümlenir. Çekirdek, ticari koda katı bir bağımlılık almadan Apache-2.0 olarak kalır.

API yüzeyi

Sözleşme	Tür	Kararlılık	Beri	Alan
`PdfDocumentInterface`	interface	stable	1.0.0	document
`DocumentFactoryInterface`	interface	stable	1.7.0	document
`ResettableService`	interface	stable	1.7.0	document
`OutputDestination`	enum	stable	1.0.0	document
`Orientation`	enum	stable	1.0.0	document
`Alignment`	enum	stable	1.0.0	document
`SignerInterface`	interface	stable	1.0.0	signing
`HsmSignerInterface`	interface	stable	1.0.0	signing
`DeferredSignerInterface`	interface	experimental	3.0.0	signing
`TimestampProviderInterface`	interface	experimental	3.0.0	signing
`LtvManagerInterface`	interface	stable	1.10.0	signing
`CryptoPolicyInterface`	interface	stable	1.9.0	signing
`Barcode1DEncoderInterface`	interface	stable	1.0.0	barcode
`Barcode2DEncoderInterface`	interface	stable	1.0.0	barcode
`BarcodeEncoderInterface`	interface	stable	3.0.0	barcode
`Gs1DataParserInterface`	interface	stable	1.0.0	barcode
`FontRegistryInterface`	interface	stable	1.7.0	typography
`TextPreprocessorInterface`	interface	stable	1.9.0	typography
`HtmlSecurityPolicyInterface`	interface	stable	3.1.0	security-policy
`ExternalResourcePolicyInterface`	interface	stable	4.0.0	security-policy
`InspectorInterface`	interface	experimental	2.2.0	extraction
`EmbeddingServiceInterface`	interface	experimental	2.1.0	extraction
`VectorIndexInterface`	interface	experimental	2.1.0	extraction
`JobNotificationInterface`	interface	experimental	2.2.0	observability
`SpectrumInterface`	interface	experimental	2.1.0	observability
`StreamingWriterInterface`	interface	experimental	3.1.0	streaming
`CursorInterface`	interface	experimental	3.1.0	streaming

Tablo, birincil sözleşmeleri listeler. Değer nesnesi biçimindeki veri aktarım nesneleri (DTO’lar) (TextSegment, TextPreprocessResult), EInvoice alt ad alanı, davranış numaralandırmaları (DegradationPolicy, UnderlineStyle) ve içe aktarma sözleşmeleri (ImportedFormObjectInterface, EmbeddedPdfObjectInterface, ChromeRenderResultInterface) dahil olmak üzere geri kalan tipler, Ayrıca bakınız altındaki alan sayfalarında belgelenmiştir. Makine tarafından okunabilir tam liste docs/extension-points.json dosyasıdır; .ai/contracts-map.md dosyasına yansıtılır.

Kod örneği — hızlı başlangıç

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->save(__DIR__ . '/output/01-hello-world.pdf');

Document::createStandalone(), somut bir Document döndürür; bu nesne PdfDocumentInterface arabirimini karşılar. Motorun iç bileşenleri değiştirilebilir kalsın diye hizmetlerinizde arabirimi tip ipucu olarak kullanın.

Kod örneği — üretim

<?php

declare(strict_types=1);

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

use NextPDF\Core\DocumentFactory;
use NextPDF\Core\PdfFactory;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Typography\FontRegistry;

// Created once at process boot in a RoadRunner/Swoole/Octane worker.
$fontRegistry = new FontRegistry();
$imageRegistry = new ImageRegistry(maxCacheBytes: 50 * 1024 * 1024);
$documentFactory = new DocumentFactory($fontRegistry, $imageRegistry);

$factory = PdfFactory::new()
    ->withCompress(true)
    ->withDocumentFactory($documentFactory);

for ($request = 1; $request <= 3; $request++) {
    $doc = $factory->create();
    $doc->setTitle("Worker Request #{$request}");
    $doc->addPage();
    $doc->setFont('helvetica', 'B', 16);
    $doc->cell(0, 12, "Worker Request #{$request}", newLine: true);
    $doc->save(__DIR__ . "/output/14-worker-request-{$request}.pdf");
}

DocumentFactory, DocumentFactoryInterface arabirimini uygular. Sürecin ömrü boyunca yaşayan FontRegistryInterface ve ImageRegistryInterface tekillerini tutar ve bunları kullanılıp atılabilir her Document nesnesine enjekte eder; böylece bir işçi, binlerce istek boyunca her yazı tipini yalnızca bir kez ayrıştırır.

Sınır durumları ve püf noktaları

Yalnızca sözleşme olan bir tip derlenir, ancak çalışma zamanı desteği yoktur. new anahtar sözcüğüyle StreamingWriterInterface veya CursorInterface üzerinden bir nesne oluşturma girişimi başarılı olamaz, çünkü bunları henüz hiçbir sınıf uygulamaz. Bunları ileriye dönük olarak duyurulmuş bir uygulama programlama arabirimi (API) gibi değerlendirin.
Tek bir tip için @stability PHPDoc etiketi doğruluk kaynağıdır. docs/extension-points.json, küme için doğruluk kaynağıdır. Uyuşmadıklarında StabilityContractTest başarısız olur. Bir tarafı düzenleyerek uyuşmazlığı gizlemeyin.
experimental, pratikte kararsız olduğu anlamına gelmez. Uyumluluk taahhüdünün daha zayıf olduğu anlamına gelir. Bir sözleşmeye bağımlılığı sabitlemeden önce, her sözleşmenin bc_promise alanını .ai/contracts-map.md içinde okuyun.
Bir @internal sınıfı, diğer paketler teknik olarak ona başvurabilse bile asla bir sözleşme değildir. Kararlılık testi, manifest dosyasında görünen herhangi bir @internal tipi reddeder.
Bir stable arabirime metot eklemek, metot varsayılan bir uygulamayla gönderilmediği sürece uygulayıcılar için kırıcı bir değişikliktir. Motor, mevcut arabirimleri genişleterek değil, yeni arabirimler aracılığıyla yetenek ekler.

Performans

Doğrudan Contracts üzerinden programlama yapmak, ölçülebilir bir çalışma zamanı maliyeti eklemez: bir arabirim tip ipucu, çağrı başına değil, bağlama zamanında çözümlenir. Bu sayfanın işçi örneği için performance_budget değeri, üç belge genelinde 1500 ms duvar saati süresi ve 64 MB tepe bellek değeridir. İlk istekteki yazı tipi ayrıştırması bu bütçedeki baskın maliyettir. Sonraki istekler kayıt defteri önbelleğini yeniden kullanır ve sözleşmeye atfedilebilir iş yükü tek haneli milisaniyelere düşer. Maliyet modeli, sözleşme gönderimi başına O(1)‘dir; iş, her alan sayfasında belgelenen somut uygulamadadır.

Güvenlik notları

SPI aynı zamanda bir güvenlik sınırıdır. HtmlSecurityPolicyInterface ve ExternalResourcePolicyInterface, güvenilmeyen HTML’nin bir işleyiciye ulaşmadan önce neler yapabileceğini kısıtlayan, varsayılanı reddet olan sözleşmelerdir. CryptoPolicyInterface, imzalama ve şifreleme için algoritma ve anahtar gücü seçimini denetler. Bunlar sözleşme olduğundan, motoru çatallamadan daha katı bir politika sağlayabilirsiniz. Güvenlikle ilgili herhangi bir politika için stable katmanına sabitleyin. Deneysel politika sözleşmeleri, minör sürümler arasında biçim değiştirebilir. İmzalama ve güvenlik politikası alan sayfaları, tam tehdit modelini ve normatif kaynakları içerir.

Uygunluk

Bu genel bakış doğrudan normatif bir iddia ortaya koymaz; her alan sayfası kendi citations bloğunu işler. İmzalama sözleşmeleri ISO 32000-2 §12.8 (dijital imzalar) ve ETSI EN 319 142 (PAdES taban çizgileri) ile eşlenir. PDF/A yöneticisi ISO 19005-4 ile eşlenir. Madde düzeyinde uygunluk tabloları için imzalama, güvenlik politikası ve çıkarma sayfalarına bakın.

Ticari bağlam

Pro ve Enterprise sürümleri, çeşitli çekirdek sözleşmelerinin arkasındaki üretim kodunu sağlar: LtvManagerInterface (uzun vadeli doğrulama), PdfAManagerInterface (PDF/A zorunlu kılma), donanım güvenlik modülü (HSM) ve ertelenmiş imzalayıcılar, barkod kodlayıcılar ile gömme ve vektör dizini sözleşmeleri. Çekirdek, arabirimleri yayımlar ve dondurur; Premium paketi uygulamaları sunar. Bu, açık kaynaklı motorun Apache-2.0 olarak kalmasını sağlar ve ticari dağıtımlar için API değişikliği gerektirmeyen, yerine takılabilir bir yükseltme sunar.

Ayrıca bakınız

Contracts / Document — PDF belgesi, fabrika ve kayıt defteri sözleşmeleri.
Contracts / Signing — imzalayıcı, HSM, zaman damgası ve uzun vadeli doğrulama (LTV) sözleşmeleri.
Contracts / Security Policy — kripto, HTML ve kaynak politikası sözleşmeleri.
Contracts / Typography — yazı tipi kayıt defteri ve metin ön işleme sözleşmeleri.
Contracts / Extraction — denetleyici, PDF/A, gömme ve e-fatura sözleşmeleri.
Core — bu sözleşmeleri karşılayan somut sınıflar.
Event — Contracts ile birlikte yayımlanan olay SPI karşılığı.