Inspect: PDF incelemesi ve ön denetim

Bir bakışta

Inspect modülü, mevcut bir Portable Document Format (PDF) dosyasını okur ve içeriğine ilişkin karmaşıklık puanı, yazı tipi ve görüntü denetimleri, uygunluk ipuçları ve risk bayrakları raporlar. Bir ön denetim politikası bu raporu pass/fail kararına dönüştürür; böylece belge bir işlem hattına alınmadan önce denetlenebilir.

Kararlılık: deneysel. İnceleme yetenekleri hâlâ gelişmektedir. Şu öğeler alt sürümler arasında değişebilir: InspectResult şekli, risk bayrağı kümesi ve isteğe bağlı hızlandırılmış inceleme yolu. Bunu tanılama ve denetim için kullanın; sonuç şekline henüz uzun ömürlü sözleşmeler için güvenmeyin.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Giriş noktası olarak Inspector sınıfını kullanın. InspectorInterface arayüzünü uygular ve tek bir yöntem sunar: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. Salt okunurdur: PDF’yi ayrıştırır ve niteler; belgeyi değiştirmez.

InspectResult, yapılandırılmış rapordur. Karmaşıklık puanını, denetimleri, ipuçlarını ve bir RiskFlag kümesini içerir. Serbest metni ayrıştırmak yerine belirli bir riske göre dallanmak için hasRisks() / hasRisk(RiskFlag $flag) yöntemlerini kullanın. ComplexityScore, sayısal bir puan ve bir category() aralığı sunar. FontAuditEntry ve ImageAuditEntry, gömülü kaynakları açıklar. ComplianceHint, olası uygunluk sorunlarını işaretler. InspectIssue, belirli bir bulguyu kaydeder. InspectDepth inceleme derinliğini belirler ve toSpectrumDepth(), Spectrum yardımcı bileşeni mevcut olduğunda bu derinliği hızlandırılmış yola eşler. İnceleme, yardımcı bileşen olmadan da çalışır. Yardımcı bileşen yalnızca performansı değiştirir, sözleşmeyi değiştirmez. InspectResponseParser, ham bir yanıttan (örneğin, hızlandırılmış yolun yanıtından) isteğe bağlı bir izleme kimliğiyle bir InspectResult oluşturur.

PreflightPolicy, karar katmanıdır. evaluate(InspectResult $result), yapılandırılmış bir politikayı bir sonuca uygular ve politika sonucunu döndürür. Modülün tamamı @since 2.2.0 sürümündendir.

API yüzeyi

Tür	Temel üyeler	Rol
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Salt okunur PDF inceleyici (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), score/audit erişimcileri	Yapılandırılmış inceleme raporu (@since 2.2.0)
ComplexityScore	category()	Sayısal karmaşıklık puanı + aralık (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	kaynak erişimcileri	Gömülü kaynak denetimleri (@since 2.2.0)
ComplianceHint / InspectIssue	bulgu erişimcileri	Uygunluk ipuçları ve bulgular (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	İnceleme derinliği → hızlandırılmış yol (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Geçti/kaldı ön denetim kararı (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Ham bir yanıttan bir sonuç oluşturur (@since 2.2.0)

Tam PHPDoc tablosu için composer docs:generate-api-php -- --module=Inspect komutunu çalıştırın.

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

Kaynak: examples/34-inspect-layout-boxes.php, sayfa geometrisinin nasıl okunacağını gösterir. Bu örnek, herhangi bir PDF’nin risk profilini inceler:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Inspect\Inspector;

$result = (new Inspector())->inspect(file_get_contents('/srv/in/incoming.pdf'));

if ($result->hasRisks()) {
    echo "Complexity: {$result->complexityScore()->category()}; risks present.\n";
}

Kod örneği — üretim

Gelen bir PDF’yi bir ön denetim politikasından geçirerek denetleyin ve herhangi bir risk varsa reddedin.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Inspect\Inspector;
use NextPDF\Inspect\PreflightPolicy;
use Psr\Log\LoggerInterface;

final readonly class IngestPreflight
{
    public function __construct(
        private Inspector $inspector,
        private PreflightPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    public function accept(string $pdfData): bool
    {
        $result = $this->inspector->inspect($pdfData);
        $verdict = $this->policy->evaluate($result);

        if ($verdict !== []) {
            $this->logger->warning('PDF rejected at preflight.', ['findings' => $verdict]);

            return false;
        }

        return true;
    }
}

Sınır durumları ve dikkat edilmesi gerekenler

• inspect() salt okunurdur. Girdiyi asla değiştirmez veya onarmaz; “düzeltilmiş” bir belge döndürmesini beklemeyin.
• hasRisk(RiskFlag) kesin denetimdir. Yalnızca hasRisks() üzerinden dallanmak her riski aynı şekilde ele almak anlamına gelir; genellikle belirli bir bayrağı kontrol etmek istersiniz.
• InspectDepth maliyeti denetler. Büyük bir PDF’nin derin incelemesi önemli ölçüde daha yavaştır; ihtiyacınızı karşılayan en sığ derinliği kullanın.
• Spectrum ile hızlandırılmış yol performansı değiştirir, sonuç sözleşmesini değiştirmez. Hızlandırılmış yanıt şekline değil, InspectResult üzerine kod yazın.
• PreflightPolicy::evaluate() bulguları döndürür; özel durum (exception) fırlatmaz. Boş sonuç, geçiş anlamına gelir; dönüş değerine göre işlem yapın.

Performans

İnceleme maliyeti, belge boyutu ve seçilen InspectDepth ile orantılı olarak artar. Sığ inceleme hızlıdır; büyük bir PDF’nin derin denetimi bütçeye yaklaşabilir. Spectrum yolu, mevcut olduğunda ağır ayrıştırma işini devralır. 1500 ms duvar saati / 64 MB tepe değeri olan performance_budget, referans iş yükünü tanımlar. Yeniden üretilebilirlik profili structural’dır: sonuç bir izleme kimliği ve zamanlama bilgisi içerebilir. İki çalıştırma bu alanlarda farklılık gösterebilir; aynı girdi için bulgular kararlı kalır.

Güvenlik notları

Inspector::inspect() güvenilmeyen PDF baytlarını ayrıştırır; amacı budur, bu yüzden girdinin kötü niyetli olabileceğini varsayın. Kullanıcı tarafından sağlanan belgeler için incelemeyi kısıtlı bir iş sürecinde çalıştırın ve girdi boyutunu önceden sınırlandırın. Kasıtlı olarak karmaşık bir PDF, derinlikten bağımsız olarak bir hizmet reddi (denial-of-service) vektörüdür. Sonuç belgeyi açıklar ancak onu temizlemez; “düşük risk” kararı buluşsal bir değerlendirmedir, güvenlik garantisi değildir. Çıkarılan dizeleri ve meta verileri güvenilmeyen olarak kabul edin. Motor tehdit modeli için /modules/core/security/ sayfasına bakın.

Uygunluk

Bu modül uygunluk ipuçları raporlar; nihai uygunluk kararını vermez. ComplianceHint olası sorunları buluşsal olarak işaretler. PDF/A, PDF/UA ve International Organization for Standardization (ISO) 32000-2 için nihai uygunluk kararı, /modules/core/cli/ tarafından yönlendirilen referans doğrulayıcılardan ve /modules/core/conformance/ sayfasında açıklanan oracle ve golden paketlerinden gelir. Temiz bir Inspect sonucunu uygunluk sertifikası olarak kabul etmeyin.

Ayrıca bakınız

• CLI modülü — nihai harici doğrulayıcıları yönlendirir.
• Uygunluk genel bakışı — nihai karar ve golden paketleri.
• Accelerator modülü — isteğe bağlı hızlandırılmış inceleme yolu.
• Motor güvenlik modeli