Pro sürüm

Document — Derinlemesine başvuru

Bir bakışta

Document modülü üç Pro derleme ilkeli sağlar: sayfa aralığı bölme, çok belgeli birleştirme ve PDF Portfolio (Collection) sözlüğü oluşturma. PdfSplitter, sayfa aralıklarını bağımsız, yapısal olarak uyumlu PDF’lere ayıklar ve belgelerin tamamını yeniden numaralandırılmış tek bir dosyada birleştirir. PdfPortfolio, gömülü dosyaları sıralanabilir şema sütunlarıyla sunan Collection sözlüğünü oluşturur. Her giriş noktası, düşmanca girdiye karşı girdi boyutunu ve nesne sayılarını sınırlar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gelir ve bir 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 bir lisans edinin.

Genel API yüzeyi

Tüm modül türleri NextPDF\Pro\Document ad alanında bulunur. PageRange ve MergeResult, NextPDF\Document içindeki Core değer nesneleridir.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
`PdfSplitter::split()`	`string $pdfData`, `list<PageRange> $ranges`, `int $maxBytes = 100_000_000`, `int $maxRanges = 1000`	Her aralık için bir bağımsız PDF segmenti oluşturur	`SplitResult`	Eksik bir `%PDF` başlığında `InvalidArgumentException`; boyut, aralık sayısı veya kapanış korumasında `OverflowException`	Korumalar herhangi bir ayrıştırmadan önce çalışır
`PdfSplitter::splitEvery()`	`string $pdfData`, `int $pagesPerSegment`	Bitişik N sayfalık aralıklar türetir; son segment daha kısa olabilir	`SplitResult`	`$pagesPerSegment < 1` olduğunda veya başlık eksik olduğunda `InvalidArgumentException`	Varsayılan üst sınırlarla `split()`’e devreder
`PdfSplitter::extractPages()`	`string $pdfData`, `PageRange $range`	Tek bir aralığı bağımsız PDF baytları olarak döndürür	`string`	Eksik bir başlıkta `InvalidArgumentException`; kapanış korumasında `OverflowException`	Bu yolda üst sınır parametresi yoktur
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`, `int $maxInputs = 100`, `int $maxBytesEach = 100_000_000`	Girdileri sırayla yeniden numaralandırılmış tek bir PDF’de birleştirir	`MergeResult`	Boş bir listede veya PDF olmayan girdide `InvalidArgumentException`; sayı, girdi başına boyut veya kapanış korumasında `OverflowException`	3.1.0’dan beri; en yüksek girdi sürümü çıktı başlığını belirler
`SplitResult`	readonly `$segments`, `$ranges`, `$totalPages`	Ham segment baytlarını ve kaynak meta verilerini taşır	—	—	`final readonly` değer nesnesi
`SplitResult::count()`	—	Üretilen segmentleri sayar	`int`	—	—
`SplitResult::segment()`	`int $index`	Bir segmentin baytlarını döndürür	`string`	Sınır dışı bir dizinde `OutOfRangeException`	Sıfır tabanlı dizin
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	Yapım sırasında görünüm modunu doğrular	—	`tile`, `detail`, `hidden` dışında bir modda `InvalidArgumentException`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	Bir şema sütunu ekler	`self`	—	Akıcı
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	Bir dosya girdisi ekler	`self`	—	Akıcı
`PdfPortfolio::getSchema()`	—	Biriktirilen şema alanlarını döndürür	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	Biriktirilen dosya girdilerini döndürür	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	Dosya girdilerini sayar	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	Collection sözlüğü dizesini yayar	`string`	—	Şema ve sıralama blokları yalnızca alanlar mevcut olduğunda görünür
`PortfolioEntry`	`$filename`, `$data`, `$description = ''`, `$mimeType = 'application/octet-stream'`, `$customFields = []`	Değişmez dosya girdisi değer nesnesi	—	—	`size()`, veri bayt uzunluğunu döndürür
`PortfolioField`	`$name`, `PortfolioFieldType $type`, `$displayName = ''`, `$order = 0`, `$visible = true`	Değişmez şema sütunu değer nesnesi	—	—	`effectiveDisplayName()`, `$name`’e geri döner
`PortfolioFieldType`	Dize enum: `Text`, `Date`, `Number`, `FileName`, `Description`, `Size`, `ModDate`, `CreationDate`	`pdfSubtype()` aracılığıyla her durumu bir PDF `/Subtype` değerine eşler	`string` (`S`, `D`, `N`, `F`, `Desc`)	—	Tarih benzeri durumlar `D` alt türünü paylaşır; sayısal durumlar `N` paylaşır

Giriş noktası imzaları:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Davranış sözleşmesi

Bölme ve birleştirme, tek bir nesne grafiği ardışık düzenini paylaşır:

Girdi %PDF başlığıyla başlamalıdır. Boyut ve sayı korumaları ayrıştırmadan önce çalışır ve ihlalde OverflowException oluşturur.
Yaprak sayfalar, sayfa nesnesi işaretleri taranarak algılanır; sayfa ağacı düğümleri sayımın dışında tutulur.
Ayrıştırıcı, akış farkında bir sonlandırıcı taramasıyla her sıkıştırılmamış dolaylı nesneyi dizinler. Bir nesne kimliğinin ilk geçtiği yer kazanır, bu nedenle artımlı güncelleme geçersiz kılmaları uygulanmaz.
Devralınabilir sayfa ağacı öznitelikleri (/Resources, /MediaBox, /CropBox, /Rotate), her ayıklanan sayfaya /Parent zinciri izlenerek gerçekleştirilir, bu nedenle segmentler bağımsızdır.
Her sayfanın geçişli dolaylı başvuru kapanışı, /Parent geri kenarı hariç toplanır ve yeni bir bitişik kimlik alanına yeniden numaralandırılır.
Serileştirici; başlığı, Catalog’u, Pages ağacını, sayfa nesnelerini ve kapanış nesnelerini yayar, ardından bayt düzeyinde doğru ofsetlere sahip bir çapraz başvuru tablosu ve xref anahtar sözcüğünü gösteren bir startxref yayar.
mergeDocuments, ardışık düzeni her girdi için tek bir paylaşılan kimlik alanına tekrarlar. En yüksek girdi PDF sürümü çıktı başlığını belirler. Bu, hataya kapalı kalan devre dışı bırakılmış Core birleştiricisinin uyumlu yerine geçenidir.
Çıktı belirleyicidir. Hiçbir zaman damgası veya rastgele tanımlayıcı yayılmaz, bu nedenle aynı girdi aynı baytları verir.

Portfolio derlemesi:

Yapıcı, görünüm modunu doğrular. Yayılan /View belirteci sırasıyla tile, detail ve hidden için /T, /D veya /H olur.
generateCollectionDictionary(); /Type /Collection, /View belirteci, alanlar mevcut olduğunda bir /Schema bloğu ve ilk şema alanında artan yönde bir /Sort yönergesi yayar.
Her şema alanı; /Subtype (pdfSubtype()’ten), /N (kaçışlanmış görünen ad), /O (sıra) ve /V (görünürlük) yayar.
Alan adları geçerli PDF ad belirteçlerine arındırılır; sözcük olmayan karakterler alt çizgiye dönüşür. Dize değerleri PDF değişmez dizeleri olarak kaçışlanır.
Dosya girdileri, yazma katmanı tarafından gömülmek üzere getEntries() aracılığıyla açığa çıkarılır. Collection sözlüğünün kendisi yalnızca görünümü, şemayı ve sıralamayı taşır.

Uç durumlar ve hata modları

Hiçbir sayfayla eşleşmeyen bir aralık, bir hata değil, minimal tek sayfalık bir segment (612 x 792 MediaBox) verir.
Algılanabilir sayfa işareti olmayan bir belge, tek sayfa olarak sayılır.
Nesne akışları içinde depolanan sayfalar algılanmaz; ayıklamaya yalnızca sıkıştırılmamış dolaylı nesneler katılır.
Yinelenen nesne kimlikleri mevcut olduğunda, en düşük ofsetli revizyon kullanılır; sonraki artımlı güncelleme revizyonları yok sayılır.
Segment başına başvuru kapanışı 50,000 nesneyle sınırlıdır; kötü niyetli bir şekilde kendine başvuran veya yayılan bir grafik OverflowException oluşturur.
Varsayılan üst sınırlar: 100 MB girdi, 1,000 aralık, 100 birleştirme girdisi. Tümü çağrı başına çağıran tarafça ayarlanabilir.
splitEvery(), 1’in altındaki bir segment boyutunu InvalidArgumentException ile reddeder.
SplitResult::segment(), sınır dışı bir dizini OutOfRangeException ile reddeder.
Yalnızca noktalama işaretlerinde farklılık gösteren iki şema alanı adı, aynı sözlük anahtarına arındırılır; sonraki alan, yayılan şemada öncekini sessizce gölgeler.
Bu modül hiçbir kriptografik işlem gerçekleştirmez; FIPS modu davranışını değiştirmez.

Uygunluk

Segment ve birleştirme çıktısı ISO 32000-2’nin sayfa nesnesi modelini izler; kaynak, ilgili maddeleri açıklar. Harici olarak denetlenebilir iddialar:

Trailer düzeni, startxref bayt ofseti ve %%EOF sonlandırıcısı ISO 32000-2:2020, §7.5.5’i izler — başvuru ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
Collection sözlüğü /View değerleri (/T, /D, /H) ISO 32000-2:2020, §12.3.5’i izler — başvuru 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
Collection alanı /Subtype, /N, /O ve /V girdileri ISO 32000-2:2020, §12.3.5’i (collection field dictionary) izler — başvuru 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Bu ifadeler, modülün testleriyle doğrulanan uygulanmış yeteneği tanımlar. Bir yapının desteklenmesi bir uygunluk iddiası değildir ve uygunluk sertifikasyon değildir; NextPDF bu modül için hiçbir üçüncü taraf sertifikasyonuna sahip değildir.

Geliştirme notları

Tüm modül sınıfları final; sonuç ve değer nesnesi türleri readonly. Bölücü ve Portfolio türleri 1.9.0’a dayanır; mergeDocuments() 3.1.0’da eklendi.
PageRange ve MergeResult Core türleridir, bu nedenle çağrı yerleri sürümler arası taşınabilir kalır.
Segment trailer’ları yalnızca /Size ve /Root taşır; hiçbir /ID dosya tanımlayıcısı veya /Info sözlüğü yayılmaz.
Artımlı güncelleme veya imzalama iş akışları için, segment baytlarını yerinde sonradan düzenlemek yerine Writer modülüne verin.
Modül hiçbir belge içeriğini günlüğe kaydetmez.

Yayın sınırı

Bu sayfa yalnızca harici olarak gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalıştırma kılavuzu (runbook) dosya adları ve talep önekleri kapsam dışıdır.