Destek: paylaşılan yardımcılar + Clock + Sleeper

Genel bakış

Support modülü, motorun dahili olarak kullandığı paylaşılan yardımcı araçları içerir. Bunun yanında küçük bir genel yüzey sunar: PHP Standards Recommendation 20 (PSR-20) sistem saati, uyarı toplama hattı ve Portable Document Format (PDF) serileştirme temel öğeleri. Ad alanının büyük bölümü dahili altyapıdır. Bu sayfa, bağımlı olabileceğiniz bölümleri belgeler ve yalnızca dahili olan bölümleri işaretler.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Saat (PSR-20). SystemClock, Psr\Clock\ClockInterface arabirimini uygular. Bu sınıfın now() yöntemi, geçerli zamanı bir DateTimeImmutable olarak döndürür. PSR-20 modeli, tek bir okuma işlemi olan ve geçerli zamanı değişmez bir tarih-saat değeri olarak döndüren bir saat arabirimi tanımlar (PSR-20 psr_20_clock#2.1). SystemClock varsayılan uygulamadır; bir saat enjekte etmediğinizde motor bunu kullanır. Testlerde zamanı sabitlemek için aynı arabirimi uygulayan dondurulmuş bir saat enjekte edin. Bayt düzeyinde aynı çıktıya ihtiyaç duyduğunuzda saati Config::deterministic ile eşleştirin.

Uyarı hattı. WarningCollector, ölümcül olmayan işleme sorunları için birincil bellek içi taşıyıcıdır. Motor, sıkıştırılmış bir tablo sütunu, çözümlenmemiş bir yazı tipi veya eksik bir glif gibi belirlenimci her bozulma için bir Warning ekler. Oluşturma tamamlandıktan sonra uyarıları Document::getWarnings() üzerinden okursunuz. Bir Warning, değişmez bir değer nesnesidir. Şunları içerir: bir WarningCode, bir WarningSeverity (warning veya degraded), sayfa, öğe türü, özellik kimliği, bir bozulmuş-eşitlik bayrağı, bir ileti, bir DegradationImpact ve isteğe bağlı bir yetenek kimliği. WarningCode, kararlı tanımlayıcılardan oluşan dize tabanlı bir numaralandırmadır. Tanımlayıcılar NEXTPDF_W_ önekiyle başlar, örneğin NEXTPDF_W_FONT_UNRESOLVED; böylece bunlarla testlerde güvenle eşleştirme yapabilirsiniz. addWithPolicy(), etkin DegradationPolicy’yi uygular. Katı ilkede, uyumlulukla ilgili, anlamsal veya engelleyici bir etki DegradedException fırlatır. Dengeli ilkede yalnızca engelleyici bir etki durumunda fırlatır. İzin verici ilke hiçbir zaman fırlatmaz.

PDF temel öğeleri. PdfStringEscaper, PDF dizesi ve ad kaçışı için tek doğru kaynaktır. escapeLiteral(), bir PDF düz dizesinde gereken karakterleri kaçırır: ters bölü (reverse solidus), parantezler, satır başı (CR), satır besleme (LF), yatay sekme (HT), geri al (BS) ve sayfa beslemesi (FF). Ayrıca NUL baytını da çıkarır. escapeName(), yazdırılabilir American Standard Code for Information Interchange (ASCII) aralığının dışındaki baytları ve bir ad nesnesi için PDF sınırlayıcı kümesindeki baytları onaltılık olarak kodlar. BinaryBuffer, PDF nesnelerini ve akışlarını yazmak için iyileştirilmiş ikili bir biriktiricidir. Akış kipinde, büyük belgelerde bir php://temp tutamacına taşar. Ayrıca imza gömme işleminin gerektirdiği bayt aralığı işlemlerini de destekler. PdfOperators, yollar, metin, grafik durumu ve yazı tipleri için içerik akışı işleci biçim dizelerini tutar. Çizim ve ayrıştırıcı katmanları bu dizeleri paylaşır.

BinaryBuffer, PdfOperators ve NextPDF\Support\ ad alanının geri kalanının büyük bölümü dahili altyapıdır. Yazıcı ve çizim katmanları bunları kullanır. Bu sayfa, bütünlük ve denetim amacıyla bunları belgeler. Bunlar, desteklenen genel uygulama programlama arabirimi (API) kapsamında değildir. Bunun yerine Document cephesine ve Contracts ad alanına bağımlı olun. SystemClock, WarningCollector, Warning, WarningCode, WarningSeverity ve DegradationImpact genel kullanıma açık üyelerdir.

API yüzeyi

Sembol	Tür	Görünürlük	Önemli üyeler
NextPDF\Support\SystemClock	final class	public	now(): DateTimeImmutable (PSR-20 ClockInterface)
NextPDF\Support\WarningCollector	final class	public	add(), emit(), addWithPolicy(), getWarnings(), hasWarnings(), hasDegradedParity(), clear()
NextPDF\Support\Warning	final readonly class	public	$code, $severity, $page, $elementType, $featureId, $degradedParity, $message, $impact, $capabilityId
NextPDF\Support\WarningCode	string enum	public	kararlı NEXTPDF_W_* tanımlayıcıları
NextPDF\Support\WarningSeverity	string enum	public	Warning, Degraded
NextPDF\Support\DegradationImpact	string enum	public	Cosmetic, LayoutRisk, SemanticLoss, ComplianceRisk, Blocking
NextPDF\Support\PdfStringEscaper	final readonly class	internal	escapeLiteral(), escapeName() (statik)
NextPDF\Support\BinaryBuffer	final class	internal	write(), writeStream(), replaceAt(), extract(), enableStreaming(), getContents()
NextPDF\Support\PdfOperators	final class	internal	içerik akışı işleci biçim dizesi sabitleri

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

Oluşturmanın ardından toplanan uyarıları okuyun.

<?php

declare(strict_types=1);

use NextPDF\Support\WarningCollector;

$collector = new WarningCollector();

// The engine appends warnings during rendering. After generation:
if ($collector->hasWarnings()) {
    foreach ($collector->getWarnings() as $warning) {
        \printf(
            "[%s] page %d: %s\n",
            $warning->code->value,
            $warning->page,
            $warning->message,
        );
    }
}

Kod örneği — üretim

Zamanı belirlenimci hale getirmek için bir saat enjekte edin ve bozulmuş-eşitlik uyarısını bir derleme başarısızlığı olarak değerlendirin.

<?php

declare(strict_types=1);

use NextPDF\Support\SystemClock;
use NextPDF\Support\WarningCollector;
use Psr\Clock\ClockInterface;

// Production uses the real system clock.
$clock = new SystemClock();
$now = $clock->now();          // DateTimeImmutable
$epoch = $now->getTimestamp(); // int

// In tests, swap in any ClockInterface that returns a fixed instant
// (the parameter is typed to the PSR-20 interface, not SystemClock).
function buildReport(ClockInterface $clock): \DateTimeImmutable
{
    return $clock->now();
}

$collector = new WarningCollector();
// ... run generation ...
if ($collector->hasDegradedParity()) {
    throw new \RuntimeException('Output parity degraded; failing the build.');
}

Sınır durumlar ve dikkat edilecekler

• SystemClock::now(), her çağrıda yeni bir DateTimeImmutable döndürür. İki çağrının aynı anı döndüreceğini varsaymayın. Sabit zaman için dondurulmuş bir saat enjekte edin.
• WarningCollector, bellek içidir ve her örneğe özeldir. Birincil uyarı kanalıdır. JavaScript Object Notation (JSON) yan dosyası ile komut satırı arabirimi (CLI) standart hata (STDERR) çıktısı, toplayıcının kendisi tarafından değil, çıktı sınırında yayımlanır.
• addWithPolicy(), katı bir ilke altında işleme sırasında DegradedException fırlatabilir. Kısmi çıktıya ihtiyaç duyuyorsanız bunu oluşturma sınırında yakalayın.
• WarningCode değerleri kararlı dizelerdir. İnsan tarafından okunabilen ve değişebilen ileti metniyle değil, numaralandırma durumuyla eşleştirin.
• BinaryBuffer::getLength(), akış arabirimi eşitliği için getOffset() yönteminin kasıtlı bir takma adıdır. Her ikisi de aynı bayt sayısını döndürür.
• Şunları dahili altyapı olarak değerlendirin: PdfStringEscaper, BinaryBuffer ve PdfOperators. Bunlar, genel API kararlılık taahhüdü kapsamında değildir.

Başarım

SystemClock::now(), tek bir nesne oluşturur ve O(1) süresinde çalışır. WarningCollector eklemeleri amortize edilmiş O(1) liste eklemeleridir. getWarnings(), içteki listeyi döndürür. Akış kipinde BinaryBuffer, diske taşmadan önce belleği maxmemory eşiğine (varsayılan 2 MB) kadar tutar; bu da büyük belgelerde tepe bellek kullanımını sabit tutar. Bu başvuru sayfası için varsayılan performance_budget değeri wall_ms: 1500, peak_mb: 64 şeklindedir.

Güvenlik notları

İmzalı ve zaman damgalı çıktıda duvar saati belirsizliğini kaldırmak için saat yüzeyini kullanın: sabit bir saat enjekte edin ve bunu Config::deterministic ile eşleştirin. PdfStringEscaper, PDF dizesi ve ad çıktısı için tek denetlenebilir kaçış aracıdır. Kullanıcının sağladığı metindeki kaçırılmamış parantezler veya sınırlayıcılar yoluyla içerik enjeksiyonunu önlemek için tüm dize yayımını bunun üzerinden yönlendirin. Uyarılar, öğe türleri ve özellik kimlikleri gibi belgeden türetilmiş ayrıntılar taşıyabilir. Uyarı çıktısını düşük güven düzeyli bir günlük havuzuna iletmeden önce temizleyin.

Uygunluk

Belirtim	Madde	Konu
PSR-20 (PHP-FIG)	psr_20_clock#2.1	Saat okuma işlemi değişmez bir tarih-saat döndürür
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	Düz dize ve ad nesnesi kaçışı (açımlanmıştır; ISO metni alıntılanmamış, hiçbir parça sabitlenmemiştir)

SystemClock, PSR-20 ClockInterface arabirimini uygular. Kaçış aracı, PDF’nin düz dize ve ad nesnesi karakter kurallarını izler. ISO metni, sitenin alıntı ilkesi kapsamında açımlanmıştır; hiçbir birebir parça sabitlenmemiştir.

Ayrıca bakın

• /modules/core/exception/ — DegradedException, fırlatan: addWithPolicy()
• /modules/core/contracts/ — DegradationPolicy, Capability
• /modules/core/observability/ — uyarı iletimi ve ölçümler
• /modules/core/config/ — Config::deterministic, saatle eşleşir
• /modules/core/writer/ — şunların dahili tüketicisi: BinaryBuffer ve PdfOperators

Sözlük: PSR-20 · bozulma ilkesi · değer nesnesi