Exception: türlendirilmiş istisna hiyerarşisi

Bir bakışta

NextPDF’in fırlattığı her istisna, tek bir soyut temel sınıf olan NextPdfException sınıfını genişletir; böylece herhangi bir motor hatasını tek bir catch ile işleyebilirsiniz. Her etki alanı istisnası ContextAwareExceptionInterface arabirimini uygular ve mesaj dizesini ayrıştırmaya gerek kalmadan günlük kaydı ve uygulama performansı izleme (APM) için yapılandırılmış tanılama alanları sunar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Hiyerarşi üç katmandan oluşur:

RuntimeException (PHP SPL)
  └── NextPdfException (abstract; implements ContextAwareExceptionInterface)
        ├── InvalidConfigException
        ├── FontNotFoundException
        ├── FontParsingException
        ├── ImageProcessingException
        ├── SignatureException
        ├── EncryptionException
        ├── WriterException
        ├── PageLayoutException
        ├── HtmlParsingException
        ├── CompressionException
        ├── NotImplementedException
        ├── … (23 domain exceptions total)
        └── Strict\StrictModeViolation (abstract)
              ├── Strict\IncompatibleRenderingModeException
              ├── Strict\OracleConformanceFailure
              └── Strict\UnregisteredCssDeviation

NextPdfException, Standart PHP Kitaplığı (SPL) içindeki RuntimeException sınıfını genişletir. RuntimeException yakalamak, NextPDF hatalarını da yakalar. NextPdfException yakalamak, işleyiciyi yalnızca motor hatalarıyla sınırlar. Hedefli kurtarma için bir yaprak sınıfı yakalayın. Strict\ alt ağacı, uygunluk modu ihlallerini soyut StrictModeViolation altında gruplar; bu sınıf da NextPdfException sınıfını genişletir.

Dize kodları değil, bağlam. NextPDF bir hatayı, bir dize hata koduyla değil, PHP türüyle tanımlar. İstisna sınıfları hiçbir NPDF-#### kod sabiti tanımlamaz. Bunun yerine ContextAwareExceptionInterface::getContext(), günlük veya APM yüküne güvenle serileştirilebilen snake_case biçiminde ilkel alanlardan oluşan bir array<string, mixed> döndürür. NextPdfException::getContext() varsayılan olarak [] döndürür. Her etki alanı istisnası, ilgili hataya özgü alanlarla bu yöntemi geçersiz kılar. Örneğin FontNotFoundException::getContext() şu alanları döndürür: font_name, search_paths ve fallback_attempted. WriterException, output_path ve writer_state döndürür. InvalidConfigException, config_key, given_value ve expected_type döndürür. Kararlı NEXTPDF_W_* dize tanımlayıcıları, istisnalara değil, Support modülündeki ölümcül olmayan WarningCode enum’una aittir.

Eyleme geçirilebilirlik. Her etki alanı istisnasının sınıf docblock’u, ona kimin müdahale edebileceğini belirtir: geliştirici, altyapı veya kitaplığı çağıran taraf. InvalidConfigException bir geliştirici hatasıdır; yapılandırmayı düzeltin. FontNotFoundException bir geliştirici veya altyapı hatasıdır; yolu ya da dosya izinlerini doğrulayın. WriterException bir altyapı hatasıdır; diski, izinleri ya da çıkış akışını denetleyin. NotImplementedException bir çağıran taraf hatasıdır; çağrıyı kaldırın ya da adı belirtilen takip işini içeren bir sürüme sabitleyin. Bazı istisnalar, kesin kök nedenler için adlandırılmış kurucular sağlar: SignatureException::ltvCapabilityMissing(), ::tsaRequired() ve benzerleri. Operatörler, genel bir mesaj yerine gerçek nedeni görür.

API yüzeyi

Sembol	Tür	Başlıca üyeler
NextPDF\Contracts\ContextAwareExceptionInterface	arabirim	getContext(): array<string, mixed>
NextPDF\Exception\NextPdfException	soyut sınıf	şunu genişletir: RuntimeException; getContext() (varsayılan [])
NextPDF\Exception\InvalidConfigException	final	getConfigKey(), getGivenValue(), getExpectedType(), getContext()
NextPDF\Exception\FontNotFoundException	final	getFontName(), getSearchPaths(), wasFallbackAttempted(), getContext()
NextPDF\Exception\SignatureException	final	getCertInfo(), getSignatureLevel(), getDetail(), getContext(); adlandırılmış kurucular ltvCapabilityMissing(), tsaRequired(), httpClientMissing(), …
NextPDF\Exception\WriterException	final	getOutputPath(), getWriterState(), getContext()
NextPDF\Exception\PageLayoutException	final	getPageNumber(), getContext()
NextPDF\Exception\NotImplementedException	final	$feature, $followUp
NextPDF\Exception\Strict\StrictModeViolation	soyut	şunu genişletir: NextPdfException
NextPDF\Exception\Strict\IncompatibleRenderingModeException	final	şunu genişletir: StrictModeViolation

Tüm yaprak sınıflar (23): BarcodeEncoderNotFoundException, BarcodeException, CompressionException, ContentStreamBalanceException, CssParserLimitExceededException, CssResolutionBudgetExceededException, EncryptionException, FontNotFoundException, FontParsingException, GraphicsStateBalanceException, HtmlParsingException, ImageProcessingException, InvalidConfigException, LinearizationInvariantException, LinearizationUnimplementedException, MissingShadingResourceException, NotImplementedException, PageLayoutException, PdfRViolationException, SignatureException, TemplateException, UnsupportedAlgorithmException, WriterException.

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

Temel türü yakalayarak herhangi bir motor hatasını yakalayın.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NextPdfException;

try {
    $doc = Document::createStandalone();
    $doc->addPage();
    $doc->setFont('helvetica', '', 12);
    $doc->cell(0, 10, 'Hello');
    $doc->save('out.pdf');
} catch (NextPdfException $e) {
    \error_log($e->getMessage());
}

Çalıştırılabilir examples/15-exception-handling.php örneği bu deseni uygular.

Kod örneği — üretim

Yaprak sınıf düzeyinde kurtarma yapın ve yapılandırılmış bağlamı günlük işlem hattına gönderin.

<?php

declare(strict_types=1);

use NextPDF\Contracts\ContextAwareExceptionInterface;
use NextPDF\Core\Document;
use NextPDF\Exception\FontNotFoundException;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

function render(Document $doc, LoggerInterface $logger): void
{
    try {
        $doc->setFont('Brand-Sans', '', 12);
        $doc->cell(0, 10, 'Invoice');
        $doc->save('invoice.pdf');
    } catch (FontNotFoundException $e) {
        // Targeted recovery: fall back to a built-in font.
        $logger->warning($e->getMessage(), $e->getContext());
        $doc->setFont('helvetica', '', 12);
        $doc->save('invoice.pdf');
    } catch (NextPdfException $e) {
        // Any other engine error: structured context, then rethrow.
        $context = $e instanceof ContextAwareExceptionInterface
            ? $e->getContext()
            : [];
        $logger->error($e->getMessage(), $context);
        throw $e;
    }
}

Uç durumlar ve dikkat edilecek noktalar

• Yakalama sırası önemlidir. Yaprak sınıfları NextPdfException öncesinde sıralayın; baştaki bir catch (NextPdfException) her alt sınıfı yakalar.
• getContext() anahtarları snake_case kullanır; değerler ise iç içe nesne içermeyen ilkel değerler veya ilkel değer listeleridir. Bu yük, JavaScript Object Notation (JSON)‘a serileştirme için güvenlidir.
• Temel NextPdfException::getContext() [] döndürür. Bu yöntemi geçersiz kılmayan bir alt sınıf hiçbir yapılandırılmış alan taşımaz. Bu durumda getMessage() yöntemine başvurun.
• NextPdfException soyuttur; onu doğrudan örnekleyemezsiniz. Somut bir yaprak fırlatın.
• NotImplementedException bilinçli olarak açıkça hata verecek şekilde tasarlanmıştır. Geçici bir hatayı değil, bilerek eksik bırakılmış bir uygulamayı işaret eder. Onu yeniden denemeyin.
• Strict\* ihlalleri, kurtarılabilir bir çalışma zamanı hatasını değil, bir uygunluk modu sözleşme ihlalini gösterir. Bunları yapılandırma veya girdi kusurları olarak değerlendirin.
• Hiçbir dize hata kodu sabiti yoktur. İstisna türüne göre eşleştirin. Makine tüketicileri için getContext() verisini iletin.

Performans

İstisna oluşturma sırasında bir nesne ayrılır ve mesajı oluşturan sprintf çağrısı yapılır: O(1). getContext(), zaten tutulan alanlardan oluşturulan küçük bir ilişkisel dizi döndürür: alan sayısı bakımından O(1). İstisnalar sık çalışan yolda değil, hata yolunda çalışır. Maliyet, başarısız olan işle karşılaştırıldığında ihmal edilebilir. Bu başvuru sayfası için varsayılan performance_budget şudur: wall_ms: 1500, peak_mb: 64.

Güvenlik notları

Bağlam alanları belgeden türetilen ayrıntılar taşıyabilir. FontNotFoundException dosya sistemi arama yollarını, WriterException çıkış yolunu, InvalidConfigException ise verilen değeri içerir. Bağlamı düşük güvenlikli bir günlük havuzuna iletmeden önce alanları temizleyin veya yalnızca izin verilenler listesindeki anahtarları iletin; çünkü yollar ve değerler dağıtım düzenini ya da kullanıcı girdisini açığa çıkarabilir. İstisna mesajları insan tarafından okunabilir ve aynı ayrıntıyı içerebilir. Güvenlik açısından hassas bir bağlamda ham mesajları son kullanıcılara göstermeyin. SignatureException, eksik bir paket ya da bir Zaman Damgası Yetkilisi (TSA) için boş bir Tekdüzen Kaynak Konumlayıcı (URL) gibi somut kök nedeni bilinçli olarak mesaja ekler; böylece operatörler çağrı noktalarını aramadan sorunu önceliklendirebilir. Bu ayrıntı, son kullanıcıya değil, operatöre yöneliktir.

Uygunluk

Bu modül bir motor hata modeli tanımlar ve hiçbir normatif standart atfı taşımaz. Standart ihlalleri için fırlatılan istisnalar (örneğin PdfRViolationException veya Strict\OracleConformanceFailure), kendilerini düzenleyen maddeye burada değil, ihlali algılayan modülde başvurur.

Ayrıca bakınız

• /modules/core/contracts/ — ContextAwareExceptionInterface tanımı
• /modules/core/observability/ — getContext() verisini APM’ye iletme
• /modules/core/config/ — InvalidConfigException, NotImplementedException
• /modules/core/support/ — DegradedException; WarningCode (NEXTPDF_W_*)
• /modules/core/event/ — InvalidConfigException, şu çağrıdan: addListener()

Sözlük: bağlam duyarlı istisna · düşürme ilkesi