Çalışma zamanı ve destek hataları

Kapsam

Bu girişler, çalışma zamanı destek katmanı tarafından fırlatılan istisnaları belgeler: düşürme ilkesi, cURL-destekli HTTP taşıması, dayanıklılık devre kesicisi, Güvenlik Bilgileri ve Olay Yönetimi (SIEM) yayıcısı, oluşturma manifesti, PDF incelemesi ve kaos-mühendisliği alt sistemi.

Her NextPDF istisnası, ContextAwareExceptionInterface arayüzünü uygulayan ve yapılandırılmış tanılama günlüklemesi için getContext(): array yöntemini sunan NextPdfException sınıfını genişletir. Bir alt sınıf, o diziyi yalnızca getContext() yöntemini geçersiz kıldığında doldurur; temel sınıf boş bir dizi döndürür. Bu sayfadaki üç istisna (DegradedException, CircuitBreakerOpenException ve InspectException), doğrudan PHP’nin RuntimeException sınıfını genişletir ve verilerini getContext() yerine genel readonly özellikler üzerinden sunar. Aşağıdaki her giriş, sınıfın taşıdığı tam özellikleri veya bağlam anahtarlarını kaynaktan alınmış olarak adlandırır.

Düşürme ilkesi

DegradedException

• Ne zaman fırlatılır. Oluşturma işlem hattı, etkin düşürme ilkesini ihlal eden düşürülmüş bir yetenekle karşılaşır. DegradationPolicy::Strict altında, herhangi bir yüksek-etkili düşürme (ComplianceRisk, SemanticLoss veya Blocking) onu fırlatır; DegradationPolicy::Balanced altında yalnızca bir Blocking etkisi onu fırlatır.
• Sınıf. Doğrudan RuntimeException sınıfını genişletir (NextPdfException değil); bu nedenle bir getContext() taşımaz.
• Taşınan veri. İki genel readonly özellik: $capability (reddetmeyi tetikleyen Capability değer nesnesi; id, status, reason, fallbackTarget ve impact dahil) ve $policy (reddetme anında etkin olan DegradationPolicy). İleti, Feature "<id>" is <status>: <reason> (policy: <policy>) biçimindedir.
• Çözüm. Eksik özelliği ve nedenini tanımlamak için $capability değerini inceleyin. Ya yeteneğin gerektirdiği bileşeni yükleyin, daha düşük-etkili bir yapılandırmayı kabul edin ya da düşürme kullanım durumu için kabul edilebilir olduğunda ilkeyi Strict kipinden Balanced kipine gevşetin. Kullanıcıya dönük iletileri yönlendirmek için $capability->isAvailable() / isDegraded() yöntemlerini çağırın.

HTTP taşıması

Bu üç istisna, cURL-destekli PSR-18 istemcisinden ve güvenlik-bilinçli dekoratöründen kaynaklanır. İlk ikisi NextPdfException sınıfını genişletir ancak getContext() yöntemini geçersiz kılmaz; bu nedenle getContext() çıktıları boş bir dizi döndürür; tanılama verisine PSR-18 getRequest() erişimcisi ve zincirlenmiş önceki fırlatılabilir nesne üzerinden ulaşılır.

CurlNetworkException

• Ne zaman fırlatılır. HTTP isteği, ağ-düzeyi bir hata nedeniyle tamamlanamaz: Etki Alanı Adı Sistemi (DNS) çözümleme hatası, bağlantı zaman aşımı ya da Taşıma Katmanı Güvenliği (TLS) el sıkışma hatası. Ayrıca, güvenlik-bilinçli dekoratörün bir güvenlik reddi (Sunucu Tarafı İstek Sahteciliği reddi, DNS-yeniden bağlama reddi ya da reddedilen bir yönlendirme) için fırlattığı sınıftır.
• Sınıf. PSR-18 Psr\Http\Client\NetworkExceptionInterface arayüzünü uygular.
• Taşınan veri. getRequest(), başarısız olan RequestInterface nesnesini döndürür. Kaynaklanan taşıma hatası, mevcut olduğunda, zincirlenmiş önceki fırlatılabilir nesnedir. getContext() boş bir dizi döndürür (temel varsayılan).
• Çözüm. Bir ağ hatası geçici olabilir — istek bağışıksa (idempotent) geri çekilmeli olarak yeniden deneyin. Bir güvenlik reddi geçici değildir ve güvenli biçimde başarısız olmalıdır: yeniden denemeyin; bunun yerine hedef URL’yi veya SSRF ilkesini düzeltin. İkisini ayırt etmek için iletiyi ve önceki fırlatılabilir nesneyi okuyun.

CurlRequestException

• Ne zaman fırlatılır. Hatalı biçimlendiği için isteğin kendisi gönderilemez; örneğin geçersiz bir URL ya da herhangi bir ağ çağrısından önce SSRF doğrulamasında başarısız olan bir istek.
• Sınıf. PSR-18 Psr\Http\Client\RequestExceptionInterface arayüzünü uygular.
• Taşınan veri. getRequest(), hatalı RequestInterface nesnesini döndürür; temel neden, mevcut olduğunda, zincirlenmiş önceki fırlatılabilir nesnedir. getContext() boş bir dizi döndürür.
• Çözüm. Bu, geçici bir hata değil, bir çağıran-girdisi veya ilke kusurudur. Değiştirmeden yeniden denemeyin. İstek URL’sini, başlıkları veya gövdeyi düzeltin ya da hedef meşru biçimde izinliyse SSRF izin-listesini ayarlayın, sonra isteği yeniden gönderin.

TransientHttpException

• Ne zaman fırlatılır. Dahili olarak, SecurityAwareHttpClient içinde, gerçekten geçici bir iç-taşıma hatasını (iç PSR-18 istemcisinin fırlattığı DNS, bağlantı ya da zaman aşımı) sınırlı yeniden-deneme bütçesine uygun olarak işaretlemek için. Dekoratörün yeniden-deneme döngüsünün tanıdığı tek yeniden-deneme-uygun sınıftır; sarılmamış bir istisna (dekoratörün fırlattığı bir güvenlik reddi) ölümcül olarak ele alınır.
• Sınıf. PSR-18 Psr\Http\Client\NetworkExceptionInterface arayüzünü uygular. @internal olarak işaretlenmiştir — tamamen SecurityAwareHttpClient içinde oluşturulur ve sarması açılır ve asla dekoratörden kaçmaz.
• Taşınan veri. getRequest(), başarısız olan isteği döndürür. Özgün iç-taşıma ClientExceptionInterface, zincirlenmiş önceki fırlatılabilir nesne (getPrevious()) olarak korunur ve yeniden-deneme bütçesi tükendiğinde çağırana aynen yeniden yüzeye çıkarılır; böylece genel PSR-18 sözleşmesi değişmez. getContext() boş bir dizi döndürür.
• Çözüm. Uygulama kodu bu türü doğrudan yakalamaz. Dekoratörün, yeniden-deneme bütçesi harcandıktan sonra döndürdüğü, yeniden yüzeye çıkan iç istisnayı yakalayın ve tekrarlayan geçici hataları bir yukarı-akış kullanılabilirlik sorunu olarak ele alın.

Dayanıklılık

CircuitBreakerOpenException

• Ne zaman fırlatılır. CircuitBreakerState::Open durumundaki bir CircuitBreaker, herhangi bir alt akış çağrısından önce bir çağrıyı hızlı-hata ile reddeder. Çağıranların “uzak hizmete şu anda erişilemiyor” (düşürmeye değer geçici bir taşıma hatası) durumunu “bu çağrı bağlantı havuzunu tüketirdi” (hızlı-hata, ağ denenmedi) durumundan ayırabilmesi için vardır — Açık Anahtar Altyapısı (PKI) istemcileri için gereken toplu hizmet-reddi azaltması.
• Sınıf. Doğrudan RuntimeException sınıfını genişletir; bu nedenle bir getContext() taşımaz.
• Taşınan veri. İki genel readonly özellik: $breakerName (açık kesicinin tanımlayıcısı) ve $secondsUntilHalfOpen (kesici yarı-açığa geçmeden önce kalan yaklaşık soğuma süresi). İleti, Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast. biçimindedir.
• Çözüm. Kesiciyi zorlamayın — yeniden denemeden önce en az $secondsUntilHalfOpen süresi kadar bekleyin ya da işlemi düşürün. Hiçbir ağ çağrısı denenmedi; bu nedenle bu, uzak hizmetin kendisinin başarısız olduğunun kanıtı değildir; bağlantı havuzunu koruyan bir geri-baskıdır.

Gözlemlenebilirlik

SiemEmitterException

• Ne zaman fırlatılır. Bir SIEM olay yayıcısı bir kaydı kalıcılaştıramadığında ya da zincirleyemediğinde. Dosya-sistemi-düzeyi hataları (open, lock, seek, write, fflush, read) ve karma-zinciri bütünlük hatalarını (chain: sıra-dışı dizin, hatalı kuyruk kaydı ya da JSON gidiş-dönüş kayması), karma-zinciri olay günlüğü ve JSON-lines dosya yayıcısı bağdaştırıcıları arasında paylaşılan biçimde yüzeye çıkarır.
• Sınıf. NextPdfException sınıfını genişletir ve getContext() yöntemini geçersiz kılar.
• Bağlam anahtarları. operation (open, lock, seek, write, fflush, read, chain değerlerinden biri), path (hedef günlük yolu) ve detail (bayt sayıları ya da beklenen-karşı-gerçek dizin gibi insan tarafından okunabilir bir ayrıntı). Bunlara getOperation(), getPath() ve getDetail() üzerinden de ulaşılır. İleti, SIEM emitter <operation> failed for <path>: <detail>. biçimindedir.
• Çözüm. Bu, uygulama mantığı tarafından değil, altyapı veya SecOps tarafından eyleme dönüktür. Günlük-birimi bağlamasını, dizin izinlerini, kullanılabilir dosya tanımlayıcılarını ve dosya sistemi sağlığını doğrulayın. Bir chain işlem hatası, denetim günlüğünde bir kurcalama veya bozulma sinyalini gösterir ve sessizce yeniden denenmek değil, araştırılmalıdır.

Oluşturma manifesti

RenderManifestException

• Ne zaman fırlatılır. Bir RenderManifest, yapısal, tür ya da şema-uyumluluğu hatası nedeniyle oluşturulamadığında, serisi çözülemediğinde veya okunamadığında. Manifest, her taşıma (CLI, Laravel kuyruğu, Symfony, SaaS API) tarafından gönderilen sürümlenmiş bir genel sözleşmedir; bu nedenle hatalı veya uyumsuz bir manifest, varsayılanlara zorlanmak yerine doğrudan yüzeye çıkarılır.
• Sınıf. NextPdfException sınıfını genişletir ve getContext() yöntemini geçersiz kılar. Adlandırılmış yapıcılar, SPEC-MANIFEST-* ad alanında kararlı, makinede okunabilir bir kod ayarlar:
  • RenderManifestException::shape() → SPEC-MANIFEST-001 — RenderManifest::fromArray() sırasında biçim veya tür hatası.
  • RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — uyumsuz ana şema sürümü (okunamaz).
  • RenderManifestException::missingField() → SPEC-MANIFEST-003 — oluşturucu sonlandırması sırasında zorunlu bir alan eksik.
  • RenderManifestException::unsupported() → SPEC-MANIFEST-004 — iyi-biçimli bir manifest, geçerli oluşturucunun çözemediği bir girdiye veya şablona başvurur (örneğin bir URI girdisi ya da yalnızca ana bilgisayara özgü bir şablon motoru).
• Bağlam anahtarları. manifest_code (SPEC-MANIFEST-* tanımlayıcısı) ve reason (insan tarafından okunabilir hata açıklaması). Bunlara getManifestCode() ve getReason() üzerinden de ulaşılır. İleti, [<code>] <reason> biçimindedir.
• Çözüm. manifest_code değerine göre dallanın. SPEC-MANIFEST-001 ve SPEC-MANIFEST-003 için manifest yükünü düzeltin (alan türünü düzeltin ya da eksik alanı sağlayın). SPEC-MANIFEST-002 için manifesti desteklenen bir ana şema sürümüne karşı yeniden üretin ya da oluşturucuyu yükseltin. SPEC-MANIFEST-004 için geçerli sürümün çözebileceği bir girdi veya şablon motoru sağlayın.

İnceleme

InspectException

• Ne zaman fırlatılır. PDF incelemesi başarısız olduğunda.
• Sınıf. Doğrudan RuntimeException sınıfını genişletir (NextPdfException değil); bu nedenle bir getContext() taşımaz.
• Taşınan veri. İki genel readonly özellik: $inspectCode (INSPECT-* ad alanında makinede okunabilir bir kod) ve $retryable (çağıranın yeniden denemesi gerekip gerekmediğini gösteren bir boole — örneğin bir inceleme yardımcısı geçici olarak kapalıyken). Kaynaklanan neden, mevcut olduğunda, zincirlenmiş önceki fırlatılabilir nesnedir.
• Çözüm. Belirli hata sınıfı için $inspectCode değerine göre dallanın. $retryable değeri true olduğunda, hata geçici olması beklendiğinden (örneğin bir yardımcı yeniden başlatması) geri çekilmeyle yeniden deneyin; false olduğunda, girdiyi veya yapılandırmayı kusur olarak ele alın ve değiştirmeden yeniden denemeyin.

Kaos mühendisliği

ChaosReportWriteException

• Ne zaman fırlatılır. ChaosScenarioRunner::writeReport(), toplanan kaos-günü raporunu diske kalıcılaştıramadığında. Genel bir çalışma zamanı hatasının etki alanı-türlü yerine geçenidir; böylece çağıranlar, belirli rapor-disk hatasını, senaryo benzetimcilerinin kendi içinde fırlatılan hatalarla (çalıştırıcı bunları ChaosOutcome alanları olarak yakalar) karıştırmadan yakalayabilir.
• Sınıf. NextPdfException sınıfını genişletir ve getContext() yöntemini geçersiz kılar.
• Bağlam anahtarları. output_path (çalıştırıcının yazmaya çalıştığı mutlak yol). Buna getOutputPath() üzerinden de ulaşılır. İleti, ChaosScenarioRunner: failed to write report to "<path>". biçimindedir.
• Çözüm. Bu, senaryoların değil, rapor alıcısının yazma tarafı hatasıdır. Çıktı dizininin var olduğunu ve yazılabilir olduğunu ve disk alanının mevcut olduğunu doğrulayın, sonra rapor yazma işlemini yeniden çalıştırın. Kaos sonuçlarının kendisi etkilenmez.

RetrievalUnavailableException

• Ne zaman fırlatılır. Bir getirme uç noktası (örneğin bir Voyage Getirmeyle Artırılmış Üretim hizmeti) kullanılamadığında ve sistem ya yalnızca-önbellek kipine geri döndüğünde ya da güvenli biçimde başarısız olduğunda.
• Sınıf. NextPdfException sınıfını genişletir ve getContext() yöntemini geçersiz kılar.
• Bağlam anahtarları. mode (hatadan sonraki işletim kipi — sonuçlar yalnızca anlamsal önbellekten sunulduğunda CACHED_ONLY ya da istek hiçbir bayat veri olmadan tamamen reddedildiğinde FAIL_CLOSED) ve endpoint (erişilemez hâle gelen uç nokta). Bunlara getMode() ve getEndpoint() üzerinden de ulaşılır. İleti, Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode. biçimindedir.
• Çözüm. Sistemin nasıl düşürdüğünü öğrenmek için mode değerini okuyun. CACHED_ONLY altında sonuçlar bayat olabilir; uç nokta kurtulduğunda yenileyin. FAIL_CLOSED altında istek tasarım gereği reddedildi ve uç noktaya erişildikten sonra yeniden denenmelidir. Taze getirmeye güvenmeden önce uç nokta bağlanabilirliğini (ağ, kimlik bilgileri, hizmet sağlığı) geri yükleyin.

Ayrıca bakınız

• Hata başvurusu dizini
• Sorun giderme: imzalar ve zaman damgaları
• Sorun giderme: şifreleme ve izinler
• Sorun giderme: yazı tipleri ve etiketleme
• Sorun giderme: PDF/A ve PDF/UA doğrulama