백포트 빌더 API 레퍼런스

한눈에 보기

백포트 빌더는 런타임 라이브러리가 아니라 빌드 도구입니다. 공개 인터페이스는 빌드 명령 집합(scripts/build.php 및 해당 composer build* 래퍼), 이를 뒷받침하는 네 개의 스크립트 수준 클래스(Build, MergeSources, AdjustComposer, ValidateBuildContract), 세 개의 Rector 구성 파일, 세 개의 사용자 정의 Rector 규칙, 그리고 생성된 패키지 계약(nextpdf/backport 및 nextpdf/backport-pro)으로 이루어집니다. 최신 NextPDF 소스를 다운그레이드된 배포본으로 변환할 때는 빌드 호스트 또는 CI 호스트에서 이 도구를 실행합니다. 애플리케이션에는 절대 추가하지 않습니다.

처음이라면 여기서 시작하세요. composer build:dry를 실행합니다(실제로는 php scripts/build.php --dry-run으로 실행됩니다). 파일을 쓰지 않고 보고 전용 모드로 모든 단계를 실행하므로 실제 빌드 전에 소스 레이아웃과 플래그를 확인할 수 있습니다. 아래의 첫 번째 “일반 작업” 예제가 바로 이 과정을 보여 줍니다.

일반 작업

이 패키지에서 가장 자주 하는 작업은 빌드 호스트에서 빌드를 호출하는 것입니다. 아래의 각 예제는 단일 명령이며, scripts/build.php 및 composer.json의 소스를 기준으로 검증되었습니다.

파일을 전혀 쓰지 않고 파이프라인을 검증합니다(안전한 첫 실행).

composer build:dry

실제로 실행되는 명령은 php scripts/build.php --dry-run입니다. 병합, Rector, composer 생성, 자산 복사, 검증을 보고 전용 모드로 실행하며 아무것도 복사하지 않습니다.

전체 PHP 8.1 배포본을 생성합니다(nextpdf/backport, 그리고 Pro 소스가 있는 경우 nextpdf/backport-pro).

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

코어와 함께 프레임워크 어댑터 및 tcpdf 호환 계층을 병합하고, PHP 8.1 대상을 위한 단일 Rector 패스를 실행한 후, 생성된 패키지 트리를 ./output에 씁니다. Pro 패키지를 건너뛰려면 --no-pro를 추가합니다.

코어 전용 PHP 7.4 배포본을 생성합니다(2단계 열거형 파이프라인).

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

--target=php74는 코어 전용 출력을 강제하고 Pro를 비활성화한 다음, 열거형 전처리, Rector 이후 보정, 전체 PHP 7.4 다운그레이드 패스를 실행합니다.

명령 인터페이스

빌드 진입점과 빌드를 구동하는 스크립트 수준 클래스의 정확한 시그니처, 플래그, 종료 동작이 필요할 때는 이 표를 참조하세요.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 조건	참고
`scripts/build.php`	스크립트에 문서화된 대상, 버전, 소스 경로, 출력 경로, 플래그입니다.	브랜치별 대상 기본값을 사용합니다.	생성된 패키지 트리입니다.	0이 아닌 종료 코드 및 단계별 오류 출력입니다.	기본 빌드 진입점입니다. 애플리케이션이 아니라 빌드 호스트에서 실행합니다.
`Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)`	버전, 소스 디렉터리, 출력 디렉터리, 대상 런타임 레인, Pro 포함 플래그, 드라이런 플래그입니다.	PHP 8.1 대상이며, PHP 7.4를 제외하고 Pro가 포함됩니다. 드라이런이 활성화되어 있지 않으면 파일을 씁니다.	`Build`	지원되지 않는 대상에서는 `InvalidArgumentException`이 발생하며, `run()` 중에 단계 오류가 발생합니다.	스크립트 수준 클래스로, `scripts/build.php` 뒤에 있습니다.
`Build::run()`	없음.	계약을 검증하고, 소스를 병합하고, `composer.json` 메타데이터를 조정하고, Rector 패스를 실행합니다.	`bool`	예상된 단계 실패에는 `false`를 반환하며, 예기치 않은 filesystem/runtime 오류에는 예외를 발생시킬 수 있습니다.	CI는 `false`일 때 실패해야 합니다.
`composer build:dry`	Composer 스크립트 래퍼입니다.	드라이런 빌드 검증입니다.	종료 상태 및 로그입니다.	빌드 또는 검증 실패 시 0이 아닌 종료 코드입니다.	CI 게이트에서 사용됩니다.
`scripts/merge-sources.php`	소스 체크아웃 경로와 병합 대상입니다.	대상 런타임을 위해 선택된 소스 패키지를 병합합니다.	병합된 소스 트리입니다.	누락된 소스, 지원되지 않는 대상, 파일 시스템 실패입니다.	소스 참조를 릴리스 태그와 일치하게 유지하세요.
`MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)`	소스 기준 디렉터리, 출력 디렉터리, Pro 포함 플래그, 드라이런 플래그, 코어 전용 플래그입니다.	구성된 모든 저장소를 병합하거나, `coreOnly`가 true이면 코어만 병합합니다.	`MergeSources`	실행 중에 잘못된 소스 또는 출력 경로가 감지됩니다.	스크립트 수준 클래스로, `scripts/merge-sources.php` 뒤에 있습니다.
`MergeSources::run()`	없음.	선택된 소스 트리를 빌드 대상으로 복사하고 정규화합니다.	`bool`	예상된 병합 실패에 대해 `false`를 반환합니다.	로그는 `getLog()`으로 읽을 수 있습니다.
`MergeSources::getLog()`	없음.	누적된 단계 로그 항목을 반환합니다.	`array`	예상되는 예외 없음.	CI 진단에 사용합니다.
`scripts/adjust-composer.php`	생성된 `composer.json` 메타데이터와 버전입니다.	생성된 출력의 패키지 제약 조건과 replace 항목을 씁니다.	조정된 `composer.json`입니다.	잘못된 버전 또는 누락된 생성 파일입니다.	생성된 패키지 식별 정보를 관리합니다.
`AdjustComposer::__construct(string $version, string $target = 'php81')`	버전 문자열과 대상 레인입니다.	PHP 8.1 대상입니다.	`AdjustComposer`	생성 경로에서 잘못된 대상 오류가 발생합니다.	빌드 스크립트와 테스트에서 사용됩니다.
`AdjustComposer::generatePublicComposer()`	없음.	다음의 메타데이터를 생성합니다: `nextpdf/backport`.	`array`	예상되는 예외 없음.	테스트를 위한 순수 생성 API입니다.
`AdjustComposer::generateProComposer()`	없음.	다음의 메타데이터를 생성합니다: `nextpdf/backport-pro`.	`array`	예상되는 예외 없음.	독점 빌드 레인을 위한 순수 생성 API입니다.
`AdjustComposer::writePublicComposer(string $outputDir)`	출력 디렉터리입니다.	생성된 공개 `composer.json`을 씁니다.	`void`	파일 시스템 오류입니다.	생성된 출력 디렉터리에서만 사용하세요.
`AdjustComposer::writeProComposer(string $proOutputDir)`	Pro 출력 디렉터리입니다.	생성된 Pro `composer.json`을 씁니다.	`void`	파일 시스템 오류입니다.	Pro 출력 트리가 있어야 합니다.
`ValidateBuildContract::__construct(string $repoRoot)`	저장소 루트입니다.	제공된 저장소 루트를 계약 기준으로 사용합니다.	`ValidateBuildContract`	예상되는 예외 없음.	스크립트 수준 계약 검증기입니다.
`ValidateBuildContract::run()`	없음.	필수 입력과 빌드 가정을 확인합니다.	`bool`	계약 실패 시 `false`를 반환합니다.	빌드 출력을 신뢰하기 전에 실행합니다.

Rector 구성

어떤 Rector 구성 파일이 어떤 대상 레인을 구동하는지, 그리고 각 패스가 PHP 8.1 단일 패스 또는 PHP 7.4 2단계 파이프라인의 어느 위치에 있는지 알아야 할 때 이 표를 사용하세요.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 조건	참고
`rector/config/rector-php81.php`	소스 트리와 Rector 런타임입니다.	PHP 8.1 대상으로의 단일 패스 다운그레이드입니다.	변환된 소스입니다.	Rector 구문 분석 또는 변환 실패입니다.	PHP 8.1 배포 레인에 사용됩니다.
`rector/config/rector-php74-enums.php`	소스 트리와 Rector 런타임입니다.	열거형 변환을 위한 첫 번째 PHP 7.4 패스입니다.	중간 변환 소스입니다.	Rector 구문 분석 또는 변환 실패입니다.	전체 PHP 7.4 패스 전에 실행됩니다.
`rector/config/rector-php74.php`	중간 소스와 Rector 런타임입니다.	전체 PHP 7.4 다운그레이드 패스입니다.	PHP 7.4 호환 소스입니다.	Rector 구문 분석 또는 변환 실패입니다.	PHP 7.4 배포 레인에 사용됩니다.

사용자 정의 규칙

세 개의 프로젝트별 Rector 규칙을 유지 관리하거나 확장할 때 각 규칙의 메서드 계약과 변환 대상 구문이 필요하면 이 표를 참조하세요.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 조건	참고
`DowngradeAsymmetricVisibilityRector`	비대칭 가시성을 사용하는 속성 또는 승격된 매개변수입니다.	이전 런타임과 호환되는 일반 가시성으로 변환합니다.	가능한 경우 읽기 가시성을 유지합니다.	Rector 규칙 실패입니다.	setter 제한은 컴파일 타임에만 적용되며 생성된 출력에서는 제거됩니다.
`DowngradeAsymmetricVisibilityRector::getRuleDefinition()`	없음.	Rector 규칙 메타데이터와 예제를 반환합니다.	`RuleDefinition`	예상되는 예외 없음.	규칙 문서를 Rector 도구에서 볼 수 있는 상태로 유지합니다.
`DowngradeAsymmetricVisibilityRector::getNodeTypes()`	없음.	규칙이 검사할 노드 유형을 선택합니다.	`array<class-string<Node>>`	예상되는 예외 없음.	결정적 변환을 위해 범위를 좁게 유지해야 합니다.
`DowngradeAsymmetricVisibilityRector::refactor(Node $node)`	AST 노드입니다.	있는 경우 비대칭 가시성을 변환합니다.	`Node	null`	Rector 규칙 실패입니다.
`DowngradeCloneWithRector`	`clone()` 속성 재정의를 포함하는 구문입니다.	복제와 명시적 속성 할당으로 변환합니다.	생성된 임시 변수를 사용합니다.	Rector 규칙 실패입니다.	readonly 속성 다운그레이드 후에 실행해야 합니다.
`DowngradeCloneWithRector::getRuleDefinition()`	없음.	규칙 메타데이터와 예제를 반환합니다.	`RuleDefinition`	예상되는 항목 없음.	Rector 진단에서 사용됩니다.
`DowngradeCloneWithRector::getNodeTypes()`	없음.	반환 노드와 표현식 노드를 선택합니다.	`array<class-string<Node>>`	예상되는 예외 없음.	규칙이 clone-with 구문에 집중되도록 유지합니다.
`DowngradeCloneWithRector::refactor(Node $node)`	AST 노드입니다.	clone-with를 복제와 할당으로 다시 작성합니다.	`array	null`	Rector 규칙 실패입니다.
`DowngradeTraitConstantsRector`	트레이트 상수와 해당 참조입니다.	정적 속성과 속성 참조로 변환합니다.	가능한 경우 가시성을 유지합니다.	Rector 규칙 실패입니다.	이전 속성은 final이 될 수 없으므로 `final`을 제거합니다.
`DowngradeTraitConstantsRector::getRuleDefinition()`	없음.	규칙 메타데이터와 예제를 반환합니다.	`RuleDefinition`	예상되는 예외 없음.	Rector 진단에서 사용됩니다.
`DowngradeTraitConstantsRector::getNodeTypes()`	없음.	트레이트 노드와 클래스 상수 페치 노드를 선택합니다.	`array<class-string<Node>>`	예상되는 예외 없음.	규칙이 트레이트 상수에만 적용되도록 유지합니다.
`DowngradeTraitConstantsRector::refactor(Node $node)`	AST 노드입니다.	트레이트 상수와 참조를 호환되는 속성으로 다시 작성합니다.	`Node	null`	Rector 규칙 실패입니다.

생성된 패키지 계약

빌더가 무엇을 생성하는지 확인하려면 이 표를 사용하세요. 다운스트림 프로젝트가 실제로 설치하는 패키지 이름과 Pro 배포본을 담는 패키지를 보여 줍니다.

생성된 패키지	런타임 역할	참고
`nextpdf/backport`	생성된 오픈 소스 런타임 배포본입니다.	대상 런타임을 위해 선택된 `nextpdf/*` 패키지를 대체합니다.
`nextpdf/backport-pro`	Pro 소스가 있을 때 생성되는 독점 Pro 배포본입니다.	오픈 소스 패키지와 별도로 게시됩니다.

개발 참고 사항

빌더는 소스 릴리스를 소비하고 생성된 아티팩트를 내보냅니다. 생성된 출력을 기준 소스로 간주해 패치하지 마세요.
각 사용자 정의 규칙은 빌드 파이프라인에 들어가기 전에 픽스처 테스트가 있어야 합니다.
릴리스 작업은 빌드 호스트뿐만 아니라 대상 런타임에서도 생성된 출력을 검증해야 합니다.