Kiểm tra tuân thủ: tiền kiểm trong tiến trình với oracle bên ngoài

Tổng quan nhanh

Dùng công thức này để chạy các trình kiểm tra tuân thủ thuần PHP ngay trong tiến trình của NextPDF, như một bước tiền kiểm cấu trúc nhanh, rồi chuyển quyết định tuân thủ có thẩm quyền cho một trình kiểm tra độc lập. Các bước kiểm tra trong tiến trình là cần thiết, nhưng chưa đủ: kết quả sạch chỉ là một dữ kiện cấu trúc, không phải phán quyết tuân thủ. Công thức này dùng examples/33-validate-conformance.php và bộ khung kiểm thử tests/Cookbook/Php/ValidateConformanceRecipeTest.php của nó.

Cài đặt

composer require nextpdf/core:^3

Các trình kiểm tra trong tiến trình không yêu cầu bộ công cụ bên ngoài. Với bước cổng có thẩm quyền, bạn cần một trình kiểm tra bên ngoài trên PATH. Ví dụ này dùng veraPDF. Bạn không cần gói Pro hoặc Enterprise.

Tổng quan khái niệm

NextPDF cung cấp các trình kiểm tra trong tiến trình nằm dưới \NextPDF\Compliance\Validator. Chúng xác minh các bất biến quy chuẩn cụ thể mà không cần khởi động một tiến trình bên ngoài:

PdfRValidator — chạy các bước kiểm tra luồng byte theo ISO 23504-1 (PDF/R-1) §5/§6: danh sách cho phép cho file-header, các đối tượng thế hệ 0, danh sách toán tử nội dung trang được phép ở §6.5.7 (chỉ q/Q/cm/Do), và danh sách khóa Info-dict được phép ở §6.4.3. Nó trả về một PdfRValidationFinding[] phẳng; danh sách rỗng nghĩa là mọi bước kiểm tra §6 được kiểm soát đều đạt.
ArlingtonValidator — chạy ngữ pháp Arlington có thể đọc bằng máy của PDF Association ở chế độ chỉ báo cáo. Nó không bao giờ chặn bản dựng, và ghi lại SHA commit của ngữ pháp đã ghim trên mọi phát hiện để bên kiểm toán có thể đối chiếu với ảnh chụp upstream đã biết.

Các bước kiểm tra này được chủ ý giới hạn phạm vi. Chúng phát hiện sự lệch giữa hợp đồng được phát sinh và đặc tả, nhưng không xác lập tính tuân thủ ISO cho một profile như PDF/A-4 hoặc PDF/UA-2. Quyết định đó thuộc về một trình kiểm tra độc lập, và phán quyết của nó là cổng của bản dựng (ISO 19005-4 §6.7.3 nêu rõ điều này cho PDF/A). Công thức này giữ ranh giới rõ ràng: nó chạy bước tiền kiểm trong tiến trình, sau đó in ra và chạy lệnh oracle bên ngoài để quyết định.

Sơ đồ bên dưới minh họa cổng hai giai đoạn. Luồng này chịu một quy tắc duy nhất: chỉ phán quyết của oracle bên ngoài mới có thể được báo cáo là tuân thủ.

Diagram

Bề mặt API

Bề mặt API được sinh từ PHPDoc. Dùng các điểm vào chính sau:

\NextPDF\Compliance\Validator\PdfRValidator::validate(string $pdfBytes): list<PdfRValidationFinding>
\NextPDF\Compliance\Validator\PdfRValidationFinding (readonly: clause, severity, message)
\NextPDF\Compliance\Validator\ArlingtonValidator::validateReportOnly(string $pdfPath): list<ArlingtonFinding>
\NextPDF\Core\Document::output(?string $filename, OutputDestination $dest): string (OutputDestination::String để lấy byte thô)

Mã mẫu — khởi đầu nhanh

<?php

declare(strict_types=1);

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

use NextPDF\Compliance\Validator\PdfRValidator;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Document under conformance review.', newLine: true);

$bytes = $doc->output(dest: OutputDestination::String);

$findings = (new PdfRValidator())->validate($bytes);

// A finding list is a structural fact, not a conformance verdict.
echo $findings === []
    ? "No in-process PDF/R-1 findings (necessary, not sufficient).\n"
    : count($findings) . " in-process finding(s); not a conformance verdict.\n";

Mã mẫu — môi trường thực tế

Trong môi trường thực tế, hãy coi trình kiểm tra trong tiến trình như một cổng chi phí thấp, từ chối nhanh khi phát hiện sai lệch cấu trúc rõ ràng. Sau đó chạy oracle bên ngoài để đưa ra quyết định tuân thủ có thẩm quyền. Chỉ phán quyết của oracle mới có thể được báo cáo là tuân thủ.

$bytes = $doc->output(dest: OutputDestination::String);
$doc->save($out);

// 1. In-process pre-check — necessary, not sufficient.
$findings = (new PdfRValidator())->validate($bytes);
foreach ($findings as $finding) {
    fwrite(STDERR, sprintf("[%s] §%s — %s\n",
        $finding->severity, $finding->clause, $finding->message));
}

// 2. The authoritative gate — the external validator decides.
$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — not reported conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — the validator reports the file conforming\n";

Chạy ví dụ bằng php examples/33-validate-conformance.php. Nó tạo một PDF thông thường và in ra các phát hiện trong tiến trình. Dự kiến một PDF thông thường sẽ tạo ra các phát hiện PDF/R-1; đó chính là điểm cần minh họa. Sau đó ví dụ in ra lệnh oracle bên ngoài có thẩm quyền.

Trường hợp đặc biệt & điểm cần lưu ý

Cần thiết, nhưng chưa đủ. Danh sách phát hiện PdfRValidator rỗng chỉ có nghĩa là các bước kiểm tra §6 được kiểm soát đã đạt, không hơn. Đó không phải là tuyên bố tuân thủ PDF/A-4 hay PDF/UA-2. Đừng bao giờ báo cáo tính tuân thủ chỉ dựa trên một kết quả trong tiến trình.
Một PDF thông thường không đạt PDF/R-1 theo thiết kế. PDF/R-1 là một profile raster chỉ chứa hình ảnh; việc một PDF văn bản thông thường tạo ra các phát hiện §6.5.7 và §6.4.3 là hợp lý. Ví dụ cố tình minh họa điểm này để nhấn mạnh: kết quả trong tiến trình là một dữ kiện cấu trúc, không phải một phán quyết.
Arlington chỉ báo cáo. ArlingtonValidator::validateReportOnly() không bao giờ ném ngoại lệ và không bao giờ chặn. Ở chế độ chỉ ngữ pháp, nó phát ra một phát hiện info để chứng minh SHA của ngữ pháp đã ghim đã được nạp; nó trả về một danh sách rỗng khi ngữ pháp chưa được hiện thực hóa. Đừng xây một cổng pass/fail dựa trên nó — đó là đầu ra dùng để đối chiếu.
Byte so với tệp. PdfRValidator::validate() nhận chuỗi byte thô (OutputDestination::String); oracle bên ngoài cần một đường dẫn tệp. Lưu tệp bằng save() cho bước oracle.
Đầu vào rỗng. Truyền một chuỗi rỗng hoặc chuỗi không có header cho PdfRValidator::validate() sẽ trả về một phát hiện lỗi §6.2.2 thay vì ném ngoại lệ. Hãy kiểm tra danh sách phát hiện; đừng giả định sẽ có ngoại lệ.

Hiệu năng

Các trình kiểm tra trong tiến trình dùng biểu thức chính quy một lượt và quét byte trên toàn bộ PDF. Chúng chạy nhanh, cấp phát ít bộ nhớ với tài liệu thông thường, và nằm trong giới hạn 2000 ms / 128 MB. Khi có mặt, oracle bên ngoài chiếm phần lớn thời gian chạy thực tế, nhưng nó chạy ngoài tiến trình. Áp dụng profile tái lập theo ngữ nghĩa. Giá trị của ví dụ nằm ở hành vi kiểm tra quan sát được; bộ khung kiểm thử xác minh hành vi đó bằng cây cú pháp trừu tượng (AST) có cấu trúc cùng với so sánh metadata.

Ghi chú bảo mật

Lưu trú dữ liệu & giảm thiểu rủi ro PII

Các trình kiểm tra đọc byte tài liệu ngay trong tiến trình, và không có dữ liệu nào rời khỏi tiến trình. Tuy nhiên, oracle bên ngoài lại nhận tệp làm đầu vào. Nếu bạn chạy một trình kiểm tra dạng dịch vụ được lưu trữ, nội dung tài liệu sẽ rời khỏi ranh giới của bạn. Đối với nội dung nhạy cảm, hãy ưu tiên binary cục bộ của trình kiểm tra, hoặc tẩy xóa thông tin trước khi kiểm tra.

Telemetry an toàn & làm sạch nhật ký

Các phát hiện có thể trích dẫn đường dẫn đối tượng và đoạn toán tử. Ví dụ ghi các phát hiện ra STDERR và một dòng tiến độ cố định ra STDOUT. Đối với tài liệu nhạy cảm, hãy giữ nhật ký phát hiện ngoài các kênh thu thập chung. Đừng bao giờ ghi nhật ký các byte PDF thô.

Mô hình mối đe dọa

Kết quả sạch trong tiến trình không phải là tín hiệu về tính toàn vẹn hay tính xác thực. Bên tạo tệp có ý đồ xấu có thể tạo ra một tệp vượt qua các bước kiểm tra trong tiến trình có phạm vi giới hạn nhưng lại không đạt trình kiểm tra đầy đủ, hoặc một tệp đúng định dạng nhưng gây hiểu lầm. Hãy xem kết quả đạt trong tiến trình như một bộ lọc nhanh, không bao giờ coi đó là sự tin cậy.

Hành vi ở chế độ FIPS

Công thức này không thực hiện thao tác mật mã nào. Chế độ Federal Information Processing Standards (FIPS) không làm thay đổi hành vi của nó. Không có thao tác ký, mã hóa hay băm vật liệu tin cậy nào diễn ra.

Tính tuân thủ

Phát biểu	Đặc tả	Điều khoản
Nội dung trang PDF/R-1 chỉ dùng các toán tử trong danh sách cho phép q/Q/cm/Do.	ISO 23504-1	§6.5.7
Các trang PDF/R-1 là nội dung raster chỉ chứa hình ảnh.	ISO 23504-1	§6.5.5
PDF/R-1 áp ràng buộc lên các khóa trong từ điển thông tin tài liệu.	ISO 23504-1	§6.4.4
Ngữ pháp Arlington là bước đối chiếu mô hình đối tượng có thể đọc bằng máy.	Arlington PDF Model	ngữ pháp
Một trình kiểm tra, chứ không phải bên tạo tệp, quyết định tính tuân thủ.	ISO 19005-4	§6.7.3

Các trình kiểm tra trong tiến trình của NextPDF xác minh các bất biến quy chuẩn cụ thể. Hỗ trợ không phải là tuân thủ; kiểm tra không phải là chứng nhận. Kết quả sạch trong tiến trình không xác lập tính tuân thủ ISO; một trình kiểm tra độc lập (ví dụ veraPDF) đưa ra quyết định đó. Hãy dùng phán quyết của nó làm cổng cho bản dựng.