NextPDF Backport Builder 개요

빌드 도구 — 런타임 의존성이 아닙니다. NextPDF 메인테이너는 이 패키지를 사용해 PHP 8.1+ 및 PHP 7.4+ 호환 NextPDF 배포본을 생성합니다. 애플리케이션은 이 패키지를 런타임 의존성으로 절대 추가해서는 안 됩니다.

한눈에 보기

NextPDF Backport Builder 는 개발 기준선보다 오래된 PHP 런타임을 위해 NextPDF 에코시스템의 다운그레이드된 배포본을 생성하는 빌드 인프라입니다. NextPDF 자체는 최신 PHP 버전을 기준으로 작성되며, 이전 인터프리터가 거부하는 구문을 사용합니다. 빌더는 추상 구문 트리 변환 엔진인 Rector로 소스를 처리한 뒤, PHP 8.1 또는 PHP 7.4 런타임이 받아들일 수 있는 구문으로 된 패키지를 내보냅니다.

Composer 패키지 이름은 nextpdf/backport-builder입니다. 이 패키지는 "type": "project"를 선언하며 NextPDF 런타임 의존성을 갖지 않습니다. 필요한 것은 빌드 엔진(rector/rector), 정적 분석(phpstan/phpstan), 테스트 러너(phpunit/phpunit), 그리고 생성된 출력에서 사용하는 symfony/polyfill-* 패키지 모음뿐입니다. 이는 저장소 루트의 composer.json에 대해 검증됩니다.

이 패키지가 아닌 것

이 저장소에는 NextPDF 엔진이 포함되어 있지 않습니다. 이 저장소에는 엔진을 백포트된 형태로 변환하는 규칙과 스크립트가 들어 있습니다. 여기에서 다음 세 가지 구분이 따라옵니다:

PDF 를 렌더링하기 위해 이것을 설치하는 것이 아닙니다. 설치해야 하는 산출물은 이 빌더가 생성한 nextpdf/backport입니다. 빌더는 메인테이너 또는 CI 호스트에 머무릅니다.
생성된 코드를 대상으로 개발하지 않습니다. 생성된 배포본은 기계가 생성한 읽기 전용 산출물입니다. 버그 보고와 기능 요청은 원본 nextpdf/* 소스 저장소로 보내십시오.
출력은 이 저장소의 브랜치가 아니라 버전 태그로 배포됩니다. 릴리스 파이프라인은 생성된 트리에 태그를 지정하고, 아카이브를 GitHub 릴리스에 첨부합니다.

무엇을 생성하는가

빌더는 이름과 라이선스가 scripts/adjust-composer.php에 의해 고정된 Composer 패키지를 내보냅니다:

생성된 패키지	라이선스	범위	빌드 시점
`nextpdf/backport`	`Apache-2.0`	코어, 그리고 PHP 8.1 타깃용 프레임워크 어댑터와 tcpdf 호환성 레이어	항상
`nextpdf/backport-pro`	`proprietary`	Pro 모듈, 별도 패키지로 내보냄	PHP 8.1 타깃, Pro 소스가 존재하며 Pro 가 제외되지 않은 경우

nextpdf/backport 패키지는 Composer replace 항목을 선언하므로, 설치되면 원본 패키지 제약 조건을 충족합니다. PHP 8.1 타깃에서는 nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, 그리고 nextpdf/compat-legacy가 교체되는 패키지입니다. PHP 7.4 타깃에서는 PHP 7.4 빌드가 코어 전용이므로 nextpdf/core만 교체됩니다. 이는 scripts/adjust-composer.php(buildReplace())에 대해 검증됩니다.

소비자 측 오토로더는 병합된 트리를 단일 PSR-4 접두사, 즉 src/에 매핑된 NextPDF\를 통해 해석합니다. PSR-4 는 네임스페이스 접두사를 기본 디렉터리에 매핑하고, 정규화된 각 클래스 이름을 그 아래의 파일로 해석합니다 — PHP-FIG PSR-4 참조. Pro 패키지는 NextPDF\Pro\를 자체 src/에 매핑합니다.

지원되는 PHP 매트릭스

아래 매트릭스는 Rector 구성과 빌드 스크립트가 강제하는 사항만 명시합니다. 빌드 호스트는 항상 최신 PHP 를 실행합니다. 출력은 더 오래된 PHP 를 대상으로 합니다.

항목	값	근거
빌드 호스트 PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
CI build/test PHP	8.5	`.github/workflows/0-ci.yml`, `build.yml` (`shivammathur/setup-phpphp-version: '8.5'`)
PHP 8.1 타깃 출력 제약 조건	`>=8.1 <8.5`	`scripts/adjust-composer.php` (`generatePublicComposer()`)
PHP 7.4 타깃 출력 제약 조건	`>=7.4 <8.1`	`scripts/adjust-composer.php` (`generatePublicComposer()`)
PHP 8.1 타깃 범위	Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, 별도)	`scripts/merge-sources.php`, `scripts/adjust-composer.php`
PHP 7.4 타깃 범위	코어 전용	`scripts/build.php` (`--target=php74`는 코어 전용을 강제하고 Pro 를 비활성화함)

PHP 8.1 빌드는 PHP 8.1, 8.2, 8.3, 8.4 에서 검증됩니다. PHP 7.4 빌드는 PHP 7.4 및 8.0 에서 검증됩니다. 이는 .github/workflows/build.yml의 validate-php81 및 validate-php74 작업 매트릭스에 대해 검증됩니다. 이들이 파이프라인이 실행하는 런타임입니다. 이는 관찰된 검증 집합이며 적합성 주장이 아닙니다.

이중 브랜치 모델

이 저장소에는 main 브랜치가 없습니다. PHP74는 기본 브랜치이고, PHP81은 두 번째 영구 브랜치입니다. 현재 체크아웃한 브랜치는 두 가지를 결정합니다: 로컬 빌드가 기본으로 삼는 타깃, 그리고 병합되는 소스 집합입니다. 두 타깃 모두에 영향을 미치는 변경은 각 브랜치마다 별도의 풀 리퀘스트를 통해 적용됩니다. 지속적 통합 워크플로는 PHP74와 PHP81 모두에서 실행됩니다. 이는 git branch -a와 .github/workflows/0-ci.yml (branches: [PHP74, PHP81])에 대해 검증됩니다.

릴리스가 일어나는 방식

릴리스 경로는 이벤트 기반입니다. NextPDF 소스 조직이 릴리스 태그를 게시하면, source-release 유형의 repository-dispatch 이벤트가 빌드 워크플로를 트리거합니다. 워크플로는 모든 소스 저장소를 일치하는 태그에서 체크아웃하고, 파이프라인을 실행하며, 타깃 런타임에서 출력을 구문 검사하고, 지원 매트릭스 전반에 걸쳐 검증한 다음, 아카이브를 GitHub 릴리스에 첨부합니다. 버전 태그는 시맨틱 버저닝을 따릅니다 — 버전 번호는 선언된 공개 API 에 대한 MAJOR.MINOR.PATCH입니다 (Semantic Versioning 2.0.0 §2). 이는 .github/workflows/build.yml에 대해 검증됩니다.

다음으로 갈 곳

/integrations/backport/install/ — 빌드 호스트에서 빌더를 가져오는 방법, 그리고 소비자가 생성된 패키지를 설치하는 방법.
/integrations/backport/configuration/ — Rector 구성, 사용자 지정 규칙, 그리고 빌드 플래그.
/integrations/backport/quickstart/ — 실행 가능한 드라이런과 전체 빌드 호출, 소스 기반.
/integrations/backport/production-usage/ — 빌더를 릴리스 워크플로에 연결하기.
/integrations/backport/troubleshooting/ — 파이프라인이 방어하는 실패 모드와 이를 읽는 방법.
/integrations/backport/security-and-operations/ — 공급망 태세, 신뢰 경계, 그리고 운영 보장.
/integrations/backport/boot-and-discovery/ — 빌더가 소스 모듈을 탐색하고 부팅하는 방법.
/integrations/backport/integration/ — 빌드 호스트 통합 계약.