Inspect: introspeksi dan preflight PDF

Sekilas

Modul Inspect membaca berkas Portable Document Format (PDF) yang sudah ada dan melaporkan isinya: skor kompleksitas, audit fon dan gambar, petunjuk konformansi, serta flag risiko. Kebijakan preflight mengubah laporan tersebut menjadi keputusan pass/fail, sehingga Anda dapat menyaring dokumen sebelum dokumen masuk ke pipeline.

Stabilitas: eksperimental. Introspeksi masih terus berkembang. Bentuk InspectResult, kumpulan flag risiko, dan jalur inspeksi terakselerasi yang opsional dapat berubah di antara versi minor. Gunakan untuk diagnostik dan penyaringan; untuk saat ini, jangan jadikan bentuk hasilnya sebagai kontrak jangka panjang.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Gunakan Inspector sebagai titik masuk. Kelas ini mengimplementasikan InspectorInterface dan menyediakan satu metode: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. Sifatnya hanya-baca: ia mengurai PDF dan mengidentifikasi karakteristiknya; ia tidak memodifikasi dokumen.

InspectResult adalah laporan terstruktur tersebut. Laporan ini mencakup skor kompleksitas, audit, petunjuk, dan sekumpulan RiskFlag. Gunakan hasRisks() / hasRisk(RiskFlag $flag) untuk bercabang pada risiko tertentu, bukan mengurai teks bebas. ComplexityScore menyediakan skor numerik dan satu pita kategori melalui category(). FontAuditEntry dan ImageAuditEntry mendeskripsikan sumber daya yang tertanam. ComplianceHint menandai kemungkinan masalah konformansi. InspectIssue mencatat satu temuan spesifik. InspectDepth mengatur kedalaman inspeksi, dan toSpectrumDepth() memetakan kedalaman tersebut ke jalur terakselerasi saat sidecar Spectrum tersedia. Inspeksi tetap berjalan tanpa sidecar. Sidecar hanya mengubah performa, bukan kontraknya. InspectResponseParser membangun InspectResult dari respons mentah (misalnya respons jalur terakselerasi) dengan ID jejak opsional.

PreflightPolicy adalah lapisan keputusan. evaluate(InspectResult $result) menerapkan kebijakan yang dikonfigurasi pada sebuah hasil dan mengembalikan hasil kebijakannya. Seluruh modul ini memiliki penanda @since 2.2.0.

Permukaan API

Tipe	Anggota utama	Peran
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Inspektor PDF hanya-baca (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), pengakses skor/audit	Laporan inspeksi terstruktur (@since 2.2.0)
ComplexityScore	category()	Skor kompleksitas numerik + pita kategori (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	pengakses sumber daya	Audit sumber daya tertanam (@since 2.2.0)
ComplianceHint / InspectIssue	pengakses temuan	Petunjuk dan temuan konformansi (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	Kedalaman inspeksi → jalur terakselerasi (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Keputusan preflight lolos/gagal (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Membangun hasil dari respons mentah (@since 2.2.0)

Jalankan composer docs:generate-api-php -- --module=Inspect untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Sumber: examples/34-inspect-layout-boxes.php menunjukkan cara membaca geometri halaman. Contoh ini menginspeksi profil risiko dari PDF apa pun:

<?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";
}

Contoh kode — Produksi

Saring PDF yang masuk dengan kebijakan preflight dan tolak jika ada risiko apa pun.

<?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;
    }
}

Kasus tepi & jebakan

• inspect() bersifat hanya-baca. Ia tidak pernah memodifikasi atau memperbaiki masukan; jangan berharap ia mengembalikan dokumen yang sudah “diperbaiki”.
• hasRisk(RiskFlag) adalah pemeriksaan yang presisi. Bercabang hanya berdasarkan hasRisks() memperlakukan setiap risiko secara identik; biasanya Anda membutuhkan flag tertentu.
• InspectDepth mengendalikan biaya. Inspeksi mendalam pada PDF besar jauh lebih lambat; gunakan kedalaman paling dangkal yang cukup untuk menjawab pertanyaan Anda.
• Jalur yang dipercepat Spectrum mengubah performa, bukan kontrak hasilnya. Tulis kode dengan mengacu pada InspectResult, bukan pada bentuk respons terakselerasi.
• PreflightPolicy::evaluate() mengembalikan temuan; metode ini tidak melempar eksepsi. Hasil kosong berarti lolos; bertindaklah berdasarkan nilai kembalian.

Performa

Biaya inspeksi naik seiring ukuran dokumen dan InspectDepth yang dipilih. Inspeksi dangkal berlangsung cepat; audit mendalam pada PDF besar dapat mendekati budget. Jalur Spectrum memindahkan penguraian berat saat tersedia. performance_budget sebesar 1500 ms wall / 64 MB puncak menggambarkan beban kerja acuan. Profil reproduksibilitasnya adalah structural: suatu hasil dapat menyertakan ID jejak dan waktu. Dua kali eksekusi dapat berbeda pada bidang-bidang tersebut, sementara temuannya tetap stabil untuk masukan yang sama.

Catatan keamanan

Inspector::inspect() mengurai byte PDF yang tidak tepercaya; memang itulah tujuannya, jadi perlakukan masukan sebagai berbahaya. Jalankan inspeksi dalam worker terbatas untuk dokumen yang dipasok pengguna, dan batasi ukuran masukan di hulu. PDF yang sengaja dibuat kompleks adalah vektor denial-of-service tanpa memandang kedalaman. Hasil tersebut mendeskripsikan dokumen tetapi tidak melakukan sanitasi terhadapnya; verdik “risiko rendah” adalah heuristik, bukan jaminan keamanan. Perlakukan string dan metadata yang diekstrak sebagai tidak tepercaya. Lihat model ancaman engine di /modules/core/security/.

Konformansi

Modul ini melaporkan petunjuk konformansi; ia tidak memberikan verdik konformansi yang otoritatif. ComplianceHint menandai kemungkinan masalah secara heuristik. Untuk PDF/A, PDF/UA, dan International Organization for Standardization (ISO) 32000-2, verdik konformansi yang otoritatif berasal dari validator referensi yang dijalankan melalui /modules/core/cli/ serta suite oracle dan golden yang dijelaskan di /modules/core/conformance/. Jangan perlakukan hasil Inspect yang bersih sebagai sertifikasi konformansi.

Lihat juga

• Modul Cli — menjalankan validator eksternal yang otoritatif.
• Tinjauan konformansi — verdik otoritatif dan suite golden.
• Modul Accelerator — jalur inspeksi terakselerasi yang opsional.
• Model keamanan engine