SPI 안정성 규칙

한눈에 보기

NextPDF 서비스 공급자 인터페이스는 유의적 버전 관리(Semantic Versioning)를 따릅니다. 각 공개 계약에는 @stability 태그와 하위 호환성 약속이 있습니다. 이 페이지는 어떤 계약에 의존할지 판단할 수 있도록 해당 규칙을 설명합니다.

설치

composer require nextpdf/core:^3

개념 개요

서비스 공급자 인터페이스는 NextPDF\Contracts 및 NextPDF\Event 네임스페이스에 있는 공개 계약의 집합입니다. 어떤 타입은 해당 소스 PHPDoc에 @stability 태그가 있을 때에만 이 인터페이스의 일부가 됩니다. 태그가 곧 경계입니다. 태그가 없는 타입은 PHP에서 기술적으로 public이더라도 내부용입니다.

NextPDF는 유의적 버전 관리(Semantic Versioning) 2.0.0을 따릅니다. stable 계약에 대한 호환성 파괴 변경은 메이저 버전을 올립니다. 새 계약이나 호환성을 파괴하지 않는 추가 사항은 마이너 버전을 올립니다. 버그 수정은 패치 버전을 올립니다.

@stability 태그

각 계약은 세 가지 안정성 값 중 하나를 선언합니다.

태그	의미	변경 규칙
`stable`	프로덕션에서 사용할 준비가 되었습니다. 안전하게 의존할 수 있습니다.	마이너 또는 패치 릴리스에서 호환성 파괴 변경이 없습니다. 새 메서드는 기본 동작과 함께 추가되거나 새 계약에만 추가됩니다.
`experimental`	사용할 수 있지만 아직 고정되지 않았습니다.	인터페이스는 사용 중단 공지를 먼저 거쳐 마이너 릴리스에서 변경될 수 있습니다.
`deprecated`	제거 예정.	계약은 대체 항목과 제거 버전을 명시합니다.

계약별 약속은 생성된 계약 맵에 기록되며 각 릴리스마다 소스에서 다시 생성됩니다. 약속 문구는 해당 계약에 대한 정확한 규칙을 명시합니다. 계약 소스 PHPDoc을 단일 진실 공급원으로 삼아 확인하십시오.

하위 호환성 약속 분류

계약 맵에는 약속이 기록됩니다. 약속은 네 가지로 분류됩니다.

인터페이스 약속. “마이너 또는 패치 릴리스에서 호환성 파괴 변경이 없습니다. 새 메서드는 기본 구현이 있는 경우에만 추가됩니다.” 대부분의 stable 인터페이스, 즉 FontRegistryInterface, SignerInterface, HsmSignerInterface, HtmlSecurityPolicyInterface 등에 적용됩니다.
열거형 약속. “케이스를 제거하지 않습니다. 새 케이스는 마이너 버전에서 추가될 수 있습니다.” stable 열거형, 즉 Alignment, Orientation, OutputDestination 등에 적용됩니다.
고정 값 객체 약속. “생성자 시그니처와 공개 속성은 고정됩니다. 새 메서드는 추가될 수 있습니다.” TextPreprocessResult, TextSegment 같은 값 객체와 그에 바인딩된 이벤트 페이로드에 적용됩니다.
실험적 약속. “인터페이스는 사용 중단 공지와 함께 마이너 버전에서 변경될 수 있습니다.” experimental 계약, 즉 DeferredSignerInterface, TimestampProviderInterface, CursorInterface, StreamingWriterInterface 등에 적용됩니다.

예를 들어 final 클래스인 EventDispatcher나 ListenerProvider는 공개 메서드 시그니처를 고정합니다. final 클래스를 확장할 때는 합성을 사용하십시오. 상속으로 하위 클래스를 만들지 마십시오.

실험적 스트리밍 계약

CursorInterface와 StreamingWriterInterface는 experimental입니다(3.1.0부터). NextPDF는 두 계약 각각에 대해 테스트를 거친 final 엔진 구현을 제공합니다. 구현 클래스는 내부용이며 공개 API 표면의 일부가 아닙니다. 스트리밍 동작은 공개 experimental 계약을 통해 사용하십시오. 일반적인 경우에는 이 계약을 직접 구현하지 않습니다.

계약이 experimental이므로 시그니처는 사용 중단 공지를 먼저 거쳐 마이너 릴리스에서 변경될 수 있습니다(실험적 약속). 프로덕션에서 의존하기 전에 버전을 엄격히 고정하거나 자체 어댑터로 감싸십시오. 스트리밍 계약은 고정된 것이 아니라 안정화 중인 확장 지점으로 취급하십시오.

API 표면

이 페이지에는 런타임 API가 없습니다. 관련 API 표면은 모든 공개 계약의 @stability PHPDoc 태그와 계약별 약속을 집계하는 재생성된 계약 맵입니다.

코드 샘플 — 빠른 시작

계약에 의존하기 전에 소스에서 해당 계약의 안정성을 확인하십시오.

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

코드 샘플 — 프로덕션

Composer 버전 제약 조건은 메이저 버전을 고정합니다. 메이저 버전은 stable 계약에 대한 호환성 파괴 변경의 단위입니다.

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

버전을 ^3.0으로 고정하면 어떤 stable 계약에도 호환성 파괴 변경이 없는 마이너 및 패치 릴리스를 받습니다. experimental 계약에 의존하는 경우에는 experimental 계약이 마이너 릴리스에서 변경될 수 있으므로 더 엄격하게 고정하십시오.

엣지 케이스 및 주의사항

가시성이 아니라 태그입니다. public PHP 메서드는 이를 선언하는 타입에 @stability 태그가 없으면 서비스 공급자 인터페이스의 일부가 아닙니다.
실험적 드리프트. experimental 계약은 마이너 릴리스에서 변경될 수 있습니다. 버전을 엄격히 고정하거나 자체 어댑터로 감싸십시오. 이는 스트리밍 계약에 구현이 제공되어 있더라도 동일하게 적용됩니다.
새 기본 메서드. stable 인터페이스에는 기본 동작이 있는 메서드가 추가될 수 있습니다. 자체 구현을 명시적으로 유지하려면 업그레이드 시 새 메서드를 구현하십시오.
에디션 동등성. NextPDF Pro와 NextPDF Enterprise는 동일한 규칙을 따릅니다. Core에서 대상으로 삼은 계약은 동일한 계약의 Premium 구현에 대해서도 유효하게 유지됩니다.

사용 중단 수명 주기

계약은 정의된 수명 주기를 거쳐 진행됩니다.

표시. 소유자는 소스 PHPDoc에 @stability deprecated를 설정하고 대체 항목과 제거 버전을 기록합니다.
공지. 사용 중단은 해당 표시가 포함된 릴리스의 변경 로그에 공지됩니다.
공존. 사용 중단된 계약과 그 대체 항목은 최소 한 번의 마이너 릴리스 동안 공존합니다.
제거. 계약은 명시된 메이저 릴리스에서 제거됩니다. 제거는 마이너 또는 패치 릴리스에서는 절대 발생하지 않습니다.

계약이 deprecated로 표시되는 즉시 업그레이드를 계획하십시오. 대체 항목은 항상 명시됩니다.

성능

이 페이지는 정책을 정의합니다. 런타임 비용이 없습니다.

보안 참고 사항

서명 계약은 stable이며 인터페이스 약속을 따릅니다. 서명 계약의 새 메서드는 기본 동작과 함께 추가되거나 새 계약에만 추가되므로, 마이너 업그레이드에서 하드웨어 기반 구현이 깨지지 않습니다. 메이저 버전은 stable 계약을 변경할 수 있으므로, 메이저 업그레이드 전에 변경 로그를 검토하십시오.

적합성

버전 관리 규칙은 유의적 버전 관리(Semantic Versioning) 2.0.0을 준수합니다. 변경 로그 생성은 Conventional Commits 1.0.0을 따릅니다.

상용 컨텍스트

NextPDF Pro와 NextPDF Enterprise는 Core와 동일한 서비스 공급자 인터페이스 안정성 규칙을 따릅니다. Core에서 대상으로 삼은 계약은 해당 계약의 Premium 구현에 대해서도 유효하게 유지되므로, 확장 코드는 에디션 간에 이식 가능합니다.