CLI: penangan perintah dan adapter validator eksternal

Sekilas

Modul antarmuka baris perintah (CLI) menyediakan permukaan perintah diagnostik dan kesesuaian yang ditujukan untuk mesin. Modul ini mencakup penangan untuk perintah benchmark, diff, init, verify, dan capabilities, beserta adapter yang membungkus validator Portable Document Format (PDF) eksternal, termasuk veraPDF dan model Arlington PDF, di balik satu antarmuka. Satu perintah verify dapat menjalankan adapter apa pun.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Setiap perintah menggunakan kelas penangan dengan metode execute() yang mengembalikan kode keluar proses. BenchmarkHandler menjalankan skenario benchmark. DiffHandler membandingkan dokumen. InitHandler menyiapkan kerangka proyek. VerifyHandler menjalankan verifikasi kesesuaian. CapabilitiesHandler melaporkan dukungan runtime. CliOutput adalah penulis stdout/stderr ringan yang dipakai bersama oleh berbagai penangan, sehingga keluarannya tetap dapat diuji alih-alih terikat pada variabel global. BinaryFinder menyelesaikan jalur alat eksternal pada host (@since 2.5.0).

Permukaan validasi merupakan batas arsitektur utama. AlternateValidatorAdapter adalah antarmuka yang diimplementasikan oleh validator eksternal. validate() menerima jalur PDF dan ComplianceFlavour, lalu mengembalikan ComplianceValidationResult. isAvailable() melaporkan apakah alat pendukungnya terpasang. toolIdentifier() mengembalikan namanya. VeraPdfCliAdapter, ArlingtonValidatorAdapter, dan AsyncValidatorAdapter mengimplementasikannya. Mesin ini tidak mengimplementasikan ulang validator pihak ketiga. Mesin ini menjalankan alat referensi dan menormalkan putusannya. Validator yang tidak terpasang melaporkan isAvailable() === false alih-alih menggagalkan proses, sehingga verifikasi mencatat alat yang hilang secara eksplisit. Adapter memiliki @since 3.0.0; penangan inti memiliki @since 2.3.0–@since 2.5.0.

Permukaan API

Kelas	Anggota utama	Peran
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	Menjalankan skenario benchmark (@since 2.4.0)
VerifyHandler	execute(): int	Mengorkestrasi verifikasi kesesuaian
DiffHandler / InitHandler	execute(): int	Diff dokumen / menyiapkan kerangka proyek
CapabilitiesHandler	execute(string $format = 'pretty'): int	Melaporkan kapabilitas runtime (@since 2.3.0)
AlternateValidatorAdapter (antarmuka)	validate(), isAvailable(), toolIdentifier()	Kontrak validator eksternal (@since 3.0.0)
VeraPdfCliAdapter	mengimplementasikan adapter	Membungkus CLI veraPDF (@since 3.0.0)
ArlingtonValidatorAdapter	mengimplementasikan adapter	Membungkus model Arlington PDF (@since 3.0.0)
AsyncValidatorAdapter	mengimplementasikan adapter	Pembungkus validator berkemampuan asinkron (@since 3.0.0)
CliOutput	write(), writeln(), error()	Penulis stdout/stderr yang dapat diuji (@since 2.3.0)
BinaryFinder	penyelesaian jalur alat eksternal	Menemukan alat di host (@since 2.5.0)

Untuk tabel PHPDoc lengkap, jalankan composer docs:generate-api-php -- --module=Cli.

Contoh kode — Mulai cepat

Sumber: examples/33-validate-conformance.php. Pilih adapter validator dan periksa ketersediaannya sebelum menggunakannya:

<?php

declare(strict_types=1);

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

use NextPDF\Cli\VeraPdfCliAdapter;
use NextPDF\Compliance\ComplianceFlavour;

$validator = new VeraPdfCliAdapter(/* binary path / process factory */);

if (!$validator->isAvailable()) {
    fwrite(STDERR, "veraPDF is not installed; conformance verification skipped.\n");
    exit(2);
}

$result = $validator->validate('/srv/out/report.pdf', ComplianceFlavour::PdfA4);
echo $result->isCompliant() ? "PASS\n" : "FAIL\n";

Contoh kode — Produksi

Jalankan verifikasi melalui validator apa pun yang tersedia. Perlakukan alat yang tidak ada sebagai pemeriksaan yang dilewati, bukan sebagai kegagalan.

<?php

declare(strict_types=1);

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

use NextPDF\Cli\AlternateValidatorAdapter;
use NextPDF\Compliance\ComplianceFlavour;
use Psr\Log\LoggerInterface;

final readonly class ConformanceGate
{
    /** @param list<AlternateValidatorAdapter> $validators */
    public function __construct(
        private array $validators,
        private LoggerInterface $logger,
    ) {}

    public function verify(string $pdfPath, ComplianceFlavour $flavour): bool
    {
        $ran = false;

        foreach ($this->validators as $validator) {
            if (!$validator->isAvailable()) {
                $this->logger->info('Validator absent; skipped.', ['tool' => $validator->toolIdentifier()]);
                continue;
            }

            $ran = true;

            if (!$validator->validate($pdfPath, $flavour)->isCompliant()) {
                $this->logger->error('Conformance failed.', ['tool' => $validator->toolIdentifier()]);

                return false;
            }
        }

        // No validator available is not a pass — surface it.
        return $ran;
    }
}

Kasus tepi & jebakan

• Validator yang tidak tersedia mengembalikan isAvailable() === false dan tidak melempar pengecualian. “Tidak ada validator yang tersedia” bukanlah keberhasilan; tangani sebagai keadaan tersendiri, seperti pada contoh produksi.
• Adapter menjalankan biner eksternal. Putusannya adalah hasil yang telah dinormalisasi dari alat eksternal, bukan implementasi ulang yang independen. Jaga agar alat tersebut tetap mutakhir.
• execute() penangan mengembalikan kode keluar proses. Kode non-nol berarti kegagalan. Teruskan kode itu dari pembungkus Anda alih-alih membuangnya.
• BinaryFinder menyelesaikan jalur alat pada host. Host yang berbeda dapat menyelesaikan versi alat yang berbeda. Sematkan lingkungan agar verifikasi dapat direproduksi.
• Profil reproduktibilitasnya adalah structural: laporan verifikasi menyertakan stempel waktu dan versi alat, sehingga bidang tersebut berbeda antarproses.

Performa

Overhead penangan dapat diabaikan. Proses validator eksternal mendominasi biaya, dan dokumen besar bisa lambat. AsyncValidatorAdapter memungkinkan Anda meng-overlap latensi tersebut. performance_budget sebesar 1500 ms wall / 64 MB puncak adalah referensi mesin, bukan batas untuk validator eksternal. Keluaran benchmark memiliki struktur deterministik, tetapi tetap menyertakan data waktu.

Catatan keamanan

Adapter meluncurkan proses eksternal untuk jalur PDF. Perlakukan PDF sebagai masukan yang tidak tepercaya, dan jalankan verifikasi di lingkungan yang dibatasi. Validator eksternal mengurai data yang berpotensi berbahaya. Validasi dan lakukan kanonisasi pada setiap jalur berkas sebelum Anda meneruskannya ke penangan, sehingga path traversal tidak dapat menjangkau berkas yang tidak diinginkan. Jangan meneruskan masukan pengguna yang belum disanitasi sebagai argumen perintah. Adapter menyusun argumen proses, bukan string shell. Berkas masukan itu sendiri tetap dikendalikan oleh penyerang. Lihat model ancaman mesin di /modules/core/security/.

Kesesuaian

Modul ini tidak membuat klaim normatif tersendiri atas spesifikasi PDF. Modul ini mengorkestrasi verifikasi kesesuaian dengan mendelegasikan ke validator referensi: veraPDF untuk PDF/A dan PDF/UA, serta model Arlington PDF untuk aturan struktural ISO 32000-2. Alat eksternal menyediakan putusan kesesuaian yang otoritatif. Modul ini menormalkan dan melaporkan putusan tersebut. Kesesuaian menyeluruh dan baseline emasnya dijelaskan di /modules/core/conformance/.

Lihat juga

• Modul Inspect — introspeksi programatik yang diekspos melalui CLI.
• Tinjauan kesesuaian — model verifikasi dan suite emasnya.
• Modul Compliance — profil ComplianceFlavour yang diperiksa oleh validator.
• Model keamanan mesin