Çekirdek ve genel hatalar

Kapsam

Bu girişler, NextPDF’in fırlattığı çekirdek ve genel amaçlı istisnaları kapsar. Çoğu, kendisi \RuntimeException sınıfını genişleten ve ContextAwareExceptionInterface arayüzünü uygulayan temel NextPdfException sınıfını genişletir. Bu arayüz tek bir yöntemi, bir günlüğe veya APM yüküne serileştirmek için güvenli ilkellerin düz bir snake_case eşlemesini döndüren getContext(): array yöntemini sunar.

NextPdfException ailesini tek bir catch (NextPdfException $e) ile yakalayın. Bu kümede doğrudan \RuntimeException sınıfını genişleten birkaç düşük seviyeli hatayı (aşağıda listelenmiştir) kapsamak için ayrıca bir catch (\RuntimeException $e) da ekleyin. Temel NextPdfException::getContext() boş bir dizi döndürür; alt sınıflar etki alanı alanları eklemek için onu geçersiz kılar. Bir sınıf getContext() yöntemini geçersiz kılmadığında, boş diziyi devralır ve tanılama ayrıntısı bunun yerine iletide ve türlü erişimcilerde bulunur.

Bu kümedeki dört tür NextPdfException sınıfını genişletmez: BlackPointCompensationUnsupportedException ve UnsupportedSourceDocumentException doğrudan \RuntimeException sınıfını genişletir (bunları \RuntimeException olarak yakalayın) ve ComplianceViolation ile RuleViolation istisna değil, değer nesnesidir — motorun döndürdüğü hata ve ihlal verisini modelledikleri için burada belgelenmişlerdir.

Temel istisna

NextPdfException

• Nedir. NextPDF çekirdeği ve uzantı paketleri tarafından fırlatılan her istisna için abstract temel sınıf. \RuntimeException sınıfını genişletir ve ContextAwareExceptionInterface arayüzünü uygular. Bu tek türü yakalamak, herhangi bir kitaplık hatasını yakalar.
• Bağlam. Temel getContext() boş bir dizi döndürür. Alt sınıflar, etki alanına özgü alanları döndürmek için onu geçersiz kılar.
• Çözüm. Doğrudan fırlatılmaz. Onu yakala-her-şey türü olarak kullanın; özel işleme için somut alt sınıfa göre dallanın.

Yapılandırma ve özellik geçişi

InvalidConfigException

• Ne zaman fırlatılır. Bir Config değeri veya değerlerin bir bileşimi geçersiz olduğunda — eksik bir zorunlu ayar, karşılıklı dışlayan bir seçenek ya da kabul edilen aralığının dışında bir değer. Bu, bir geliştirici hatasını işaret eder: çağıran kod, yeniden denemeden önce düzeltilmesi gereken bir yapılandırma sağladı. İleti, anahtarı, beklenen türü veya aralığı ve sağlanan değerin gerçek hata ayıklama türünü bildirir.
• Bağlam. getContext(), config_key, given_value ve expected_type döndürür. Türlü erişimciler: getConfigKey(), getGivenValue(), getExpectedType().
• Çözüm. Geliştirici eylemi: NextPDF’i yeniden çağırmadan önce adlandırılmış yapılandırma anahtarını beklenen türden veya aralıktan bir değere düzeltin.

NotImplementedException

• Ne zaman fırlatılır. Bir genel API giriş noktasına ulaşıldığında ancak uygulaması geçerli sürümde kasıtlı olarak yok olduğunda. Bisect öncesi çağıranlara sessiz bir işlem-yok yerine sesli, eyleme dönük bir hata vermek için var olan kullanımdan kaldırılmış uyumluluk katmanlarında kullanılır. İleti, makinede grep’lenebilir bir feature etiketini ve bir followUp başvurusunu (kusur kimliği, izleme bağlantısı veya sprint adı) birleştirir.
• Bağlam. getContext() yöntemini geçersiz kılmaz, bu nedenle boş bir dizi döndürür. $feature ve $followUp değerleri genel salt okunur özelliklerdir ve iletiye gömülüdür.
• Çözüm. Kitaplık çağıranı eylemi: çağrıyı kaldırın veya adlandırılmış takibi getiren bir gelecek sürüme sabitleyin.

IncompatibleFeatureFlagsException

• Ne zaman fırlatılır. Config derleme zamanında (Config::validate()), bir CssFeatureFlags bileşimi dahili olarak tutarsız olduğunda — bir bayrak, devre dışı bırakılmış başka bir bayrağı varsayar. Bugün yasaklanan tek bileşim layoutSubgrid = true ile layoutGrid = false: alt ızgaralı bir eksen, ızgara çizgilerini bir üst ızgara konteynerinden türetir (CSS Grid Layout Module Level 2 §1); bu nedenle ızgarasız alt ızgara, var olamayacak bir ızgarayı tanımlar. Denetim, çözümlenmiş bayraklara karşı çalışır; bu nedenle CssRenderingMode::Safe (her Phase 4+ özelliğini kapatmaya zorlar) bileşimi tetiklemek yerine maskeler. StrictModeViolation sınıfını genişletir.
• Bağlam. getContext(), üst katı kip alanlarını (cssDeviation, excId, chunkSha256, location) layoutGrid ve layoutSubgrid boole değerleriyle birleştirir. location Config::validate() değeridir ve cssDeviation bayrak çiftini kodlar.
• Çözüm. Kitaplık çağıranı eylemi: layoutSubgrid ile birlikte layoutGrid etkinleştirin ya da layoutSubgrid devre dışı bırakın.

IncompatibleRenderingModeException

• Ne zaman fırlatılır. Config derleme zamanında, bir CssRenderingMode ve CssLayoutMode eşleşmesi kip matrisinin uyumlu hücrelerinin dışına düştüğünde. Bugün yasaklanan tek eşleşme CssRenderingMode::Safe + CssLayoutMode::Retained — Safe her Phase 4+ özelliğini kapatmaya zorlar ve saklanan kip biçimlendirme bağlamlarını (Grid, Subgrid, @container) tüketicisiz bırakır; bu nedenle bileşim, sessizce düşmesine izin verilmek yerine reddedilir. StrictModeViolation sınıfını genişletir.
• Bağlam. getContext(), üst katı kip alanlarını mode1 (oluşturma kipi değeri) ve mode2 (yerleşim kipi değeri) ile birleştirir. cssDeviation kip çiftini kodlar; location Config::validate() değeridir.
• Çözüm. Kitaplık çağıranı eylemi: geri alma için Safe + Streaming seçin ya da Grid / Subgrid / Container Queries için Retained ile birlikte Safe olmayan bir oluşturma kipi (Normal / Strict / Audit) seçin.

StrictModeViolation

• Ne zaman fırlatılır. CssRenderingMode::Strict altında fırlatılan herhangi bir spesifikasyon-sapması istisnası için abstract temel sınıf. Katı kipte, kayıtlı bir EXC-NNN istisna girişine bağlı olmayan, algılanan herhangi bir CSS sapması, algılama noktasında bu sınıfın (veya bir alt sınıfının) bir örneğini fırlatır. Doğrudan fırlatılmaz; IncompatibleFeatureFlagsException ve IncompatibleRenderingModeException sınıflarına bakın.
• Bağlam. getContext() dört ADR-023 alanını döndürür: cssDeviation (sapan yapı için kısa etiket), excId (kayıtlıysa kayıt tanımlayıcısı, aksi hâlde null), chunkSha256 (bilindiğinde spesifikasyon-alıntısı parça karması, aksi hâlde null) ve location (çağıran tarafından okunabilir köken, aksi hâlde null).
• Çözüm. Kitaplık çağıranı eylemi: sapmayı yeni, imzalanmış bir EXC-NNN girişi olarak kaydedin ya da oluşturucuyu sapmayı kaldıracak şekilde düzeltin.

HTML ve CSS girdisi

HtmlParsingException

• Ne zaman fırlatılır. HTML girdisi ayrıştırma veya DOM oluşturma başarısız olduğunda: geçersiz karakter kümesi bildirimleri, girdi-boyutu-sınırı ihlalleri, aşırı iç içe geçme derinliği, öğe-sayısı taşmaları ve satır-sayısı üst sınırı gibi tablo-yapısı hataları. CSS’e özgü kaynak tükenmesi bunun yerine CssParserLimitExceededException ve CssResolutionBudgetExceededException tarafından bildirilir.
• Bağlam. getContext(), html_snippet (hatalı HTML’nin kısa, kesilmiş bir alıntısı), position (bayt ofseti veya bilinmiyorsa -1) ve rule (ihlal edilen ayrıştırıcı kısıtlaması) döndürür. Türlü erişimciler: getHtmlSnippet(), getPosition(), getRule().
• Çözüm. Geliştirici eylemi: HTML girdisini sadeleştirin veya ayrıştırıcı sınırlarını ayarlayın.

CssParserLimitExceededException

• Ne zaman fırlatılır. CSS girdisi, yapılandırılmış bir ayrıştırıcı güvenlik sınırını aştığında. Adlandırılmış yapıcılar aracılığıyla iki kategori kapsanır: forByteLimit() (stil sayfası, güvenli regex işleme için fazla büyük) ve forNestingDepth() (CSS iç içe geçme özyinelemesi fazla derin). Her iki ileti de gerçek değeri ve sınırı adlandırır.
• Bağlam. getContext(), limit_type (byte veya nesting_depth), actual ve limit döndürür.
• Çözüm. Geliştirici eylemi: stil sayfasını daha küçük sayfalara bölün, iç içe geçme derinliğini azaltın ya da yapılandırılmış sınırı yükseltin.

CssResolutionBudgetExceededException

• Ne zaman fırlatılır. CSS :has() çözümlemesi, dolaşım bütçesini aştığında. İki geçişli :has() çözümleyicisi, hastalıklı seçicilerin ikinci dereceden belge gezintilerine yol açmasını önlemek için katı bir düğüm-ziyaret bütçesi uygular; toplam ziyaret sayısı sınırı aştığında stil sayfası fazla karmaşık olarak reddedilir. İleti, ziyaret sayısını ve bütçeyi adlandırır.
• Bağlam. getContext(), visits ve budget döndürür. Türlü erişimciler: getVisits(), getBudget().
• Çözüm. Geliştirici eylemi: seçici karmaşıklığını azaltın ya da yapılandırılmış bütçeyi yükseltin.

Yazı tipleri ve görüntüler

FontNotFoundException

• Ne zaman fırlatılır. Bir yazı tipi dosyası, dosya sistemi düzeyinde bulunamadığında veya okunamadığında: istenen aile veya yol yok, okunabilir değil ya da yapılandırılmış yazı tipleri dizinine erişilemiyor. Yazı tipi verisi geçerli olabilir — bu yalnızca ona erişilemediğini işaret eder. İleti, aranan yolları listeler.
• Bağlam. getContext(), font_name, search_paths (bir liste) ve fallback_attempted (bir boole) döndürür. Türlü erişimciler: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Çözüm. Geliştirici eylemi: yazı tipi yolunu doğrulayın. Altyapı eylemi: yazı tipi dosyasındaki veya dizinindeki dosya izinlerini düzeltin.

FontParsingException

• Ne zaman fırlatılır. Bir yazı tipi dosyası bulunduğunda ancak içeriği kullanılamadığında: bozuk, desteklenmeyen bir biçimde ya da zorunlu tablolar eksik. TrueType, Type 1, CFF ve OpenType ayrıştırma sırasındaki yapısal doğrulama hatalarını kapsar — kesilmiş başlıklar, geçersiz tablo dizinleri, eksik zorunlu tablolar (head, hhea, OS/2), paket açma hataları ve boyut ihlalleri. İleti, dosyayı ve ayrıştırma hatasını adlandırır.
• Bağlam. getContext(), font_file ve parse_error döndürür. Türlü erişimciler: getFontFile(), getParseError().
• Çözüm. Geliştirici eylemi: yazı tipi dosyasını geçerli bir dosyayla değiştirin.

ImageProcessingException

• Ne zaman fırlatılır. Bir görüntü kodu çözülemediğinde, desteklenmeyen bir biçimde olduğunda ya da GD/Imagick işlemesinde başarısız olduğunda: tanınmayan sihirli baytlar, bozuk JPEG verisi, desteklenmeyen MIME türleri, dosya-boyutu-sınırı ihlalleri ve GD kaynak ayırma hataları. Görüntüye erişilebiliyordu ancak gömme için piksel verisi çıkarılamadı.
• Bağlam. getContext(), image_path (satır içi veri için boş), format (algılanan veya beklenen, örneğin jpeg, png, unknown) ve operation (örneğin decode, resize, embed) döndürür. Türlü erişimciler: getImagePath(), getFormat(), getOperation().
• Çözüm. Geliştirici eylemi: geçerli, desteklenen bir görüntü dosyası sağlayın.

Çıktı, yerleşim ve serileştirme

CompressionException

• Ne zaman fırlatılır. FlateDecode (zlib) sıkıştırması veya açma işlemi başarısız olduğunda — içerik akışlarında, yazı tipi verisinde, sayfa içeriğinde, ek verisinde ve çapraz başvuru akışlarında gzcompress/gzuncompress hataları. Genellikle bozuk bir girdi akışı, yetersiz bellek ya da eksik bir zlib uzantısı.
• Bağlam. getContext(), algorithm (filtre adı, örneğin FlateDecode, LZWDecode) ve stream_length (bayt uzunluğu veya bilinmiyorsa -1) döndürür. Türlü erişimciler: getAlgorithm(), getStreamLength().
• Çözüm. Altyapı eylemi: ext-zlib yüklendiğini ve belleğin yeterli olduğunu doğrulayın.

WriterException

• Ne zaman fırlatılır. PDF serileştirme, doğrusallaştırma veya G/Ç çıktısı başarısız olduğunda: PdfWriter akış-yazma hataları, çapraz başvuru tablosu bozulması, başlık/fragman üretimi hataları, nesne-başvurusu çözümleme hataları, dosya yazma hataları ve çıktı-arabelleği taşmaları. Geçerli bir bellek-içi belge, geçerli bir bayt akışına serileştirilemedi. İleti, aşamayı adlandırır.
• Bağlam. getContext(), output_path (dize çıktısı için boş) ve writer_state (aşama, örneğin header, body, xref, trailer) döndürür. Türlü erişimciler: getOutputPath(), getWriterState().
• Çözüm. Altyapı eylemi: disk alanını, dosya izinlerini ve çıktı akışını denetleyin.

PageLayoutException

• Ne zaman fırlatılır. Sayfa yerleşimi kısıtlamaları karşılanamadığında: sütun yerleşimi ihlalleri (yetersiz genişlik, geçersiz sütun sayısı), sayfa sınırlarının ötesine içerik taşması ve kenar boşluğu çakışmaları. İstenen yerleşim, verilen sayfa boyutları ve içerik için geometrik olarak imkânsızdır. İleti, bilindiğinde sayfa numarasını ve ihlal edilen kısıtlamayı adlandırır.
• Bağlam. getContext(), page_number (birden başlayan veya bilinmiyorsa 0) ve constraint döndürür. Türlü erişimciler: getPageNumber(), getConstraint().
• Çözüm. Geliştirici eylemi: sayfa boyutunu, kenar boşluklarını, sütun ayarlarını veya içeriği ayarlayın.

TemplateException

• Ne zaman fırlatılır. TemplateManager içinde bir PDF şablonu içe aktarma veya yeniden kullanma işlemi başarısız olduğunda: geçersiz şablon durumu geçişleri (şablonları sıra dışı başlatma veya bitirme), var olmayan bir şablona başvurma ve şablon serileştirme sırasında akış sıkıştırma hataları. İleti, işlemi ve atandığında şablon kimliğini adlandırır.
• Bağlam. getContext(), template_id (henüz atanmamışsa boş) ve operation (örneğin begin, end, use, serialize) döndürür. Türlü erişimciler: getTemplateId(), getOperation().
• Çözüm. Geliştirici eylemi: şablon kullanım sırasını veya kaynak PDF’i düzeltin.

İçerik akışı değişmezleri

ContentStreamBalanceException

• Ne zaman fırlatılır. Bir ContentStreamBuilder, akış kapanışında (veya değişmezler erkenden öne sürüldüğünde akış ortasında) dengesiz bir işleç çifti algıladığında. Hangi yayıcının eşleşen Q, ET veya EMC olmadan bir q, BT veya BMC sızdırdığını günlüklemenin tanımlayabilmesi için denge değişmezini geçemeyen derinlik sayaçlarını yakalar. ISO 32000-2:2020 §8.4.2 (grafik-durumu yığını), §9.4.1 (metin nesneleri) ve §14.6 (işaretli içerik) uyarınca.
• Bağlam. getContext(), graphics_depth, text_block_depth, marked_content_depth ve offending_operator döndürür. Türlü erişimciler: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Çözüm. Geliştirici eylemi: bir yapıyı kapatmadan açan yayıcıyı bulun.

GraphicsStateBalanceException

• Ne zaman fırlatılır. Bir PDF içerik akışı dengesiz q/Q işleçleriyle kapandığında. ISO 32000-2:2020 §8.4.2, her grafik-durumu kaydetmesinin (q) akış bitmeden tam olarak bir geri yüklemeyle (Q) eşleştirilmesini gerektirir; dengesizlik, dönüşümü, kırpma yolunu, renkleri ve oluşturma amacını sonraki sayfalara veya Form XObject’lerine sızdırır. Yalnızca katı grafik-durumu denetimi etkinleştirildiğinde (NEXTPDF_GFXSTATE_STRICT=1) fırlatılır; gevşek kipte bunun yerine trigger_error() aracılığıyla bir uyarı yayılır.
• Bağlam. getContext(), save_depth (fazla kaydetme için pozitif, fazla geri yükleme için negatif) döndürür. Türlü erişimci: getSaveDepth().
• Çözüm. Geliştirici eylemi: eşleşmeyen save()/restore() çiftini bulun.

MissingShadingResourceException

• Ne zaman fırlatılır. ConicGradientRenderer::render(), bir Shading-kaynağı kayıt bağlamı olmadan çağrıldığında. v10.0.0 kırıcı değişikliği, önceki örtük-işaretçi-eşlemesi yedek yolunu kaldırdı: çağıranlar, /ShadingType 4 dolaylı nesnesinin sayfanın Shading-kaynağı alt sözlüğüne karşı kaydedilmesi için (ISO 32000-2 §8.7.4.2 / §8.7.4.3) oluşturucuyu bir ShadingResourceRegistryInterface ile kurmalıdır. İleti, çağıran bağlamını adlandırır ve v9.x→v10.0 geçiş notuna işaret eder.
• Bağlam. getContext(), context (kısa bir çağıran-bağlamı etiketi, örneğin ConicGradientRenderer::render) döndürür.
• Çözüm. Kitaplık çağıranı eylemi: render() çağrılmadan önce oluşturucu yapıcısına bir Shading-kaynağı kayıt örneği bağlayın.

Doğrusallaştırma (Hızlı Web Görünümü)

LinearizationInvariantException

• Ne zaman fırlatılır. v2 üç geçişli Linearizer, MEASURE → PLACE → FILL öne sürümlerinin ihlal edildiğini algıladığında: Pass 1 ile öngörülen dosya uzunluğuyla eşleşmeyen bir Pass 3 bayt sayısı (ofset kayması), serileştirilmiş genişlik için fazla küçük bir doğrusallaştırma sözlüğü yer tutucusu ya da nihai çıktıyla eşleşmeyen bir /H [offset length] ipucu-akışı ofseti. Bozuk bir PDF yaymak yerine bunu yüzeye çıkarmak, belirtilmiş bir güvenlik garantisidir.
• Bağlam. getContext(), invariant (ihlal edilen değişmez adı), expected, actual ve delta (işaretli fark) döndürür. Türlü erişimciler: getInvariant(), getExpectedValue(), getActualValue().
• Çözüm. Bakımcı eylemi: bir hata raporu açın — bu değişmezler, tüm iyi-biçimli girdiler için geçerli olmalıdır. Zincirlenmiş önceki istisnayı yakalayın.

LinearizationUnimplementedException

• Ne zaman fırlatılır. Doğrusallaştırıcı özellik bayrağı, kasıtlı olarak devre dışı bırakılmış bir arka uca ayarlandığında. Şu anda yalnızca linearizerVersion === 'v1-noop' için fırlatılır; bu, bir kod değişikliği veya yeniden dağıtım olmadan çalışma zamanında tüm doğrusallaştırma denemelerini reddeden acil-durum-düşürme ayarıdır — üretimde Hızlı Web Görünümü’nü kapatmak (kill-switch) için kullanışlıdır.
• Bağlam. getContext(), reason (kısa, insan tarafından okunabilir bir açıklama) döndürür. Türlü erişimci: getReason().
• Çözüm. Operatör / sürüm-mühendisliği eylemi: yapılandırmayı ayarlayın veya düzeltilmiş bir arka uç sürümüne yükseltin.

Uygunluk ve profil değişmezleri

ConformanceViolationException

• Ne zaman fırlatılır. İstenen bir özellik, belgenin bildirilen ISO uygunluk sözleşmesini bozmadan yayılamadığında ve motor, uyumsuz bir nesne yazmak yerine güvenli biçimde başarısız olduğunda. Kanonik tetikleyici, her PDF/A bölümünün yasakladığı (ISO 19005 serisi) bir PDF/A arşivleme profili altındaki bir çoklu ortam Screen ek açıklaması veya Rendition eylemidir (ISO 32000-2:2020 §12.5.6.18 / §13.2) — dosya veraPDF doğrulamasında başarısız olacağından motor baştan reddeder.
• Bağlam. getContext(), conformance_mode (bildirilen kip, örneğin pdfa4) ve feature (reddedilen özellik, örneğin Screen annotation) döndürür. Her ikisi de genel salt okunur özelliktir. Neden, istisna iletisidir.
• Çözüm. Geliştirici eylemi: arşivleme çıktısı için çoklu ortam çağrısını bırakın ya da arşiv dışı bir uygunluk profilini hedefleyin (varsayılan ConformanceMode::Plain).

PdfRViolationException

• Ne zaman fırlatılır. Bir PDF/R-1 (ISO 23504-1:2020) uygunluk değişmezi, ister değer-nesnesi oluşturumunda (PdfRStrip, PdfRPage, PdfRDocument profilleri) ister doğrulayıcı zamanında (PdfRValidator) ihlal edildiğinde. Denetim tüketicilerinin bulguları serbest metni ayrıştırmadan doğru §6 alt hükmüne yönlendirebilmesi için hatalı normatif hükmü ve tek satırlık bir ihlal açıklamasını yakalar.
• Bağlam. getContext(), standard (her zaman ISO 23504-1:2020), clause (hüküm yolu, örneğin 6.6.1) ve violation döndürür. Türlü erişimciler: getClause(), getViolation().
• Çözüm. Geliştirici eylemi: reddedilen girdiyi düzeltin ya da belgeyi, alıntılanan hükme uyacak şekilde yeniden oluşturun.

Barkod üretimi

BarcodeException

• Ne zaman fırlatılır. Desteklenen tüm sembolojilerde (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) geçersiz veri veya kodlama hataları nedeniyle barkod üretimi başarısız olduğunda ve görüntü oluşturma sırasında GD oluşturma hatalarında. Barkod değeri iletide ve bağlamda 128 bayta alıntı-üst sınırlanır — fazla uzun veya ikili yükler, bir günlüğe bütün olarak kopyalanamasınlar diye bir ... (<N> bytes, truncated) işaretçisiyle kesilmiş olarak saklanır.
• Bağlam. getContext(), barcode_type (semboloji, örneğin QRCODE, EAN13, CODE128) ve value (kesilmiş değer) döndürür. Türlü erişimciler: getBarcodeType(), getValue().
• Çözüm. Geliştirici eylemi: barkod verisini veya semboloji seçimini düzeltin.

BarcodeEncoderNotFoundException

• Ne zaman fırlatılır. BarcodeEncoderRegistry içinden, istenen kodlayıcı türü bilinmediğinde veya yetenek geçidi kapalı olduğunda. Ayrıca PSR-11 Psr\Container\NotFoundExceptionInterface arayüzünü uygular; bu nedenle kayıt, standartlara uygun bir konteynerdir. İleti, sembolojiyi ve nedeni adlandırır.
• Bağlam. getContext() yöntemini geçersiz kılmaz, bu nedenle boş bir dizi döndürür. type ve reason, getType() ve getReason() erişimcileri üzerinden ve iletide kullanılabilir.
• Çözüm. Geliştirici eylemi: kodlayıcıyı kaydedin ya da onu sağlayan paketi yükleyin (örneğin Micro QR / DotCode / HanXin / JabCode için nextpdf/pro).

Kriptografi, şifreleme ve imzalar

EncryptionException

• Ne zaman fırlatılır. PDF şifreleme veya şifre çözme başarısız olduğunda: AES-256-CBC şifreleme/çözme hataları, OpenSSL hataları, geçersiz IV boyutları, karma-hesaplama hataları ve UE/OE değer-hesaplama hataları. Genellikle eksik veya yanlış yapılandırılmış bir OpenSSL uzantısı, geçersiz anahtar materyali ya da bozuk şifrelenmiş veri. İleti, işlemi ve algoritmayı adlandırır.
• Bağlam. getContext(), algorithm (örneğin AES-256-CBC) ve operation (örneğin encrypt, decrypt, key_derivation) döndürür. Türlü erişimciler: getAlgorithm(), getOperation().
• Çözüm. Altyapı eylemi: OpenSSL’in mevcut ve doğru yapılandırılmış olduğundan emin olun. Şifreleme ve izinler sayfasına bakın.

UnsupportedAlgorithmException

• Ne zaman fırlatılır. Bir kriptografik algoritma geçerli çalışma zamanında yürütülemediğinde: zorunlu bir PHP uzantısı yok, temel kitaplık ilkeli içermiyor, paketlenmiş hash uzantısı bir SHAKE/XOF çeşidini sentezleyemiyor ya da algoritma SignatureAlgorithmRegistry içinde kayıtlı değil. Motor, sessizce daha zayıf bir ilkele düşmemelidir; bu nedenle bunun yerine bunu yüzeye çıkarır. RegulatoryProfile::FIPS seçildiğinde ancak FIPS-doğrulanmış bir OpenSSL sağlayıcısı doğrulanamadığında, statik fabrika nonFipsHostUnderFipsProfile() bunu (algoritma tanımlayıcısı regulatory-profile:fips ile) fırlatır (hem FIPS_ABSENT hem de INDETERMINATE güvenli biçimde başarısız olur).
• Bağlam. getContext(), algorithm (ad veya OID, örneğin shake256, Ed25519, AES-256-GCM) ve reason (operatör tarafından eyleme dönük) döndürür. Türlü erişimciler: getAlgorithm(), getReason().
• Çözüm. Operatör eylemi: eksik uzantıyı yükleyin veya çalışma zamanını yükseltin; FIPS geçidi için FIPS-doğrulanmış bir OpenSSL yapısı yükleyin ya da NEXTPDF_FIPS_MODE değerini açıkça ayarlayın. Geliştirici eylemi: SignatureAlgorithmRegistry::register() aracılığıyla özel bir algoritma tanımlayıcısı kaydedin.

SignatureException

• Ne zaman fırlatılır. Bir dijital imza işlemi başarısız olduğunda: sertifika ve özel anahtar işleme (PKCS#12 ayrıştırma, PEM/DER kod çözme, X.509 doğrulama), PKCS#7/CMS oluşturma, ECDSA imza biçimi, kapsayıcı-boyutu ihlalleri, DER kodlama ve PAdES düzenlemesi. TSA’ya özgü hatalar bunun yerine daha özel TsaException tarafından bildirilir. Konumsal yapıcı yerine türlü adlandırılmış fabrikaları tercih edin; her biri kök nedeni ileti kuyruğuna bağlar. Örnekler: ltvCapabilityMissing() (B-LT/B-LTA için nextpdf/enterprise gerekir), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), Ed25519 ailesi (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing() ve OCSP-durumu çifti nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Bu fabrikalar, sessizce düşürülmüş bir imza yaymak yerine güvenli biçimde başarısız olur.
• Bağlam. getContext(), cert_info (konu DN’si veya parmak izi ya da boş), signature_level (denenen PAdES seviyesi, örneğin B-B, B-T, B-LT, B-LTA) ve detail (eyleme dönük tanılama, eski konumsal yapıcı için boş) döndürür. Türlü erişimciler: getCertInfo(), getSignatureLevel(), getDetail().
• Çözüm. Geliştirici eylemi: sertifika/anahtar yapılandırmasını düzeltin. Yetenek-eksik fabrikalar için adlandırılmış paketi yükleyin. Fabrika başına belirti-ve-çözüm girişleri için İmza ve zaman damgası hataları sayfasına bakın.

BlackPointCompensationUnsupportedException

• Ne zaman fırlatılır. NullBlackPointCompensationTransform::transform() içinden, bir çağıran null bağdaştırıcıdan Default olmayan bir ISO 18619 siyah-nokta telafisi dönüşümü uygulamasını istediğinde. Null bağdaştırıcı, renk yönetimi arka ucu olmayan ortamlar için güvenli yedektir; gerçek bir renk yönetimi modülü olmadan dönüştürülmüş bir örnek üretmek, dönüşümü sessizce yanlış bildirir. Buradaki çoğu girişin aksine, bu NextPdfException değil, doğrudan \RuntimeException sınıfını genişletir; bu nedenle mevcut catch (\RuntimeException) yolları çalışmaya devam eder.
• Bağlam. getContext() yok; düz bir \RuntimeException sınıfıdır. Ayrıntı iletidedir.
• Çözüm. Geliştirici eylemi: gerçek bir BlackPointCompensationTransform (LittleCMS, Argyll, saf-PHP) kaydedin ya da /UseBlackPtComp değerini BlackPointCompensation::Default ile sınırlayın.

Belge derleme ve erişilebilirlik

UnsupportedSourceDocumentException

• Ne zaman fırlatılır. Bir kaynak belge, bir birleştirme/bölme çıktısına güvenli biçimde kopyalanamadığında ve işlem, bozuk veya güvenlik-açısından-tehlikeli bir sonuç yaymak yerine güvenli biçimde başarısız olduğunda. Adlandırılmış fabrikaları kullanın: encrypted() (ISO 32000-2 §7.6 — içerik anahtar olmadan kopyalanamaz), signed() (§12.8 — sayfaları kopyalamak imza bayt aralığını geçersiz kılar), unsupportedStreamFilter() (nesne-grafiği okuyucusunun gidiş-dönüş yapamadığı bir filtre), multipleInteractiveForms() (belgelenmiş bir sınırlama: birden fazla kaynak boş olmayan bir /AcroForm taşır, §12.7) ve splitWithInteractiveForm() (belgelenmiş bir sınırlama: form taşıyan bir kaynağı sayfa-altkümeleme, pencere öğelerini yetim bırakır). NextPdfException değil, doğrudan \RuntimeException sınıfını genişletir.
• Bağlam. getContext() yok; düz bir \RuntimeException sınıfıdır. Neden ve etkilenen nesne numarası iletide adlandırılır.
• Çözüm. Geliştirici eylemi: kaynağı önce şifre çözün veya anahtarı sağlayın; imzalı kaynaklar için bunun yerine birleştirdikten sonra imzalayın; çok-formlu birleştirmeler için bir kaynak hariç tümünün form alanlarını düzleştirin veya kaldırın; form taşıyan bölmeler için bölmeden önce formu düzleştirin.

InvalidBcp47TagException

• Ne zaman fırlatılır. Bcp47Validator::validate() içinden, bir aday dil etiketi RFC 5646 §2.1 ABNF altında hatalı biçimlendiğinde ya da derlenmiş kayıt araması başarısız olduğunda. BCP-47 / ISO 14289-2:2024 §8.4.4 etki alanına özgüdür ve InvalidConfigException türünden ayrıdır; böylece erişilebilirlik bağlantısının alt akışındaki çağıranlar dar bir türü yakalayabilir. Yüklem çifti Bcp47Validator::isWellFormed() / isValid(), istisnalar yerine dallanmayı tercih eden çağıranlar için geriye dönük uyumlu dönüş-değeri yüzeyi olmaya devam eder.
• Bağlam. getContext(), tag (sağlandığı şekliyle tam aday) ve reason (kararlı, makinede okunabilir bir reddetme kodu, örneğin empty-string, well-formed-shape, unregistered-primary, duplicate-variant) döndürür. Türlü erişimciler: getTag(), getReason().
• Çözüm. Geliştirici eylemi: dil etiketini iyi-biçimli, kayıtlı bir BCP-47 etiketine düzeltin. Yazı tipleri ve etiketleme sayfasına bakın.

FormFieldAccessibilityException

• Ne zaman fırlatılır. Etkileşimli bir form alanı, katı erişilebilir-alan-adı uygulaması etkinken bir PDF/UA belgesi üretirken sentetik (yazar tarafından sağlanmamış) bir erişilebilir ada dayanacağında. Varsayılan PDF/UA çıktısı, bir alanın asla adsız kalmaması için pencere öğesi /Contents içine sentetik bir yedek ad yayar; katı kip ise bunun yerine ekran-okuyucu kullanıcılarının gerçek bir açıklama alması için yazarın anlamlı bir ad (bir araç ipucu ya da eylemsiz bir basma düğmesi için bir başlık) sağlamasını gerektirir (ISO 14289-2:2024 §8.10.2).
• Bağlam. getContext() yöntemini geçersiz kılmaz, bu nedenle boş bir dizi döndürür. $fieldId genel bir salt okunur özelliktir; neden iletidedir.
• Çözüm. Geliştirici eylemi: katı bir PDF/UA belgesi üretmeden önce adlandırılmış alan için bir araç ipucu / erişilebilir ad sağlayın ya da katı kipi devre dışı bırakın. PDF/A ve PDF/UA doğrulama sayfasına bakın.

VendorExtensionRegistryConflictException

• Ne zaman fırlatılır. VendorExtensionRegistry::register() içinden, bir çağıran, bilinen bir PDF geliştirici-uzantısı satıcı önekini (ISO 32000-2:2020 §7.12.1), önceden kayıtlı üst veriyle çelişen bir açıklamayla yeniden kaydettiğinde. Tanımlayıcılar yalnızca-ekle ve çakışma-algılamalıdır; türlü istisna, çağıranların bu belirli sınıfı yakalayabilmesi için genel bir \RuntimeException türünün yerini aldı.
• Bağlam. getContext(), prefix, existing_description ve attempted_description döndürür. Türlü erişimciler: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Çözüm. Geliştirici eylemi: öneki mevcut açıklamayla kaydedin ya da farklı bir önek kullanın; kayıtlı üst veriyi üzerine yazmayın.

Denetim dışa aktarımı

AuditExportException

• Ne zaman fırlatılır. Çalışma zamanında denetim-dışa-aktarım paketi derlemesi, izlenebilirlik-matrisi üretimi veya şema yansıtması başarısız olduğunda. claims.json / manifest.json dosyalarına karşı G/Ç, kanonik paketin JSON kodlama/çözme işlemi ve AuditExporter::projectToV1() geriye dönük uyumluluk yolundaki şema-sürümü uyumsuzluğunu kapsar. İleti, aşamayı, bilindiğinde yapıyı ve ayrıntıyı adlandırır.
• Bağlam. getContext(), stage (örneğin read_claims, encode_bundle, project_v1), detail ve artefact (hataya yol açan yol veya schema_version) döndürür. Türlü erişimciler: getStage(), getDetail(), getArtefact().
• Çözüm. Uygunluk / DevOps eylemi: girdi yapısı yollarını doğrulayın, claims.json dosyasını temiz bir çalıştırmadan yeniden üretin ya da dışa aktarmayı yeniden denemeden önce manifesti yeniden oluşturun.

İhlal değer nesneleri

Bunlar istisna değildir. Bireysel bir ihlali tanımlamak için motorun döndürdüğü değişmez değer nesneleridir; getContext() taşımazlar.

ComplianceViolation

• Nedir. Harici bir doğrulayıcı (veraPDF veya eşdeğeri) tarafından bildirilen bir kural hatasını, ISO hüküm başvurusu ve PDF yapısı içindeki konum dahil olmak üzere temsil eden final readonly bir değer nesnesi.
• Alanlar. Genel salt okunur özellikler: ruleId (doğrulayıcı kural tanımlayıcısı, örneğin 6.1.2-1), clause (ISO hüküm başvurusu, örneğin ISO 19005-1:2005, 6.1.2), severity (örneğin error, warning), location (PDF yapısı içindeki nesne yolu) ve message (insan tarafından okunabilir açıklama).
• Kullanım. Bir uygunluk doğrulayıcısının döndürdüğü koleksiyonu inceleyin; her girişi severity ve clause değerine göre yönlendirin veya görüntüleyin. PDF/A ve PDF/UA doğrulama sayfasına bakın.

RuleViolation

• Nedir. Bir Schematron / EN 16931 iş-kuralı ihlalini temsil eden, SchematronRunnerInterface::runRules() tarafından döndürülen ve ValidationResult::$ruleViolations içinde toplanan final readonly bir değer nesnesi. Kararlılık deneyseldir.
• Alanlar. Genel salt okunur özellikler: ruleId (EN 16931 tanımlayıcısı, örneğin BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n} ya da katmana özgü bir paket), severity (bir RuleSeverity enum’ı), message (kural metni, en-GB), xpath (gömülü XML’e XPath, belge geneli kurallar için null) ve semanticPath (BG-22.BT-106 gibi nokta-gösterimli BG/BT yolu, yapısal ihlaller için null).
• Kullanım. Doğrulama sonucundaki koleksiyonu inceleyin; her girişi severity, ruleId ve konumlandırıcıya göre yönlendirin veya görüntüleyin.

Ayrıca bakınız

• Hata başvurusu dizini
• Bilgi tabanı dizini
• İmza ve zaman damgası hataları
• Şifreleme ve izinler
• Yazı tipleri ve etiketleme
• PDF/A ve PDF/UA doğrulama