Contracts / Document

Bir bakışta

Belge alanı, Portable Document Format (PDF) çıktısı oluşturmak için kullandığınız sözleşmeleri barındırır: içerik için PdfDocumentInterface, çalışan ortamlarında güvenli oluşturma için DocumentFactoryInterface, yazı tipi ve görüntü kayıt defteri sözleşmeleri ve teslimat ile yerleşimle ilgili üç enum’u. Tümü 1.0.0 veya 1.7.0 sürümünden bu yana stable durumundadır.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

PdfDocumentInterface, birincil uygulama programlama arayüzü (API) yüzeyidir. Sayfa yönetimini, yazı tipi seçimini, hücre ve çok hücreli metin yerleşimini, Hypertext Markup Language (HTML) işlemeyi, görüntü gömmeyi ve nihai çıktıyı tanımlar. Her yöntem static döndürür; böylece çağrıları zincirleyebilirsiniz. Document::createStandalone(), arayüzü karşılayan somut bir örnek döndürür. Motorun iç yapısı değiştirilebilir kalsın diye kendi hizmetlerinizde arayüzü tip ipucu olarak kullanın.

Belge oluşturmanın iki yolu vardır. Klasik bir PHP FastCGI Process Manager (PHP-FPM) isteğinde, createStandalone() özel kayıt defterlerine sahip kendi kendine yeten bir belge oluşturur. RoadRunner, Swoole ve Laravel Octane dahil uzun süre yaşayan çalışanlar diğer yolu kullanır. Bu modelde DocumentFactoryInterface::create(), yeni ve tek kullanımlık bir Document döndürür. Belge, süreç ömrü boyunca yaşayan kayıt defterlerinden okur ancak onları asla değiştirmez. Fabrika, FontRegistryInterface ve ImageRegistryInterface tekil örneklerini barındırır. Her belge kendi işleme bağlamını ve yazıcısını alır. Bu model hataları sınırlar: bir belge, başka bir belgenin bağımlı olduğu paylaşılan durumu bozamaz.

Kayıt defteri sözleşmeleri, çalışanların hızlı kalmasını sağlar. FontRegistryInterface, bir yazı tipi dosyasını bir kez ayrıştırır ve ayrıştırılan meta verileri sürecin ömrü boyunca önbelleğe alır. Üretim trafiğinin kayıt defterini değiştirememesi için ısınmadan sonra kilitleyebilirsiniz. ImageRegistryInterface, kodu çözülmüş görüntü ikili verilerini sınırlı bir en uzun süredir kullanılmayanı atma (LRU) politikasıyla önbelleğe alır. İkili veriler atıldıktan sonra bile görüntü meta verileri bellekte kalır. Her iki kayıt defteri de kapasite planlaması için memoryUsage() sunar. ImageRegistryInterface, yapısal meta verileri yok etmeden önbelleğe alınmış verileri atan ResettableService arayüzünü genişletir. Bir çalışan, bellek baskısı altındayken görüntü önbelleklerini atabilir ve hizmet vermeye devam edebilir.

Alanı üç enum tamamlar. OutputDestination, satır içi görüntüleme, zorunlu indirme, dosya sistemine yazma veya ham dize döndürme seçeneklerinden birini seçer. Orientation, dikey veya yatay yönü seçer. Alignment, sola hizalı, ortalı, sağa hizalı veya iki yana yaslı metni seçer. Her enum, enum değeri olarak eski TCPDF kodunu kullanır; böylece compat-tcpdf köprüsü sorunsuz şekilde eşlenir. Bu enum’lar için geriye dönük uyumluluk taahhüdü eklemeye dayalıdır. Hiçbir durum kaldırılmaz. Yeni durumlar bir ara sürümde gelebilir.

API yüzeyi

Tür	Tip	Anahtar üyeler	Kararlılık	Şu sürümden beri
`PdfDocumentInterface`	interface	`addPage()`, `setMargins()`, `setFont()`, `cell()`, `multiCell()`, `writeHtml()`, `image()`, `output()`, `save()`	stable	1.0.0
`DocumentFactoryInterface`	interface	`create(?Config): Document`	stable	1.7.0
`ResettableService`	interface	`reset(): void`	stable	1.7.0
`FontRegistryInterface`	interface	`register()`, `get()`, `warmup()`, `lock()`, `isLocked()`, `registerFromBinary()`, `memoryUsage()`	stable	1.7.0
`ImageRegistryInterface`	interface	`load()`, `loadFromString()`, `getMetadata()`, `memoryUsage()` (`ResettableService` arayüzünü genişletir)	stable	2.0.0
`OutputDestination`	enum (string)	`Inline`, `Download`, `File`, `String`	stable	1.0.0
`Orientation`	enum (string)	`Portrait`, `Landscape`	stable	1.0.0
`Alignment`	enum (string)	`Left`, `Center`, `Right`, `Justify`	stable	1.0.0

Tipografi sayfası, FontRegistryInterface ve ImageRegistryInterface arayüzlerini ayrıntılı olarak belgeler. Bu sayfa, bunların oluşturma yaşam döngüsündeki rolünü ele alı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->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'This is a minimal PDF generated with NextPDF.', newLine: true);
$doc->save(__DIR__ . '/output/01-hello-world.pdf');

Kod örneği — üretim

<?php

declare(strict_types=1);

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

use NextPDF\Core\PdfFactory;
use NextPDF\ValueObjects\{Margin, PageSize};

$factory = PdfFactory::new()
    ->withPageSize(PageSize::A4())
    ->withMargins(new Margin(15.0, 15.0, 15.0, 15.0))
    ->withCompress(true)
    ->withLang('en');

// The same configured factory creates independent documents.
$doc = $factory->create();
$doc->setTitle('PdfFactory Example');
$doc->setAuthor('NextPDF');
$doc->addPage();
$doc->setFont('helvetica', '', 16);
$doc->cell(0, 12, 'Created via PdfFactory', newLine: true);

$doc2 = $factory->create();
$doc2->addPage();
$doc2->setFont('helvetica', '', 12);
$doc2->cell(0, 10, 'Second document from the same factory.');

$doc->save(__DIR__ . '/output/02-pdf-factory.pdf');

PdfFactory, değişmez bir oluşturucudur. Her with*() çağrısı yeni bir örnek döndürür. Arka planda bir DocumentFactoryInterface oluşturur; böylece genel bakıştaki çalışan kayıt defteri modeli ek bağlama gerektirmeden geçerli olur.

Uç durumlar ve dikkat edilmesi gerekenler

createStandalone(), özel kayıt defterleri oluşturur. Bir çalışan döngüsünde bu, her istekte her yazı tipinin yeniden ayrıştırılması anlamına gelir. Bunun yerine paylaşılan kayıt defterleriyle DocumentFactoryInterface kullanın.
Bir Document, tasarım gereği tek kullanımlıktır. Bir örneği mantıksal belgeler arasında yeniden kullanmak durum sızıntısına yol açar. Her belge için create() çağırın ve çöp toplayıcının onu geri kazanmasına izin verin.
FontRegistryInterface::lock(), register(), addFontDirectory() ve warmup() yöntemlerinin LogicException fırlatmasına neden olur. Isınma tamamlandıktan sonra kilitleyin; istek işleme sırasında asla değil.
OutputDestination::File, sunucu dosya sistemine yazar ve ham baytları döndürür. save(), açık dosya yolu API’sidir. Aynı belge için ikisini bir arada kullanmayın.
cell(), TCPDF uyumluluğu için kenarlık bağımsız değişkeni olarak bool|string kabul eder. Boş dize, false ile aynı şey değildir. Kastettiğiniz tipte bir değer geçirin.

Performans

Yazı tipi ve görüntü kayıt defterleri, belge alanını istek başına yapılan işten çok bellekle sınırlanan bir sisteme dönüştürür. İlk istekteki yazı tipi ayrıştırması baskındır. performance_budget, çalışan örneğindeki üç belge boyunca 1500 ms duvar saati süresi ve 64 MB tepe bellek kullanımıdır. Bu bütçenin neredeyse tamamını ilk yazı tipi ayrıştırması kullanır. Isınma tamamlandıktan sonra, belge başına sözleşmelere atfedilebilir iş O(1)‘dir: bir kayıt defteri araması ve bir bağlam ayırma. Her iki kayıt defterinden birinde memoryUsage(), canlı kapasite planlaması için bir MemoryReport döndürür. ResettableService::reset(), sürekli yük altında tepe bellek kullanımını sınırlar.

Güvenlik notları

Belge sözleşmeleri herhangi bir kriptografik yüzey sunmaz, ancak iki operasyonel risk geçerlidir. İlk olarak image(), bir yol veya Uniform Resource Locator (URL) kabul eder. Güvenilmeyen girdi senaryolarında, kullanıcı denetimindeki URL’leri doğrudan geçirmek yerine uzaktan getirmeyi ExternalResourcePolicyInterface aracılığıyla sınırlayın (güvenlik ilkesi sayfasına bakın). İkinci olarak writeHtml(), HTML işlem hattının giriş noktasıdır. Güvenilmeyen biçimlendirme, işlenmeden önce bir HtmlSecurityPolicyInterface denetiminden geçmelidir. Belge katmanının kendisi temizleme yapmaz. Bu görev güvenlik ilkesi alanına aittir ve bu bir sözleşme olduğu için, çatallama yapmadan daha katı bir ilke sağlayabilirsiniz.

Uyumluluk

Belge sözleşmeleri, ISO 32000-2’de tanımlandığı biçimiyle PDF 2.0 belge yapısını uygular. Çıktı, sayfa ve yazı tipi işleme, ISO 32000-2 §7 uyarınca dolaylı nesneler ve bir çapraz başvuru akışı üretir. Yazıcı katmanı, motor katmanı sözleşmesi ve mimari karar kaydı (ADR-010) uyarınca içerik üretir. Bu sayfa, yapısal uyumluluğun ötesinde madde düzeyinde bir iddiada bulunmaz. Ayıklama ve erişilebilirlik sayfaları, PDF/A ve PDF/UA uyumluluğunu belgeler ve normatif tablolar içerir.

Ayrıca bakın

Contracts: 41 public interfaces (SPI) — service provider interface (SPI) genel bakışı ve kararlılık katmanları.
Contracts / Typography — FontRegistryInterface için eksiksiz belgeler.
Contracts / Security Policy — writeHtml() ve image() yöntemlerini denetleyen ilkeler.
Core — Document ve PdfFactory somut sınıfları.
Document — belge oluşturma modülü.
Writer — bu sözleşmeler için PDF nesneleri üreten katman.