Filter — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\Filter ad alanındaki NextPDF Pro Filter modülünün sözleşme düzeyindeki başvurusudur. Yüzey iki sınıftan oluşur. DecodeParms, bir PDF /DecodeParms sözlük parçasını değişmez, sınır denetimli bir değer nesnesine ayrıştırır. PngPredictor, FlateDecode ile açılmış akış baytları üzerinde PNG öngörücü ailesini (10-15 etiketleri) tersine çevirir. Modül, Pro Diff ve Classifier çıkarıcılarına hizmet eder. Genel amaçlı bir akış filtresi çerçevesi değildir. Bu sayfa, genel API’yi, gözlemlenebilir davranış sözleşmesini ve türlenmiş hata modlarını belirtir. Kullanım rehberi ve kod örnekleri Filter yetenek sayfasında yer alır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Hiçbir çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Filter sınıfları, nextpdf/pro yüklü olduğunda kullanılabilir.

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla oluşur veya başarısız olur	Notlar
DecodeParms	kurucu: int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Varsayılanlar “öngörücü yok” olarak kodlanır	—	—	final readonly; dört özelliğin tümü herkese açık ve değişmezdir
DecodeParms::fromDictionary()	string $raw — ham sözlük metni, çevreleyen nesne gövdesi hoş görülür	Eksik anahtarlar varsayılanlarını korur; eşleştirme boşluk toleranslıdır	self	InvalidArgumentException	Ayrıştırma zamanı darboğazı; sınırlar davranış sözleşmesinde listelenir
DecodeParms::isPngPredictor()	yok	Saf yüklem; G/Ç yok	bool — 10-15 öngörücüsü için true	—	Ters filtreyi çağırmadan önce buna göre dallanın
PngPredictor	—	Durumsuz	—	—	final; tek giriş noktası statik inverse()’tir
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Satır başına etikete göre satır satır ters filtreler; boş girdi boş dize döndürür	string — filtre etiketleri çıkarılmış yeniden yapılandırılmış yük	InvalidArgumentException	Yalnızca 10-15 öngörücüsünü kabul eder; TIFF öngörücüsü kapsam dışıdır

Giriş noktası imzaları

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

Davranış sözleşmesi

/DecodeParms ayrıştırması

DecodeParms::fromDictionary(), ham sözlük metnindeki dört tanınan anahtarı tam sayı olarak eşleştirir: /Predictor, /Columns, /Colors ve /BitsPerComponent. Bunlar, ISO 32000-2:2020 §7.4.4.4’ün LZWDecode ve FlateDecode filtreleri için tanımladığı öngörücü parametreleridir. Eşleştirme boşluk toleranslıdır ve çevreleyen PDF belirteçlerinden etkilenmez. Eksik anahtarlar varsayılanlarını korur: öngörücü 1, columns 1, colors 1, bileşen başına bit 8. Mevcut değerler, herhangi bir geometri ters filtrenin satır tahsisine ulaşmadan önce, ayrıştırma zamanında fail-closed olarak doğrulanır:

• Tanınan herhangi bir anahtar için mevcut bir negatif değer reddedilir.
• 1,000,000 üzerindeki /Columns reddedilir.
• 32 üzerindeki /Colors reddedilir.
• {1, 2, 4, 8, 16} dışındaki /BitsPerComponent reddedilir.
• 64,000,000 bayt üzerindeki türetilmiş bir satır adımı reddedilir.

isPngPredictor(), ayrıştırılan öngörücü 10 ile 15 arasında olduğunda true döndürür. Öngörücü 1 (öngörü yok) ve öngörücü 2 (TIFF grubu) false döndürür.

Satır geometrisi

PngPredictor::inverse(), her satırın önünde bir baytlık bir filtre etiketinin yer aldığı FlateDecode ile açılmış bir bayt akışını tüketir. Etiketleri çıkarılmış yeniden yapılandırılmış yükü yayar. Satır yükü genişliği ceil(columns * colors * bitsPerComponent / 8) bayttır; satır adımı bir etiket baytı ekler. Sol komşu ofseti (piksel başına bayt) max(1, floor(colors * bitsPerComponent / 8)) değeridir, bu nedenle bayt altı paketlemeler bir bayta yuvarlanır. Filtreleme, PNG filtre anlamlarıyla eşleşecek şekilde bit derinliğinden bağımsız olarak tam baytlar üzerinde çalışır.

Satır başına yeniden yapılandırma

Etiket	Filtre	Yeniden yapılandırma
0	None	doğrudan geçiş
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

Tüm toplamlar modulo 256 alınır. İlk satır için ve ilk pikselin solundaki baytlar için, eksik komşu W3C PNG §9.2’ye göre sıfır olarak okunur. Ters işlem tamamen satır başına etiket tarafından yönlendirilir. Bu, ISO 32000-2:2020 §7.4.4.4 kapsamında hem sabit öngörücüler (10-14) hem de Optimum (15) için uyumlu davranıştır, bu nedenle yazıcı etiket değişkenliği hoş görülür.

Doğrulama katmanlaması

Parametre doğrulaması, tasarımı gereği iki katmanda çalışır. DecodeParms, ayrıştırma zamanı darboğazıdır ve düşmanca büyüklükleri önce reddeder. PngPredictor::inverse(), ikinci bir katman olarak kendi denetimlerini korur: dört parametrenin tümünde aralık denetimleri, adım çarpımını oluşturmadan önce tek tek çarpanları PHP_INT_MAX ile karşılaştıran taşma korumaları, aynı 64,000,000 baytlık satır başına tavan ve herhangi bir satır arabelleği tahsis edilmeden önce girdinin tamamından daha büyük bildirilmiş bir adımı reddeden girdiyle orantılı bir sınır.

Belirlenimcilik

Her iki giriş noktası da girdilerinin saf statik işlevleridir. G/Ç, günlükleme veya genel durum yoktur. Çalışma süresi, küçük bir bayt başına sabitle girdi uzunluğunda doğrusaldır. /DecodeParms ayrıştırması, birkaç sınırlı düzenli ifade eşleşmesidir. Bütçeler, frontmatter performance_budget içinde belirtilir.

Uç durumlar ve hata modları

Bu modüldeki her hata, mesajda hatalı değer adlandırılmış olarak InvalidArgumentException oluşturur.

• fromDictionary(), tanınan herhangi bir anahtar için mevcut bir negatif değeri reddeder.
• fromDictionary(), 1,000,000 üzerindeki /Columns ve 32 üzerindeki /Colors değerini reddeder.
• fromDictionary(), {1, 2, 4, 8, 16} dışındaki /BitsPerComponent ve 64,000,000 bayt üzerindeki türetilmiş bir satır adımını reddeder.
• inverse(), 10-15 dışındaki bir öngörücüyü reddeder. TIFF öngörücüsü (2) burada asla ters filtrelenmez; önce isPngPredictor()’a göre dallanın.
• inverse(), 1’in altındaki columns veya colors değerini ve yasal küme dışındaki bitsPerComponent değerini reddeder.
• inverse(), adım çarpımı platform tam sayısını taşıracak geometriyi, herhangi bir tahsisten önce reddeder.
• inverse(), gerçek girdi uzunluğundan bağımsız olarak, 64,000,000 baytlık satır başına tavanın üzerindeki bir satır adımını reddeder.
• inverse(), boş girdi için boş bir dize döndürür; bu bir hata değildir.
• inverse(), girdinin tamamından daha büyük bildirilmiş bir satır adımını, ofset 0’da kesilmiş bir satır olarak başarısız kılar.
• inverse(), sondaki kısmi bir satırı, ofseti ve bayt sayılarını adlandırarak kesilmiş bir satır olarak başarısız kılar.
• inverse(), bilinmeyen bir satır başına filtre etiketini (0-4 değil), etiket değeri ve satır ofsetiyle başarısız kılar.
• Bildirilmiş /DecodeParms geometrisi ile gerçek akış düzeni arasındaki bir uyuşmazlık, sessizce bozuk bir çıktı olarak değil, bir parametre veya kesilme hatası olarak ortaya çıkar.
• Average filtresi, PNG belirtiminin floor anlamlarına uyacak şekilde tam sayı bölmesi kullanır.
• Bu modülde hiçbir kriptografik işlem gerçekleşmez. Davranış, FIPS kısıtlamalı dağıtımlarda aynıdır.

Uygunluk

İddia	Standart	Madde
/Predictor filtre parametresi öngörücü algoritmasını seçer; izin verilen değerler öngörücü değerleri tablosundan gelir.	ISO 32000-2:2020	§7.4.4.4
PDF iki öngörücü grubu tanımlar: TIFF grubu tek Predictor 2 işlevidir; PNG grubu 10-15 etiketleridir.	ISO 32000-2:2020	§7.4.4.4
/BitsPerComponent geçerli değerleri 1, 2, 4, 8 ve 16 olup varsayılan 8’dir; /Colors 1 veya daha büyüktür, varsayılan 1’dir; /Columns varsayılanı 1’dir.	ISO 32000-2:2020	§7.4.4.4
0-4 filtre türleri için yeniden yapılandırma işlevleri bayt bazında modulo 256 çalışır; eksik sol ve önceki satır baytları sıfır olarak okunur.	W3C PNG (Third Edition)	§9.2
Paeth filtre türü sol, üst ve sol üst komşuların PaethPredictor’ını hesaplar ve en yakın olanı seçer.	W3C PNG (Third Edition)	§9.4

Tüm maddeler açımlanmıştır; NextPDF normatif metni yeniden üretmez. Bunlar sertifikalar değil, yetenek beyanlarıdır; NextPDF hiçbir sertifikaya sahip değildir ve hiçbirini vermez. Yeniden yapılandırma matematiğinin ve parametre varsayılanlarının uygunluğu, birim paketi tarafından sınanır. Tam bir PDF akış filtresi çerçevesi ve TIFF öngörücüsünün tersine çevrilmesi bu modülün kapsamı dışındadır.

Geliştirme notları

• Her iki sınıf da nextpdf/pro 3.0.0’dan beri gelir ve 3.1.0’da günceldir.
• Modül, girdileri bir öngörücü taşıdığında Pro Diff ve Classifier çıkarıcıları tarafından tüketilir.
• inverse()’i çağırmadan önce isPngPredictor()’a göre dallanın; öngörücü 1 ve TIFF öngörücüsü PNG tersine çevirme gerektirmez.
• Modül, kendi satır başına tahsisini sınırlar. Güvenilmeyen akışlarda öngörücüleri tersine çeviren çağıranlar, Pro çıkarıcıların yaptığı gibi, açılmış girdi boyutunu yine de yukarı akışta sınırlamalıdır.
• Sabit öngörücüler (10-14) ve Optimum (15) tek bir kod yolunu paylaşır; satır başına etiket her iki durumda da yeniden yapılandırmayı yönlendirir.
• İç mekanizma ayrıntısı, kaynak deposunun iç belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Filter (yetenek) — kurulum, hızlı başlangıç ve üretim kullanım örnekleri.
• Diff — Derinlemesine başvuru — ters filtrenin bir tüketicisi.
• Classifier — Derinlemesine başvuru — ters filtrenin bir tüketicisi.