CLI: komut işleyicileri ve harici doğrulayıcı bağdaştırıcıları

Genel bakış

Komut satırı arayüzü (CLI) modülü, motorun tanılama ve uyumluluk komut yüzeyini sağlar. Benchmark, diff, init, verify ve capabilities komutlarına yönelik işleyiciler ile veraPDF ve Arlington PDF modeli dahil olmak üzere harici Portable Document Format (PDF) doğrulayıcılarını tek bir arayüzün arkasında saran bağdaştırıcıları içerir. Tek bir verify komutu herhangi bir bağdaştırıcıyı çalıştırabilir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Her komut, execute() yöntemi bir işlem çıkış kodu döndüren bir işleyici sınıfı kullanır. BenchmarkHandler karşılaştırma senaryolarını çalıştırır. DiffHandler belgeleri karşılaştırır. InitHandler bir proje iskeleti oluşturur. VerifyHandler uyumluluk doğrulamasını çalıştırır. CapabilitiesHandler çalışma zamanı desteğini raporlar. CliOutput, işleyiciler tarafından paylaşılan ince bir stdout/stderr yazıcısıdır; böylece çıktı global değişkenlere bağlanmak yerine test edilebilir kalır. BinaryFinder ana makinedeki harici bir aracın yolunu çözümler (@since 2.5.0).

Doğrulama yüzeyi, mimari açıdan temel sınırdır. AlternateValidatorAdapter, harici bir doğrulayıcının uyguladığı arayüzdür. validate() bir PDF yolu ve bir ComplianceFlavour alır ve bir ComplianceValidationResult döndürür. isAvailable() destekleyici aracın kurulu olup olmadığını raporlar. toolIdentifier() aracı adlandırır. VeraPdfCliAdapter, ArlingtonValidatorAdapter ve AsyncValidatorAdapter bu arayüzü uygular. Motor, üçüncü taraf doğrulayıcıları yeniden uygulamaz. Referans araçları çalıştırır ve onların kararını normalleştirir. Kurulu olmayan bir doğrulayıcı, çalıştırmayı başarısız kılmak yerine isAvailable() === false raporlar; böylece doğrulama eksik aracı açıkça kaydeder. Bağdaştırıcılar @since 3.0.0 sürümündendir; çekirdek işleyiciler ise @since 2.3.0–@since 2.5.0 sürümlerindendir.

API yüzeyi

Sınıf	Temel üyeler	Rol
BenchmarkHandler	execute(string $format = 'pretty', ?string $scenario = null): int	Karşılaştırma senaryolarını çalıştırır (@since 2.4.0)
VerifyHandler	execute(): int	Uyumluluk doğrulamasını yürütür
DiffHandler / InitHandler	execute(): int	Belge karşılaştırması / proje iskeleti
CapabilitiesHandler	execute(string $format = 'pretty'): int	Çalışma zamanı yeteneklerini raporlar (@since 2.3.0)
AlternateValidatorAdapter (arayüz)	validate(), isAvailable(), toolIdentifier()	Harici doğrulayıcı sözleşmesi (@since 3.0.0)
VeraPdfCliAdapter	bağdaştırıcıyı uygular	veraPDF CLI’sini sarmalar (@since 3.0.0)
ArlingtonValidatorAdapter	bağdaştırıcıyı uygular	Arlington PDF modelini sarmalar (@since 3.0.0)
AsyncValidatorAdapter	bağdaştırıcıyı uygular	Eşzamansız çalışabilen doğrulayıcı sarmalayıcısı (@since 3.0.0)
CliOutput	write(), writeln(), error()	Test edilebilir stdout/stderr yazıcısı (@since 2.3.0)
BinaryFinder	harici araç yolu çözümleme	Ana makine araçlarını bulur (@since 2.5.0)

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

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

Kaynak: examples/33-validate-conformance.php. Bir doğrulayıcı bağdaştırıcısı seçin ve kullanmadan önce kullanılabilir olup olmadığını kontrol edin:

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

Kod örneği — Üretim

Doğrulamayı kullanılabilir doğrulayıcılar üzerinden çalıştırın. Kullanılamayan bir aracı başarısızlık olarak değil, atlanmış bir kontrol olarak değerlendirin.

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

Sınır durumları ve dikkat edilecek noktalar

• Kullanılamayan bir doğrulayıcı isAvailable() === false döndürür ve istisna fırlatmaz. “Kullanılabilir doğrulayıcı yok” bir başarı değildir; üretim örneğinde olduğu gibi bunu ayrı bir durum olarak ele alın.
• Bağdaştırıcılar harici ikili dosyaları çalıştırır. Sonuç, bağımsız bir yeniden uygulamanın kararı değil, harici aracın normalleştirilmiş kararıdır. Araçları güncel tutun.
• İşleyicinin execute() yöntemi bir işlem çıkış kodu döndürür. Sıfır olmayan kod başarısızlık anlamına gelir. Bunu yok saymak yerine kendi sarmalayıcınızdan iletin.
• BinaryFinder ana makinedeki bir araç yolunu çözümler. Farklı bir ana makine, farklı bir araç sürümünü çözümleyebilir. Yeniden üretilebilir doğrulama için ortamı sabitleyin.
• Yeniden üretilebilirlik profili structural şeklindedir: doğrulama raporları zaman damgaları ve araç sürümleri içerir; bu nedenle bu alanlar çalıştırmalar arasında farklılık gösterir.

Performans

İşleyici ek yükü ihmal edilebilir düzeydedir. Maliyete harici doğrulayıcı işlemleri hâkimdir ve büyük belgeler yavaş olabilir. AsyncValidatorAdapter bu gecikmeyi örtüştürmenize olanak tanır. 1500 ms süre / 64 MB en yüksek bellek olan performance_budget değeri motor referansıdır; harici bir doğrulayıcı için sınır değildir. Karşılaştırma çıktısının deterministik bir yapısı vardır, ancak zorunlu olarak zamanlama verileri içerir.

Güvenlik notları

Bağdaştırıcılar, bir PDF yolu için harici işlemler başlatır. PDF’yi güvenilmeyen girdi olarak değerlendirin ve doğrulamayı kısıtlanmış bir ortamda çalıştırın. Harici doğrulayıcılar saldırgan verileri ayrıştırır. Bir dosya yolunu bir işleyiciye geçirmeden önce doğrulayın ve kanonikleştirin; böylece yol gezinmesi (path traversal) istenmeyen bir dosyaya ulaşamaz. Temizlenmemiş kullanıcı girdisini komut bağımsız değişkeni olarak geçirmeyin. Bağdaştırıcılar kabuk (shell) dizeleri değil, işlem bağımsız değişkenleri oluşturur. Girdi dosyasının kendisi saldırgan denetiminde kalmaya devam eder. Motor tehdit modeli için bkz. /modules/core/security/.

Uyumluluk

Bu modül, kendine ait herhangi bir PDF spesifikasyonu normatif iddiasında bulunmaz. Uyumluluk doğrulamasını referans doğrulayıcılara devrederek düzenler: PDF/A ve PDF/UA için veraPDF, ISO 32000-2 yapısal kuralları için Arlington PDF modeli. Yetkili uyumluluk kararını harici araç sağlar. Bu modül o kararı normalleştirir ve raporlar. Uçtan uca uyumluluk ve altın referans değerleri /modules/core/conformance/ bölümünde açıklanmıştır.

Ayrıca bkz.

• Inspect modülü — CLI üzerinden sunulan programatik içe bakış.
• Uyumluluk genel bakışı — doğrulama modeli ve altın test paketleri.
• Compliance modülü — doğrulayıcılar tarafından kontrol edilen ComplianceFlavour profilleri.
• Motor güvenlik modeli