PHP 8.4 기반

Spec: ISO 32000-2, §7.5.2 Evidence: Code-backed PHP 제약: ≥8.4 <9.0

한눈에 보기

NextPDF는 PHP 8.4를 요구합니다. 이 페이지는 엔진이 실제로 의존하는 8.4 언어 기능이 무엇인지, 그 버전이 단순한 권장이 아니라 엄격한 최저 기준인 이유가 무엇인지, 그리고 별도의 다운그레이드 빌드가 여러분이 읽는 코드베이스를 약화시키지 않으면서 구형 런타임에서 실행할 수 있는 선택지를 어떻게 열어 두는지 설명합니다.

이것이 중요한 이유

PDF 엔진은 모호한 입력을 바이트 단위로 정확한 파일 형식으로 변환합니다. PDF는 확고하고 고정된 규칙을 갖춘 오래 정립된 형식이며, 잘못된 추측이 큰 대가로 이어질 만큼 엄격합니다. 엔진이 작성된 언어는 그러한 추측이 포착되거나 검증 없이 통과되는 첫 번째 지점입니다. 버전 최저 기준은 그 자체를 위한 제한이 아닙니다. 그 아래 버전에서는 엔진이 나머지 설계가 의존하는 타입 보장을 더 이상 할 수 없게 되는 선입니다.

이 최저 기준이 모호하면 두 가지 대가가 따릅니다. 코드베이스는 실제 로직을 가리는 호환성 심으로 가득 차게 됩니다. 또한 타입 시스템이 하중을 지탱하는 역할을 멈추게 되는데, 이는 문서 파이프라인이 결코 잃어서는 안 되는 바로 그 속성입니다.

요약

코어 패키지는 "php": ">=8.4 <9.0"을 선언합니다. 그것이 composer.json에서 검증되는 실제 제약이며, 문서상의 희망 사항이 아닙니다.
8.4가 최저 기준인 이유는 엔진이 8.4(그리고 최근 8.x) 언어 기능을 구조적 보장으로 사용하기 때문입니다. 비대칭 가시성, 동작을 갖춘 백드 enum, 타입이 지정된 클래스 상수, readonly 상태, 그리고 공개 API의 일급 명명 인수가 그것입니다.
PHP 8.1–8.3에서의 실행은 별도의 다운그레이드 빌드(백포트)를 통해 여전히 가능합니다. 이는 빌드 도구이지 런타임 의존성이 아닙니다. 여러분이 코어 저장소에서 읽는 코드를 바꾸지 않습니다.
상한 <9.0은 의도적입니다. 새로운 PHP 메이저 릴리스는 가정할 대상이 아니라 검증할 대상으로 취급됩니다.

NextPDF 가 이를 다루는 방식

최저 기준은 코드가 무엇을 하는지에 따라 정해집니다. 따라서 이를 있는 그대로 설명하려면 기능을 추상적으로 나열하기보다 코드 속에서 보여 주어야 합니다.

비대칭 가시성은 필드마다 직접 작성한 getter가 없어도 상태를 공개적으로 읽을 수 있되 쓰기는 비공개로만 가능하게 합니다. 렌더링 컨텍스트는 이를 직접 사용합니다:

declare(strict_types=1);

final class RenderingContext
{
    // Readable everywhere, writable only inside the class.
    public private(set) float $x = 0.0;
    public private(set) float $y = 0.0;
    public private(set) int $currentPageIndex = -1;
    public private(set) string $currentContentStream = '';
}

이 하나의 언어 기능이 우발적인 외부 변경이라는 한 부류 전체를 제거합니다. 커서는 엔진 외부에서 이동시킬 수 없습니다. 이 보장은 검토자가 기억해야 할 관례가 아니라 런타임이 강제하는 보장입니다.

동작을 갖춘 백드 enum은 흩어진 불리언 플래그와 문자열 상수를, 자기 자신에 대한 질문에도 답할 수 있는 하나의 타입 지정 값으로 대체합니다. 문서 적합성 판별자는 그 메서드가 사양 수준의 결과를 결정하는 백드 enum입니다:

declare(strict_types=1);

enum ConformanceMode: string
{
    case Plain  = 'plain';
    case PdfUa2 = 'pdfua2';
    case PdfA4  = 'pdfa4';
    case PdfA4f = 'pdfa4f';

    public function isTagged(): bool
    {
        return match ($this) {
            self::Plain => false,
            default     => true,
        };
    }

    /** @return 2|3|4|null */
    public function pdfaPart(): ?int
    {
        return match ($this) {
            self::PdfA4, self::PdfA4f => 4,
            default                   => null,
        };
    }
}

이 enum은 “이 문서가 사양 태그로 지정되어 있는가?” 그리고 “어떤 ISO 부분이 적용되는가?”라는 질문에 답합니다. 이러한 질문이 느슨한 불리언으로 표현되면 여러 곳에서 일관되지 않게 답할 수 있었습니다.

타입이 지정된 클래스 상수는 상수마저도 타입 계약의 일부로 만듭니다. HTML 엔진의 엄격한 제한값은 타입이 지정된 상수로 선언됩니다:

private const int MAX_NESTING_DEPTH = 100;
private const int MAX_ELEMENT_COUNT = 50_000;

명명 인수는 내부적인 요령이 아니라 공개 API 표면의 일부입니다. 예제 프로그램은 독자가 복사하도록 의도된 호출 지점에서 이를 전달합니다:

$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);

이것들은 새 문법의 장식적인 사용이 아닙니다. 각각은 그렇지 않았다면 검토자가 손으로 강제해야 했을 관례를 런타임이 강제하는 속성으로 바꿉니다.

증거가 말하는 것

이 페이지는 Evidence: Code-backed 입니다. 위의 모든 주장은 단순한 기능 목록이 아니라 코어 저장소의 파일에 대응됩니다:

버전 제약은 코어 composer.json의 require.php 값 ">=8.4 <9.0"입니다.
비대칭 가시성 예제는 src/Core/RenderingContext.php의 실제 선언 방식입니다(public private(set) 필드).
enum 예제는 src/Conformance/ConformanceMode.php를 반영하며, 이는 적합성 결정을 이끄는 match 기반 메서드를 가진 백드 enum … : string입니다.
타입이 지정된 상수는 src/Html/HtmlParser.php에 있습니다(private const int MAX_NESTING_DEPTH, MAX_ELEMENT_COUNT).
명명 인수 호출은 제공되는 examples/ 프로그램에서 가져온 것입니다.

최저 기준에는 표준 측면도 있습니다. 엔진의 임무는 다음을 준수하는 파일을 내보내는 것입니다 Spec: ISO 32000-2, §7.5.2 . 적합한 PDF 2.0 작성기는 파일 헤더 또는 카탈로그에서 문서 버전을 2.0으로 선언해야 합니다. 그만큼 정확한 의무를 충족하는 일은 작성기 아래의 언어가 불일치 상태를 애초에 구성하기 어렵게 만들 때 훨씬 더 쉬워집니다. 버전 최저 기준과 형식의 엄격성은 서로 정렬되어 있습니다.

실용 예제

가장 작은 올바른 프로그램도 이미 최저 기준을 활용합니다. 이 프로그램은 PHP 8.4에서 실행되고, 명명 인수를 사용하며, 적합한 파일을 생성합니다:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->save(__DIR__ . '/hello.pdf');

여기에 특이한 것은 없습니다. 요점은 엔진 내부를 신뢰할 수 있게 만드는 바로 그 엄격한 타이핑, enum, 비대칭 가시성 메커니즘이 이 다섯 줄짜리 프로그램 아래에서도 이미 작동하고 있다는 것입니다. 여러분이 별도로 선택해서 적용하는 것이 아닙니다.

흔한 오해

가장 흔한 오독은 “PHP 8.4를 요구한다”를 “8.4로 업그레이드하지 않으면 작동하지 않는다”로 이해하는 것입니다. 이는 코어 소스가 8.4를 대상으로 한다는 의미입니다. PHP 8.1–8.3에 고정된 팀을 위해 별도의 다운그레이드 빌드가 존재합니다.

그 빌드가 무엇인지 정확히 구분하는 것이 중요합니다. 이는 8.4 소스를 구형 문법의 출력물로 변환하는 Rector 기반 다운그레이드 파이프라인입니다. 빌드 인프라이지, 애플리케이션의 의존성에 추가하는 런타임 라이브러리가 아닙니다. 타입 보장이 더 약한 병렬 코드베이스를 도입하지도 않습니다. 이 페이지에서 검토되는 코드와 출시되는 코드는 동일한 코드입니다. 백포트는 그 코드에 적용되는 변환이지, 그 코드를 대체하는 것이 아닙니다.

한계와 경계

이 페이지는 8.4가 왜 최저 기준인지와 백포트가 무엇을 보존하는지를 설명합니다. 이 페이지는 다운그레이드 파이프라인의 실행 방법, 지원되는 대상 버전, 또는 운영상의 주의 사항을 문서화하지 않습니다. 그러한 내용은 백포트 빌드 자체의 문서에 속합니다. 그 도구의 내부 패키지 구성은 여기서 다루는 범위를 벗어납니다. 여기서 제시한 기능 사용 사례는 엔진의 방식을 예로 보여 주는 것입니다. 그것이 코드베이스가 사용하는 모든 8.x 기능의 완전한 목록은 아닙니다. 정확한 API는 이 설명이 아니라 레퍼런스에 의해 정의됩니다. 버전 제약은 이 페이지의 검토 날짜 기준으로 정확합니다. 권위 있는 값은 언제나 코어 composer.json의 require 블록입니다.

에디션은 언어 최저 기준에 아무런 영향을 주지 않습니다. 모든 에디션은 동일한 PHP 8.4 소스로부터 빌드됩니다:

PHP 8.4 source floor — edition availability
Edition	Availability
Core	Core는 PHP 8.4를 기준으로 작성됩니다.
Pro	Pro는 동일한 8.4 소스 최저 기준 위에 빌드됩니다.
Enterprise	Enterprise는 동일한 8.4 소스 최저 기준 위에 빌드됩니다.

용어집

버전 최저 기준 — 코어 소스가 대상으로 하는 최소 PHP 버전(>=8.4). 그 아래 버전에서는 엔진의 타입 보장을 표현할 수 없습니다.
비대칭 가시성 — 속성을 공개적으로 읽을 수 있되 쓰기는 더 좁은 범위에서만 가능하게 하는 PHP 8.4 기능(public private(set)).
백드 enum — 케이스가 스칼라 값을 가지며 동작(메서드)을 담을 수 있는 PHP enum으로, 여기서는 타입이 지정된 단일 진실 공급원으로 사용됩니다.
백포트 — 8.4 소스를 구형 PHP에서 실행 가능한 출력으로 변환하는 별도의 Rector 기반 다운그레이드 빌드입니다. 런타임 의존성이 아니라 빌드 도구입니다.
적합성 모드 — 문서가 어떤 ISO 적합성 계약을 충족해야 하는지 판별하는 엔진의 타입 지정 값입니다.