확장 개발: 공개 SPI 개요

한눈에 보기

NextPDF는 작고 신중하게 선별한 공개 계약 집합을 제공하며, 모두 NextPDF\Contracts 및 NextPDF\Event 네임스페이스에 있습니다. 이러한 계약을 구현하면 엔진을 포크하지 않고도 글꼴을 추가하거나, 텍스트를 가로채거나, 문서 수명 주기를 관찰하거나, 직접 만든 서명 백엔드를 제공할 수 있습니다.

설치

composer require nextpdf/core:^3

개념 개요

NextPDF는 **공개 서비스 공급자 인터페이스(SPI)**를 내부 코드와 분리합니다. SPI는 여러분이 구현하거나 관찰할 수 있도록 제공되는 타입 집합입니다. 그 밖의 모든 것은 비공개이며 예고 없이 변경될 수 있습니다.

공개 SPI에는 세 가지 형태가 있습니다.

레지스트리 계약. 문서를 생성하기 전에 채워 두는 프로세스 수명 서비스로, FontRegistryInterface와 ImageRegistryInterface가 대표적인 예입니다. 여러분이 에셋을 등록하면 엔진이 이를 읽습니다.
전략 계약. 렌더링 중에 엔진이 호출하는 단일 작업 후크입니다. TextPreprocessorInterface는 레이아웃 시점의 텍스트 가로채기를 처리하고, HtmlSecurityPolicyInterface는 HTML 기능을 통제합니다. 여러분이 동작을 제공하면 엔진이 이를 구동합니다.
서명 계약. 암호화 백엔드입니다. SignerInterface, HsmSignerInterface, DeferredSignerInterface를 사용하면 키 보관과 서명 생성을 직접 맡을 수 있습니다. 엔진이 CMS 구조를 만들고, 여러분의 코드가 키를 보유합니다.

별도의 PSR-14 호환 이벤트 시스템인 NextPDF\Event가 관찰 기능을 담당합니다. 수명 주기 이벤트를 사용하면 문서 생성, 새 페이지, 글꼴 로딩, 서명, 기록 출력에 반응할 수 있습니다. 이벤트는 엔진 동작을 변경하지 않습니다.

각 계약의 소스 PHPDoc에는 @stability 태그가 포함되어 있으며 값은 stable, experimental, 또는 deprecated입니다. 이 태그와 계약별 하위 호환성 약속은 앞으로 변경이 얼마나 발생할 수 있는지 알려 줍니다. 전체 정책은 SPI 안정성 규칙을 참조하세요.

확장 가능한 것

기능	공개 계약	안정성
글꼴 등록 및 조회	`NextPDF\Contracts\FontRegistryInterface`	stable(1.7.0 부터)
이미지 캐싱 및 디코딩	`NextPDF\Contracts\ImageRegistryInterface`	stable(2.0.0 부터)
레이아웃 시점 텍스트 가로채기	`NextPDF\Contracts\TextPreprocessorInterface`	stable(1.9.0 부터)
HTML 기능 통제	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stable(3.1.0 부터)
문서 팩토리 연결	`NextPDF\Contracts\DocumentFactoryInterface`	stable(1.7.0 부터)
동기 서명	`NextPDF\Contracts\SignerInterface`	stable(1.0.0 부터)
하드웨어 기반 서명	`NextPDF\Contracts\HsmSignerInterface`	stable(1.0.0 부터)
지연 및 일괄 서명	`NextPDF\Contracts\DeferredSignerInterface`	experimental(3.0.0 부터)
RFC 3161 타임스탬프	`NextPDF\Contracts\TimestampProviderInterface`	experimental(3.0.0 부터)
수명 주기 관찰	`NextPDF\Event\*` (PSR-14 호환)	디스패처는 stable, 페이로드는 experimental 입니다.

공개되지 않은 것

다음은 내부 항목입니다. 이를 임포트하거나, 서브클래싱하거나, 의존하지 마세요:

다음 네임스페이스, 즉 NextPDF\Contracts 및 NextPDF\Event 밖에 있는 클래스는 해당 PHPDoc에 @stability 태그가 없는 한 내부 항목입니다.
HTML 파서, 작성기, 레이아웃 파이프라인, 글꼴 서브셋터와 같은 구체적인 엔진 코드.
NextPDF Pro 및 NextPDF Enterprise 패키지. 이들의 내부 클래스는 오픈 소스 표면의 일부가 아닙니다. 유료 에디션이 SPI 구현을 제공할 때는 내부 타입이 아니라 공개 계약을 사용합니다.

API 표면

공식 목록은 생성된 계약 맵입니다. 이 맵은 릴리스마다 소스에서 다시 빌드됩니다. 각 인터페이스 파일의 @stability PHPDoc 태그를 단일 진실 공급원으로 삼으세요. 위 표는 이해를 돕기 위한 참고 자료입니다.

코드 예제 — 빠른 시작

글꼴을 등록한 다음 로드되는 시점을 관찰하세요. 두 단계 모두 공개 타입만 사용합니다.

<?php

declare(strict_types=1);

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\Content\FontLoadedEvent;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;

/** @var FontRegistryInterface $fonts */
$fonts->register('/srv/fonts/Inter-Regular.ttf', 'Inter');

$listeners = new ListenerProvider();
$listeners->addListener(
    FontLoadedEvent::class,
    static function (FontLoadedEvent $event): void {
        \error_log("Font loaded: {$event->family} {$event->style}");
    },
);

$dispatcher = new EventDispatcher($listeners);

코드 예제 — 프로덕션

장시간 실행되는 워커에서는 부팅 시 레지스트리를 한 번 빌드하고 잠근 다음, 문서 팩토리를 통해 공유 디스패처를 주입하세요.

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use Psr\Log\LoggerInterface;

final class DocumentBootstrap
{
    public function __construct(
        private readonly FontRegistryInterface $fonts,
        private readonly DocumentFactoryInterface $factory,
        private readonly LoggerInterface $logger,
    ) {}

    public function warmup(): EventDispatcher
    {
        $this->fonts->warmup([
            '/srv/fonts/Inter-Regular.ttf',
            '/srv/fonts/Inter-Bold.ttf',
        ]);
        $this->fonts->lock();

        $listeners = new ListenerProvider();
        $listeners->addListener(
            \NextPDF\Event\Security\SignatureAppliedEvent::class,
            fn (object $event): mixed => $this->logger->info('Signature applied'),
        );

        return new EventDispatcher($listeners);
    }
}

엣지 케이스 및 주의 사항

레지스트리 잠금. FontRegistryInterface::lock() 이후에는 변경 메서드가 LogicException을 던집니다. 워밍업이 끝난 뒤에만 잠그세요.
안정성 불일치. experimental 계약은 마이너 릴리스에서 변경될 수 있습니다. 프로덕션에서 계약에 의존하기 전에 명시된 안정성을 확인하세요.
네임스페이스 규율. NextPDF\Contracts 또는 NextPDF\Event 밖에 있으면서 @stability 태그가 없는 타입은 내부 항목입니다. 기술적으로 public이어도 마찬가지입니다.

성능

SPI는 사용하지 않을 때 비용이 전혀 들지 않습니다. 이벤트 클래스에 바인딩된 리스너가 없으면 이벤트 디스패처는 hasListeners()를 한 번 검사한 뒤 즉시 반환합니다. 레지스트리는 순수 PHP 데이터를 보유하며, 첫 요청의 지연 시간을 분산하기 위해 부팅 시점 워밍업을 지원합니다.

보안 참고 사항

서명 계약은 보안에 민감한 표면입니다. HsmSignerInterface는 개인 키가 하드웨어 경계를 절대 벗어나지 않아야 한다고 요구합니다. 여러분의 구현은 이를 준수해야 합니다. 서드파티 서명 백엔드 계약과 해당 위협 모델은 KMS 공급자 계약을 참조하세요.

적합성

이 개요 페이지는 규범적 주장을 하지 않습니다. 계약별 적합성(PAdES, 키 관리)은 관련 SPI 페이지에 문서화되어 있습니다.

상업적 맥락

NextPDF Pro 및 NextPDF Enterprise는 키 관리 시스템 기반 서명을 포함하여 여러 서명 및 검증 계약의 프로덕션 구현을 제공합니다. 에디션이 구현을 제공할 때도 여러분은 공개 계약에 의존하므로, 코드는 에디션 간 이식성을 유지합니다.