NextPDF 백포트 빌더 문제 해결

이 도구는 빌드 도구이며 런타임 의존성이 아닙니다. 이 페이지의 모든 증상은 유지 관리자 또는 CI 호스트에서 발생하는 빌드 시점 조건입니다. 이러한 조건은 다운스트림 애플리케이션에서 나타나지 않습니다.

한눈에 보기

빌드는 정해진 순서대로 다섯 단계를 실행합니다. 첫 번째 실패 지점에서 멈추고 단계 이름과 메시지를 출력합니다. 단계 이름을 확인한 뒤 아래에서 원인을 찾으십시오. 단계는 소스 병합, Rector 다운그레이드 실행, composer.json 생성, 정적 자산 복사, 출력 검증 순서입니다. scripts/build.php(run() 및 step())를 기준으로 검증되었습니다.

단계: 소스 병합

”Source repo '' not found at: ”

병합 단계는 복사하기 전에 예상되는 모든 소스 저장소를 검증합니다. 누락된 저장소의 이름과 경로를 표시한 뒤 중단합니다. PHP 8.1 대상은 nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, 그리고 — Pro가 포함된 경우 — nextpdf-Pro를 예상합니다. PHP 7.4 대상은 nextpdf만 예상합니다. scripts/merge-sources.php(run() 검증 루프, __construct() 저장소 맵)를 기준으로 검증되었습니다.

해결 방법: --source-dir에 전달한 경로 아래에 위의 정확한 디렉터리 이름으로 저장소를 형제 디렉터리로 체크아웃하십시오. 드라이런은 읽게 될 모든 저장소를 나열합니다. 전체 빌드 전에 레이아웃을 확인할 때 사용하십시오.

단계: Rector 다운그레이드 실행

Rector가 0이 아닌 코드로 종료됨

오케스트레이터는 Rector failed on <label> (exit code: N)를 보고한 뒤 멈춥니다. 레이블은 어느 패스가 실패했는지를 나타냅니다 — public package, pro package, enum pre-processing, 또는 full downgrade입니다. scripts/build.php(runRectorPass())를 기준으로 검증되었습니다.

enum 기본값에서 기본 매개변수 리졸버 크래시 (PHP 7.4)

PHP 7.4 대상이 2 패스인 이유가 바로 이것입니다. Rector의 기본 매개변수 값 리졸버는 생성자 프로모션 기본값으로 사용된 enum 케이스에서 크래시합니다. 패스 1(rector-php74-enums.php)은 먼저 enum을 상수 목록 클래스로 변환합니다. 그러면 패스 2의 전체 패스는 enum 케이스 기본값을 전혀 보지 않습니다. 오케스트레이터를 우회하여 enum이 포함된 소스에 대해 전체 PHP 7.4 구성을 직접 실행하면 이 크래시가 발생합니다. scripts/build.php(runRector() 주석 및 2 패스 시퀀스) 및 rector/config/rector-php74-enums.php를 기준으로 검증되었습니다.

벤치마크 스크립트가 Rector를 크래시시킴

rector-php81.php와 rector-php74.php는 */tests/Benchmark/*를 건너뜁니다. 이러한 스크립트는 Rector가 확인할 수 없는 외부 PDF 라이브러리를 참조하므로 기본 매개변수 리졸버가 크래시합니다. 벤치마크 경로가 처리된다면 건너뛰기 글로브가 누락되었거나 경로가 달라진 것입니다. withSkip() 호출을 기준으로 검증되었습니다.

`MHASH_XXH*` 크래시 (PHP 7.4)

rector-php74.php는 DowngradeHashAlgorithmXxHashRector를 건너뜁니다. 해당 내장 규칙은 xxHash 상수에서 크래시합니다. 소스는 xxHash를 사용하지 않으므로 건너뛰어도 안전합니다. rector/config/rector-php74.php(withSkip())을 기준으로 검증되었습니다.

단계: Rector 후 수정 작업 (PHP 7.4 전용)

수정 작업은 두 패스 사이에서 실행됩니다. enum을 클래스로 변환하는 규칙이 남긴 패턴을 다시 작성합니다. PHP 7.4 출력에 EnumClass::Case->value, ->name, 인스턴스 메서드로 호출된 이전 enum 메서드, 또는 확인되지 않은 타입에 대한 명명된 인수와 관련된 구문 분석 오류가 있다면, 수정 작업이 해당 패턴을 매칭하지 못한 것입니다. 여기에는 clone-with 제한도 적용됩니다: 인수 매칭은 비재귀적이므로 중첩된 괄호가 있는 재정의 값은 다시 작성되지 않습니다. scripts/build.php(postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) 및 rector/rules/DowngradeCloneWithRector.php(문서화된 제한)를 기준으로 검증되었습니다.

단계: composer.json 생성

이 단계는 처리된 src/와 tests/를 빌드 임시 디렉터리에서 출력 디렉터리로 이동합니다. 그런 다음 생성된 composer.json를 씁니다. 여기서 발생하는 실패는 거의 항상 파일 시스템 조건 때문입니다: 출력 디렉터리에 쓸 수 없거나, Rector가 아무것도 생성하지 않아 빌드 임시 트리가 누락된 경우입니다. scripts/build.php(adjustComposer(), moveTree())을 기준으로 검증되었습니다.

단계: 정적 자산 복사

이 단계는 코어 소스 저장소에서 LICENSE를 복사하고 생성된 CHANGELOG.md를 씁니다. 라이선스가 없으면 복사를 조용히 건너뛰고 빌드는 계속됩니다; 변경 로그는 항상 작성됩니다. 여기서 발생하는 실패는 빌드 도중 출력 디렉터리에 쓸 수 없게 되었음을 나타냅니다. scripts/build.php(copyStaticAssets())을 기준으로 검증되었습니다.

단계: 출력 검증

”Output src/ directory not found” / “No PHP files found in output”

검증에는 비어 있지 않은 output/src가 필요합니다. 비어 있는 트리는 병합 단계가 아무것도 복사하지 않았거나 파일 이동이 실패했음을 의미합니다. scripts/build.php(validateOutput())을 기준으로 검증되었습니다.

”Syntax validation: skipped (requires PHP runtime)”

이것은 오류가 아니라 예상된 동작입니다. 빌드 호스트는 대상 런타임이 아니라 최신 PHP를 실행하므로, 로컬 단계는 파일 수만 세고 실제 구문 검사용 Docker 명령을 출력합니다. 기준이 되는 구문 게이트는 실제 대상 런타임에서 실행되는 릴리스 워크플로의 빌드 후 php -l 단계입니다. scripts/build.php(validateOutput()) 및 .github/workflows/build.yml(PHP 8.1 / PHP 7.4 구문 검사 단계)을 기준으로 검증되었습니다.

알려진 제한 사항

이러한 제한은 다운그레이드 방식에 본질적으로 내재되어 있습니다. 규칙과 프로젝트 README.md의 “Known Limitations”를 기준으로 검증되었습니다:

Readonly 속성이 제거됩니다. clone-with 확장의 명시적 속성 할당이 이전 런타임에서 허용되도록 readonly가 제거됩니다. 다운그레이드된 출력에서는 불변성이 더 이상 런타임에 의해 강제되지 않습니다.
#[Override]는 PHP 8.1에서 강제되지 않습니다. 어트리뷰트는 남아 있을 수 있지만 이전 런타임은 이에 따라 동작하지 않습니다.
PHP 7.4 대상은 코어 전용입니다. 프레임워크 어댑터, tcpdf 호환성 계층, 그리고 Pro는 빌드 스크립트의 구성상 PHP 7.4 배포판에 포함되지 않습니다.
Pro는 별도 패키지이며 PHP 8.1 전용입니다. PHP 7.4용 Pro 빌드는 없습니다.
Clone-with 인수 매칭은 비재귀적입니다. 중첩된 괄호를 포함하는 재정의 값은 변환되지 않으며, 문자열 배열 키만 속성 이름으로 해석됩니다.

/integrations/backport/configuration/ — 규칙 및 플래그 참조.
/integrations/backport/production-usage/ — CI 게이트 및 릴리스 레인.