Mengurai dan memeriksa PDF untuk mengetahui fakta struktural

Sekilas pandang

Resep ini menggunakan fallback Quick pada inspector Core untuk membaca fakta struktural dari berkas Portable Document Format (PDF). Hasilnya mencakup versi, jumlah halaman, flag enkripsi, flag tanda tangan, flag lampiran, ukuran berkas, dan flag risiko. Quick berjalan sepenuhnya di dalam proses, tanpa sidecar Spectrum dan tanpa akses jaringan. Gunakan untuk triase cepat, bukan sebagai validator.

Instalasi

composer require nextpdf/core:^3

Gambaran konseptual

Sebuah berkas PDF mencatat versinya di header berkas (ISO 32000-2 §7.5.2). Trailer membawa pengenal berkas (/ID) berupa dua byte string (ISO 32000-2 §7.5.5). Ketika tanda tangan ada, kamus tanda tangan menyimpan Cryptographic Message Syntax (CMS) SignedData yang dikodekan dengan Distinguished Encoding Rules (DER) di Contents (ISO 32000-2 §12.8.1). Fallback Quick menggunakan pemindaian terbatas terhadap byte dokumen untuk menyimpulkan versi, memperkirakan jumlah halaman, serta menentukan flag keberadaan enkripsi, tanda tangan, dan lampiran.

Antarmuka API

Buat new Inspector(), lalu panggil ->inspect(string $pdfData, InspectConfig::quick()). Metode ini mengembalikan InspectResult yang berisi $pdfVersion, $pageCount, $isEncrypted, $hasSigned, $hasAttachments, $fileSizeBytes, $riskFlags, dan helper hasRisks().

Contoh kode — Memulai cepat

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\InspectConfig;
use NextPDF\Inspect\Inspector;

$pdf = file_get_contents(__DIR__ . '/document.pdf');
$result = (new Inspector())->inspect($pdf, InspectConfig::quick());

printf(
    "v%s, %d page(s), encrypted=%s, signed=%s\n",
    $result->pdfVersion ?? '?',
    $result->pageCount,
    $result->isEncrypted ? 'yes' : 'no',
    $result->hasSigned ? 'yes' : 'no',
);

Contoh kode — Produksi

Program mandiri ini berjalan di harness cookbook. Program ini mencerminkan examples/39-parse-and-inspect-pdf.php: program membangun PDF kecil dengan beberapa halaman di memori, membaca fakta strukturalnya dengan fallback Quick, lalu merutekannya berdasarkan fakta tersebut, bukan berdasarkan penilaian kepercayaan. Cabang perutean tersebut bersifat ilustratif. Ganti dengan pipeline, antrean verifier, dan karantina Anda sendiri.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Inspect\InspectConfig;
use NextPDF\Inspect\Inspector;

// A self-contained input so the program runs with no external file.
$doc = Document::createStandalone();
$doc->setTitle('Parse-and-inspect demo');
$doc->setAuthor('NextPDF Cookbook');
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Page one of the parse-and-inspect demonstration.', newLine: true);
$doc->addPage();
$doc->cell(0, 10, 'Page two.', newLine: true);
$pdf = $doc->getPdfData();

$result = (new Inspector())->inspect($pdf, InspectConfig::quick());

echo 'PDF version : ' . ($result->pdfVersion ?? 'unknown') . "\n";
echo 'Pages       : ' . $result->pageCount . "\n";
echo 'Encrypted   : ' . ($result->isEncrypted ? 'yes' : 'no') . "\n";
echo 'Signed      : ' . ($result->hasSigned ? 'yes' : 'no') . "\n";
echo 'Attachments : ' . ($result->hasAttachments ? 'yes' : 'no') . "\n";
echo 'File size   : ' . $result->fileSizeBytes . " bytes\n";
echo 'Risk flags  : ' . ($result->hasRisks() ? count($result->riskFlags) : 0) . "\n";

// Route on structural facts, not trust verdicts. Replace these calls with
// your own pipeline / verifier queue / quarantine.
if ($result->isEncrypted) {
    // $pipeline->decryptThenContinue($pdf);
    echo "Route: decrypt-then-continue\n";
} elseif ($result->hasSigned) {
    // $verifierQueue->enqueue($pdf);          // see the signature-inspect recipe
    echo "Route: enqueue for cryptographic verification\n";
} elseif ($result->hasRisks()) {
    // $quarantine->hold($pdf, $result->riskFlags);
    echo "Route: quarantine (risk flags present)\n";
} else {
    // $pipeline->continue($pdf);
    echo "Route: continue (no risks, unsigned, unencrypted)\n";
}

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script under the
// semantic profile; emit the document to the side-channel.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
file_put_contents($out !== false && $out !== '' ? $out : __DIR__ . '/inspected.pdf', $pdf);

Keluaran standar (STDOUT) yang diharapkan (versi dan ukuran bergantung pada build; PDF demo tidak terenkripsi, tidak ditandatangani, dan bebas risiko):

PDF version : <version>
Pages       : 2
Encrypted   : no
Signed      : no
Attachments : no
File size   : <n> bytes
Risk flags  : 0
Route: continue (no risks, unsigned, unencrypted)

Kasus tepi & jebakan

Quick adalah triase, bukan validasi. Quick hanya melaporkan apa yang ada dan tidak ada. Quick tidak memverifikasi tanda tangan, mendekripsi konten, atau menyatakan kesesuaian. Perlakukan hasilnya sebagai masukan untuk perutean.
Jumlah halaman adalah perkiraan. Fallback Quick menghitung penanda objek halaman. Graf objek yang sengaja dibuat cacat dapat membuat hitungan menjadi tidak akurat. Gunakan kedalaman yang didukung Spectrum ketika Anda memerlukan hitungan yang tepat.
Standard/Full memerlukan sidecar. new InspectConfig() (kedalaman Standard) dan InspectConfig::full() memerlukan sidecar Spectrum. Keduanya melempar INSPECT-SIDECAR-001 ketika sidecar tidak tersedia dan tidak beralih ke Quick secara diam-diam.
Masukan kosong. Memberikan string kosong akan melempar exception inspect dengan pesan “PDF data must not be empty”.
Lingkup flag enkripsi. Flag ini mencerminkan entri trailer /Encrypt. Berkas yang ditandai tidak didekripsi oleh inspector.

Performa

Fallback Quick menggunakan pemindaian terbatas, bukan penguraian penuh. Gunakan untuk melakukan perutean awal terhadap berkas masuk dalam volume tinggi sebelum pemrosesan yang lebih berat.

Catatan keamanan

Inspector berjalan di dalam proses dan hanya membaca penanda struktural. Tidak ada byte dokumen yang meninggalkan host, dan tidak ada teks dokumen yang diekstrak. Flag risiko, seperti JavaScript yang disematkan, merupakan sinyal perutean yang hanya bersifat indikatif. Flag ini bukan penegasan bahwa berkas aman atau tidak aman.

Kesesuaian

Pernyataan	Spesifikasi	Klausul
Header berkas mencatat versi PDF.	ISO 32000-2	§7.5.2
`/ID` pada trailer adalah pengenal berkas berupa dua byte string.	ISO 32000-2	§7.5.5
`Contents` pada kamus tanda tangan menyimpan CMS SignedData DER.	ISO 32000-2	§12.8.1

Resep ini hanya melaporkan fakta struktural. Resep ini tidak menegaskan bahwa berkas valid, aman, atau sesuai.

Konteks komersial

Kedalaman inspeksi Standard dan Full berjalan melalui sidecar Spectrum. Keduanya menambahkan analisis objek, fon, dan gambar yang lebih kaya. Fallback Quick yang didokumentasikan di sini tersedia di Core dan berjalan offline.