CLI: trình xử lý lệnh và bộ điều hợp trình xác thực bên ngoài

Tổng quan nhanh

Mô-đun giao diện dòng lệnh (CLI) cung cấp bề mặt dòng lệnh cho chẩn đoán và tuân thủ của engine. Mô-đun này bao gồm các trình xử lý cho lệnh benchmark, diff, init, verify và capabilities, cùng các bộ điều hợp bao bọc những trình xác thực Portable Document Format (PDF) bên ngoài, gồm veraPDF và mô hình Arlington PDF, đằng sau một giao diện chung. Một lệnh verify duy nhất có thể chạy bất kỳ bộ điều hợp nào.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Mỗi lệnh dùng một lớp trình xử lý mà phương thức execute() trả về mã thoát tiến trình. BenchmarkHandler chạy các kịch bản benchmark. DiffHandler so sánh các tài liệu. InitHandler dựng khung một dự án. VerifyHandler chạy xác minh tuân thủ. CapabilitiesHandler báo cáo mức hỗ trợ tại thời điểm chạy. CliOutput là bộ ghi stdout/stderr nhẹ được các trình xử lý dùng chung, nhờ đó đầu ra vẫn có thể kiểm thử thay vì bị gắn chặt với các biến toàn cục. BinaryFinder phân giải đường dẫn của một công cụ bên ngoài trên máy chủ (@since 2.5.0).

Bề mặt xác thực là ranh giới kiến trúc then chốt. AlternateValidatorAdapter là giao diện do một trình xác thực bên ngoài triển khai. validate() nhận một đường dẫn PDF và một ComplianceFlavour, rồi trả về một ComplianceValidationResult. isAvailable() báo cáo công cụ nền đã được cài đặt hay chưa. toolIdentifier() đặt tên cho công cụ đó. VeraPdfCliAdapter, ArlingtonValidatorAdapter và AsyncValidatorAdapter đều triển khai giao diện này. Engine không tự triển khai lại các trình xác thực của bên thứ ba. Thay vào đó, nó chạy các công cụ tham chiếu và chuẩn hóa phán quyết của chúng. Một trình xác thực chưa được cài đặt sẽ báo cáo isAvailable() === false thay vì làm hỏng lần chạy, nhờ đó quá trình xác minh ghi nhận rõ công cụ còn thiếu. Các bộ điều hợp thuộc @since 3.0.0; các trình xử lý lõi thuộc @since 2.3.0–@since 2.5.0.

Bề mặt API

Lớp	Thành viên chính	Vai trò
`BenchmarkHandler`	`execute(string $format = 'pretty', ?string $scenario = null): int`	Chạy các kịch bản benchmark (`@since 2.4.0`)
`VerifyHandler`	`execute(): int`	Điều phối xác minh tuân thủ
`DiffHandler` / `InitHandler`	`execute(): int`	So sánh tài liệu / tạo khung dự án
`CapabilitiesHandler`	`execute(string $format = 'pretty'): int`	Báo cáo các khả năng tại thời điểm chạy (`@since 2.3.0`)
`AlternateValidatorAdapter` (giao diện)	`validate()`, `isAvailable()`, `toolIdentifier()`	Hợp đồng trình xác thực bên ngoài (`@since 3.0.0`)
`VeraPdfCliAdapter`	triển khai bộ điều hợp	Bao bọc CLI veraPDF (`@since 3.0.0`)
`ArlingtonValidatorAdapter`	triển khai bộ điều hợp	Bao bọc mô hình Arlington PDF (`@since 3.0.0`)
`AsyncValidatorAdapter`	triển khai bộ điều hợp	Trình bao bọc trình xác thực có khả năng bất đồng bộ (`@since 3.0.0`)
`CliOutput`	`write()`, `writeln()`, `error()`	Bộ ghi stdout/stderr kiểm thử được (`@since 2.3.0`)
`BinaryFinder`	phân giải đường dẫn công cụ bên ngoài	Định vị các công cụ trên máy chủ (`@since 2.5.0`)

Để xem bảng PHPDoc đầy đủ, hãy chạy composer docs:generate-api-php -- --module=Cli.

Mẫu mã — bắt đầu nhanh

Nguồn: examples/33-validate-conformance.php. Chọn một bộ điều hợp trình xác thực và kiểm tra tính khả dụng trước khi sử dụng:

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

Mẫu mã — sản xuất

Chạy xác minh qua bất kỳ trình xác thực nào hiện có. Hãy xem một công cụ vắng mặt là một bước kiểm tra bị bỏ qua, chứ không phải một lỗi.

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

Trường hợp biên & lưu ý

Một trình xác thực không khả dụng trả về isAvailable() === false và không ném ngoại lệ. “Không có trình xác thực nào khả dụng” không phải là một lượt đạt; hãy xử lý nó như một trạng thái riêng biệt, đúng như mẫu mã sản xuất đang làm.
Các bộ điều hợp chạy những tệp nhị phân bên ngoài. Phán quyết của chúng là phán quyết đã được chuẩn hóa từ công cụ bên ngoài, chứ không phải một bản triển khai lại độc lập. Hãy luôn cập nhật các công cụ này.
Hàm execute() của trình xử lý trả về một mã thoát tiến trình. Mã khác không là một lỗi. Hãy lan truyền nó từ lớp bao bọc của bạn thay vì loại bỏ nó.
BinaryFinder phân giải đường dẫn của một công cụ trên máy chủ. Một máy chủ khác có thể phân giải ra một phiên bản công cụ khác. Hãy ghim môi trường để quá trình xác minh có thể tái lập.
Hồ sơ khả năng tái lập là structural: các báo cáo xác minh bao gồm dấu thời gian và phiên bản công cụ, nên những trường đó khác nhau giữa các lần chạy.

Hiệu năng

Chi phí phụ trội của trình xử lý là không đáng kể. Các tiến trình của trình xác thực bên ngoài chiếm phần lớn chi phí, và những tài liệu lớn có thể chạy chậm. AsyncValidatorAdapter cho phép bạn chồng lấp độ trễ đó. Mức performance_budget là 1500 ms thời gian thực / 64 MB đỉnh là tham chiếu của engine, không phải giới hạn cho một trình xác thực bên ngoài. Đầu ra benchmark có cấu trúc xác định, nhưng tất yếu vẫn bao gồm dữ liệu thời gian.

Lưu ý bảo mật

Các bộ điều hợp khởi chạy những tiến trình bên ngoài cho một đường dẫn PDF. Hãy xem PDF là đầu vào không đáng tin cậy, và chạy xác minh trong một môi trường bị giới hạn. Các trình xác thực bên ngoài phân tích dữ liệu thù địch. Hãy xác thực và chuẩn hóa mọi đường dẫn tệp trước khi truyền cho một trình xử lý, để việc duyệt đường dẫn không thể chạm tới tệp ngoài ý muốn. Đừng truyền đầu vào người dùng chưa được làm sạch làm tham số lệnh. Các bộ điều hợp dựng tham số tiến trình, chứ không phải chuỗi shell. Bản thân tệp đầu vào vẫn do kẻ tấn công kiểm soát. Hãy xem mô hình mối đe dọa của engine tại /modules/core/security/.

Tuân thủ

Mô-đun này không đưa ra tuyên bố chuẩn tắc riêng theo đặc tả PDF. Nó điều phối việc xác minh tuân thủ bằng cách ủy thác cho các trình xác thực tham chiếu: veraPDF cho PDF/A và PDF/UA, và mô hình Arlington PDF cho các quy tắc cấu trúc ISO 32000-2. Công cụ bên ngoài cung cấp phán quyết tuân thủ có thẩm quyền. Mô-đun này chuẩn hóa và báo cáo phán quyết đó. Tuân thủ đầu cuối và các golden baseline được mô tả trong /modules/core/conformance/.

Xem thêm

Mô-đun Inspect — nội quan có thể lập trình được cung cấp qua CLI.
Tổng quan tuân thủ — mô hình xác minh và các bộ golden.
Mô-đun Compliance — các hồ sơ ComplianceFlavour được các trình xác thực kiểm tra.
Mô hình bảo mật của engine