NextPDF 백포트 부팅과 디스커버리

빌드 도구입니다 — 런타임 의존성이 아닙니다. 이 문서는 메인테이너나 CI 호스트에서 빌더를 부트스트랩하는 방식을 설명합니다. 다운스트림 애플리케이션은 이 코드를 절대 로드하지 않습니다.

한눈에 보기

빌더에는 프레임워크도, 의존성 주입 컨테이너도, 서비스 프로바이더 자동 디스커버리도 없습니다. require_once와 Composer의 PSR-4 오토로더로 연결된 PHP CLI 스크립트 모음입니다. 여기서 “디스커버리”는 두 가지 구체적인 의미를 가집니다. 병합 단계가 어떤 소스 리포지터리를 읽는지, 그리고 오케스트레이터가 대상에 맞는 Rector 구성을 어떻게 선택하는지입니다.

빌드 파이프라인 개요

오케스트레이터는 scripts/build.php입니다. 부팅 후 정해진 순서대로 다섯 단계를 실행합니다. 각 단계에는 게이트가 적용되므로 첫 번째 실패에서 빌드가 중단됩니다.

소스 병합 — 소스 리포지터리를 하나의 트리로 복사합니다.
Rector 다운그레이드 실행 — PHP 8.1은 단일 패스로, PHP 7.4는 두 번의 패스와 추가 보정 작업으로 처리합니다.
composer.json 생성 — 생성된 패키지 매니페스트와 replace 맵을 함께 작성합니다.
정적 자산 복사 — 라이선스와 생성된 변경 로그를 복사합니다.
출력 검증 — 생성된 PHP 파일 수를 확인합니다. 최종 기준이 되는 구문 게이트는 이후 CI에서 실행됩니다.

scripts/build.php(run(), step())를 기준으로 검증되었습니다. 규칙 선택에 대한 세부 사항은 /integrations/backport/configuration/에 있으며, CI 게이트는 /integrations/backport/production-usage/에 있습니다.

소스 모듈의 디스커버리

소스 디스커버리는 매니페스트 기반이 아닙니다. scripts/merge-sources.php 안의 고정된 맵을 사용하며, 리포지터리 이름을 키로 삼고 대상에 따라 선택합니다.

PHP 8.1 대상의 경우 맵은 nextpdf(코어), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter이며, Pro가 포함될 때는 nextpdf-Pro가 더해집니다. PHP 7.4 대상의 경우 맵은 nextpdf만으로 축소됩니다. 각 리포지터리는 --source-dir 루트 아래의 형제 디렉터리로 해석됩니다. 예상되는 모든 리포지터리는 복사 전에 검증되며, 누락된 항목이 있으면 이름과 경로를 함께 표시하고 병합을 중단합니다. scripts/merge-sources.php(MergeSources::__construct(), run())를 기준으로 검증되었습니다.

병합 과정에서는 코어를 src/에 배치하고, 각 어댑터를 해당 네임스페이스의 하위 디렉터리(src/Artisan/, src/Laravel/ 등) 아래에 배치합니다. Pro는 자체 패키지로 생성될 수 있도록 별도의 pro/src/ 트리로 들어갑니다. MergeSources(mergeCore(), mergeArtisan(), mergePro())를 기준으로 검증되었습니다.

부팅 시퀀스

scripts/build.php가 CLI SAPI에서 호출됩니다. 이 스크립트는 merge-sources.php와 adjust-composer.php를 require_once합니다.
CLI 진입점은 getopt()로 옵션을 읽습니다 — --version, --source-dir, --output-dir, --target, --dry-run, --no-pro.
Build 인스턴스가 생성됩니다. 생성자는 --target을 ['php74', 'php81']에 대해 검증하며, 잘못된 값이 있으면 어떤 작업이 시작되기 전에 InvalidArgumentException을 발생시킵니다. PHP 7.4 대상의 경우 코어 전용을 강제하고 Pro를 비활성화합니다.
Build::run()은 다섯 단계를 실행하며, 성공 시 상태 0으로, 첫 번째 실패 시 1로 종료합니다.

scripts/build.php(CLI 진입점, Build::__construct(), run())를 기준으로 검증되었습니다.

컨테이너 바인딩

해당 사항 없음. 빌더는 의존성 주입 컨테이너도, 프레임워크 서비스 컨테이너도 없는 CLI 도구입니다. 연결은 명시적인 require_once와 NextPDF\Backport\(규칙) 및 NextPDF\Backport\Scripts\(스크립트)의 Composer PSR-4 오토로딩으로 이루어집니다. composer.jsonautoload 및 scripts/build.php의 require_once 문을 기준으로 검증되었습니다.

구성 해석 순서

구성 파일은 없습니다. 구성은 CLI 플래그의 집합이며, 스크립트에 내장된 기본값을 기준으로 해석됩니다.

제공된 경우 CLI 플래그.
getopt() 파싱 블록의 기본값(예를 들어, 대상은 기본적으로 php81, 버전은 2.0.0).
생성자가 대상으로부터 파생하는 동작(PHP 7.4는 --no-pro와 무관하게 코어 전용 및 Pro 비활성화를 강제합니다).

scripts/build.php(CLI 진입점 및 Build::__construct())를 기준으로 검증되었습니다. 전체 플래그 레퍼런스는 /integrations/backport/configuration/에 있습니다.

진단

오케스트레이터 자체가 진단 표면입니다. 드라이 런(composer build:dry)을 실행하면, 아무것도 기록하지 않고 읽을 예정인 소스 리포지터리와 각 단계의 의도를 출력합니다. 각 단계는 성공 체크 표시 또는 이름이 명시된 실패를 출력합니다. 별도의 diagnose 하위 명령은 없으며, bin/ 진입점도 없습니다. 빌더는 scripts/build.php 또는 해당 Composer 스크립트 별칭을 통해 호출됩니다. scripts/build.php(step(), dryRun 분기), scripts/merge-sources.php(run() 드라이 런 경로), 그리고 composer.jsonscripts를 기준으로 검증되었습니다.

함께 보기

/integrations/backport/overview/ — 빌더가 무엇이며 무엇을 생성하는지.
/integrations/backport/integration/ — 빌드 호스트 통합 계약.
/integrations/backport/configuration/ — Rector 구성 및 플래그 레퍼런스.
/integrations/backport/troubleshooting/ — 단계별 실패 레퍼런스.