NextPDF Backport Builder 빠른 시작

빌드 도구이며 런타임 의존성이 아닙니다. 이 가이드는 메인테이너 또는 지속적 통합(CI) 호스트에서 실행됩니다. 생성된 아카이브는 다운스트림 프로젝트에서 사용하는 대상입니다. 여기의 단계는 애플리케이션 서버에서 절대 실행되지 않습니다.

한눈에 보기

세 가지 작업을 실행합니다. 먼저 파일을 건드리지 않고 파이프라인이 올바르게 연결되었음을 확인하는 드라이런을 실행합니다. 다음은 전체 PHP 8.1 빌드이고, 그다음은 전체 PHP 7.4 빌드입니다. 각 단계는 하나의 명령으로 실행됩니다. 각각은 Composer 스크립트 또는 문서화된 scripts/build.php 호출로 뒷받침됩니다.

사전 요구 사항

빌드 의존성이 설치된 PHP >=8.4 <9.0 빌드 호스트가 필요합니다(composer install, --no-dev 없이). /integrations/backport/install/을 참고하세요.
하나의 소스 루트 아래에 형제 디렉터리로 체크아웃된 소스 저장소가 필요합니다. PHP 8.1 빌드는 nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, 그리고 nextpdf-Pro(Pro용)를 읽습니다. PHP 7.4 빌드는 nextpdf만 읽습니다. scripts/merge-sources.php를 기준으로 검증되었습니다.

1단계 — 드라이런

드라이런은 모든 단계를 보고 전용 모드로 실행합니다. 병합은 복사할 대상을 나열합니다. Rector는 실행 대상만 안내되고 실제로 실행되지는 않습니다. Composer 생성, 에셋 복사, 검증 단계는 수행할 작업을 출력합니다. 아무것도 기록되지 않습니다. 가장 빠른 확인 방법이므로 소스 레이아웃과 플래그가 올바른지 확인하려면 이 명령을 먼저 실행하세요.

composer build:dry

composer build:dry는 php scripts/build.php --dry-run으로 해석됩니다. composer.jsonscripts와 scripts/build.php(각 단계의 dryRun 분기)를 기준으로 검증되었습니다. 기본 플래그를 사용하면 대상은 php81이고 소스 루트는 스크립트 기본값입니다. 2단계에서 보듯 둘 다 재정의할 수 있습니다.

드라이런이 누락된 소스 저장소를 보고하면 즉시 실패하고 해당 저장소 이름을 표시합니다. 계속하기 전에 소스 레이아웃을 수정하세요. /integrations/backport/troubleshooting/을 참고하세요.

2단계 — 전체 PHP 8.1 빌드

PHP 8.1 빌드는 여러 단계를 차례로 실행합니다. core에 프레임워크 어댑터와 tcpdf 호환성 레이어를 더해 병합합니다. 단일 패스 Rector 구성을 실행합니다. nextpdf/backportcomposer.json을 생성합니다. 라이선스를 복사하고, CHANGELOG.md를 작성하며, 생성된 PHP 파일 수를 셉니다.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

scripts/build.php CLI 진입점을 기준으로 검증되었습니다. 다섯 단계가 순서대로 실행됩니다: 소스 병합, Rector 다운그레이드 실행, composer.json 생성, 정적 에셋 복사, 출력 검증. 각 단계는 성공하면 체크 표시를 출력합니다. 처음 실패한 단계가 빌드를 중단하고 해당 오류를 출력합니다. Pro를 제외하려면 --no-pro를 추가하세요.

성공하면 오케스트레이터가 경과 시간과 출력 경로를 출력합니다. Pro가 포함된 경우 Pro 출력 경로도 함께 출력합니다. 출력 디렉터리에는 src/, tests/, replace 맵과 폴리필 요구 사항을 선언하는 생성된 composer.json, LICENSE, 그리고 CHANGELOG.md가 포함됩니다.

3단계 — 전체 PHP 7.4 빌드

PHP 7.4 빌드는 core 전용이며 2패스 파이프라인을 실행합니다. 패스는 enum 전처리, 캐시 정리, Rector 이후 보정, 그리고 전체 다운그레이드입니다.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

scripts/build.php를 기준으로 검증되었습니다. 여기서 --target=php74는 core 전용을 강제하고 Pro를 비활성화하며, runRector()는 2패스 경로를 선택합니다. 생성된 composer.json은 >=7.4 <8.1 제약이 있으며, nextpdf/core만 대체하고, 8.2–8.5 폴리필 위에 PHP 8.0 및 8.1 폴리필을 추가합니다.

4단계 — 출력 읽기

검증 단계는 output/src의 PHP 파일 수를 세고, 그 수가 0이면 실패합니다. 로컬 인터프리터는 대상 런타임이 아니라 빌드 호스트의 최신 PHP이므로, 구문 검사를 로컬에서 실행하지 않습니다. 실제 대상 런타임에서 검증할 수 있도록 Docker 명령을 출력합니다. scripts/build.php(validateOutput())를 기준으로 검증되었습니다.

완전히 검증하려면 대상 PHP에서 구문 검사를 실행하세요. 릴리스 워크플로는 정확히 이 작업을 수행합니다. PHP 8.1(또는 PHP 7.4)에서 출력을 구문 검사한 다음, 지원 매트릭스 전반에서 설치하고 실행합니다. /integrations/backport/production-usage/을 참고하세요.

빌드한 결과물

아티팩트	빌드 단계	제약	대체 대상
`nextpdf/backport` (PHP 8.1)	2단계	`>=8.1 <8.5`	core + artisan + laravel + symfony + codeigniter + compat-legacy
`nextpdf/backport-pro` (PHP 8.1)	2단계, Pro 포함 시	`>=8.1 <8.5`	`nextpdf/pro`
`nextpdf/backport` (PHP 7.4)	3단계	`>=7.4 <8.1`	`nextpdf/core`

scripts/adjust-composer.php를 기준으로 검증되었습니다.

다음 단계

/integrations/backport/production-usage/ — 이를 이벤트 기반 릴리스 워크플로에 연결합니다.
/integrations/backport/configuration/ — 이 명령들의 기반이 되는 규칙과 플래그 레퍼런스입니다.
/integrations/backport/troubleshooting/ — 각 단계 실패와 그 의미를 설명합니다.