Inspect: PDF 분석 및 프리플라이트

한눈에 보기

Inspect 모듈은 기존 PDF를 읽고 그 내용을 보고합니다. 여기에는 복잡도 점수, 폰트 및 이미지 감사, 적합성 힌트, 위험 플래그가 포함됩니다. 프리플라이트 정책은 이 보고서를 pass/fail 판정으로 변환하므로, 문서가 파이프라인에 들어가기 전에 게이트를 적용할 수 있습니다.

안정성: 실험적. 분석은 계속 발전 중인 영역입니다. 이 InspectResult 형태, 위험 플래그 집합, 그리고 선택적 가속 분석 경로는 마이너 버전 사이에서 변경될 수 있습니다. 진단 및 게이팅 용도로 사용하십시오. 결과 형태를 장기 계약으로 아직 고정하지 마십시오.

설치

composer require nextpdf/core:^3

개념 개요

Inspector는 진입점입니다. 이 클래스는 InspectorInterface를 구현하며 메서드 하나만 제공합니다: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. 읽기 전용으로 동작합니다. PDF를 파싱하고 특성을 분석하지만, 문서를 수정하지 않습니다.

InspectResult는 구조화된 보고서입니다. 여기에는 복잡도 점수, 감사, 힌트, 그리고 RiskFlag 집합이 담깁니다. InspectResult는 hasRisks() / hasRisk(RiskFlag $flag)를 지원하므로, 호출자는 자유 형식 텍스트를 파싱하는 대신 특정 위험을 기준으로 분기할 수 있습니다. ComplexityScore는 수치 점수와 함께 category() 구간을 제공합니다. FontAuditEntry와 ImageAuditEntry는 임베드된 리소스를 설명합니다. ComplianceHint는 발생 가능성이 높은 적합성 문제를 표시합니다. InspectIssue는 특정 발견 사항을 기록합니다. InspectDepth로 분석 깊이를 선택하며, toSpectrumDepth()는 Spectrum 사이드카를 사용할 수 있을 때 이를 가속 경로로 매핑합니다. 분석은 사이드카 없이도 실행됩니다. 사이드카는 성능만 바꿀 뿐 계약을 바꾸지는 않습니다. InspectResponseParser는 원시 응답(예: 가속 경로 응답)에서 선택적 추적 ID와 함께 InspectResult를 구성합니다.

PreflightPolicy는 판정 계층입니다. evaluate(InspectResult $result)는 구성된 정책을 결과에 적용하고 정책 판정 결과를 반환합니다. 이 모듈 전체는 @since 2.2.0입니다.

API 표면

타입	주요 멤버	역할
`Inspector`	`inspect(string $pdfData, InspectConfig $config): InspectResult`	읽기 전용 PDF 분석기 (`@since 2.2.0`)
`InspectResult`	`hasRisks()`, `hasRisk(RiskFlag)`, score/audit 접근자	구조화된 분석 보고서 (`@since 2.2.0`)
`ComplexityScore`	`category()`	수치 복잡도 점수 + 구간 (`@since 2.2.0`)
`FontAuditEntry` / `ImageAuditEntry`	리소스 접근자	임베드 리소스 감사 (`@since 2.2.0`)
`ComplianceHint` / `InspectIssue`	발견 사항 접근자	적합성 힌트 및 발견 사항 (`@since 2.2.0`)
`InspectDepth` (enum)	`toSpectrumDepth()`	분석 깊이 → 가속 경로 (`@since 2.2.0`)
`PreflightPolicy`	`evaluate(InspectResult): array`, `toArray()`	Pass/fail 프리플라이트 판정 (`@since 2.2.0`)
`InspectResponseParser`	`parse(array, InspectConfig, ?string $traceId): InspectResult`	원시 응답에서 결과를 구성합니다 (`@since 2.2.0`)

전체 PHPDoc 표는 composer docs:generate-api-php -- --module=Inspect를 실행해 확인하십시오.

코드 예제 — 빠른 시작

출처인 examples/34-inspect-layout-boxes.php는 페이지 지오메트리를 읽는 방법을 보여 줍니다. 임의 PDF의 위험 프로파일을 분석하는 예:

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;

$result = (new Inspector())->inspect(file_get_contents('/srv/in/incoming.pdf'));

if ($result->hasRisks()) {
    echo "Complexity: {$result->complexityScore()->category()}; risks present.\n";
}

코드 예제 — 프로덕션

수신한 PDF를 프리플라이트 정책으로 게이팅하고, 위험이 있으면 거부합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;
use NextPDF\Inspect\PreflightPolicy;
use Psr\Log\LoggerInterface;

final readonly class IngestPreflight
{
    public function __construct(
        private Inspector $inspector,
        private PreflightPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    public function accept(string $pdfData): bool
    {
        $result = $this->inspector->inspect($pdfData);
        $verdict = $this->policy->evaluate($result);

        if ($verdict !== []) {
            $this->logger->warning('PDF rejected at preflight.', ['findings' => $verdict]);

            return false;
        }

        return true;
    }
}

엣지 케이스 & 주의 사항

inspect()는 읽기 전용입니다. 입력을 절대 수정하거나 복구하지 않습니다. “수정된” 문서가 반환되기를 기대하지 마십시오.
hasRisk(RiskFlag)는 정밀한 검사입니다. hasRisks()만으로 분기하면 모든 위험을 동일하게 취급하게 됩니다. 대개는 특정 플래그가 필요합니다.
InspectDepth는 비용을 제어합니다. 큰 PDF의 심층 분석은 상당히 느립니다. 질문에 답할 수 있는 가장 얕은 깊이를 선택하십시오.
Spectrum 가속 경로는 성능을 바꿀 뿐, 결과 계약을 바꾸지는 않습니다. 가속 응답 형태가 아닌 InspectResult를 기준으로 코드를 작성하십시오.
PreflightPolicy::evaluate()는 발견 사항을 반환하며 예외를 던지지 않습니다. 빈 결과는 통과를 의미합니다. 반환값을 기준으로 동작하십시오.

성능

분석 비용은 문서 크기와 선택한 InspectDepth에 따라 증가합니다. 얕은 분석은 빠릅니다. 큰 PDF의 심층 감사는 예산에 근접할 수 있습니다. Spectrum 경로는 사용 가능할 때 무거운 파싱을 오프로드합니다. 기준 워크로드의 performance_budget는 1500 ms 실측 경과 시간 / 64 MB 피크입니다. 재현성 프로파일은 structural입니다. 결과에는 추적 ID와 타이밍이 포함될 수 있습니다. 실행할 때마다 이러한 필드는 달라질 수 있지만, 동일한 입력에 대한 발견 사항은 안정적입니다.

보안 참고 사항

Inspector::inspect()는 신뢰할 수 없는 PDF 바이트를 파싱합니다. 이것이 본래 목적이므로 입력을 적대적인 것으로 취급하십시오. 사용자가 제공한 문서에 대해서는 제한된 워커에서 분석을 실행하고 업스트림에서 입력 크기를 제한하십시오. 의도적으로 복잡하게 만든 PDF는 깊이에 관계없이 서비스 거부 벡터입니다. 결과는 문서를 설명할 뿐, 정화하지는 않습니다. “낮은 위험” 판정은 휴리스틱일 뿐 안전 보장이 아닙니다. 추출된 문자열과 메타데이터는 신뢰할 수 없는 것으로 취급하십시오. 엔진 위협 모델은 /modules/core/security/를 참고하십시오.

적합성

이 모듈은 적합성 힌트를 보고할 뿐, 권위 있는 적합성 판정이 아닙니다. ComplianceHint는 발생 가능성이 높은 문제를 휴리스틱으로 표시합니다. 권위 있는 PDF/A, PDF/UA, ISO 32000-2 적합성 판정은 /modules/core/cli/가 구동하는 참조 검증기와, /modules/core/conformance/에 설명된 오라클 및 골든 스위트에서 나옵니다. 깨끗한 Inspect 결과를 적합성 인증으로 취급하지 마십시오.