Backport Builder API reference
At a glance
Section titled “At a glance”The Backport Builder is build tooling, not a runtime library. Its public interface consists of the build command set (scripts/build.php and its composer build* wrappers), the four script-level classes behind it (Build, MergeSources, AdjustComposer, ValidateBuildContract), the three Rector configuration files, the three custom Rector rules, and the generated package contract (nextpdf/backport and nextpdf/backport-pro). Run it on a build or continuous integration (CI) host to turn modern NextPDF source into a downgraded distribution. Never add it to an application.
If you are new, start with composer build:dry (which resolves to php scripts/build.php --dry-run). It exercises every stage in report-only mode without writing files, so you can confirm the source layout and flags before a real build. The first “Common tasks” sample shows the same command.
Common tasks
Section titled “Common tasks”You will most often use this package to run builds on a build host. Each sample below is a single command, verified against scripts/build.php and composer.json.
Validate the pipeline without writing anything (the safe first run):
composer build:dryIt resolves to php scripts/build.php --dry-run. It runs merge, Rector, composer-generation, asset-copy, and validation in report-only mode, and copies nothing.
Produce the full PHP 8.1 distribution (nextpdf/backport, plus nextpdf/backport-pro when Pro source is present):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputThis merges core, the framework adapters, and the tcpdf-compatibility layer. It runs the single Rector pass for the PHP 8.1 target and writes the generated package tree to ./output. Add --no-pro to skip the Pro package.
Produce the core-only PHP 7.4 distribution (the two-pass enum pipeline):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 forces core-only output, disables Pro, and runs enum pre-processing, post-Rector fix-ups, and the full PHP 7.4 downgrade pass.
Command surfaces
Section titled “Command surfaces”Use this table when you need exact signatures, flags, and exit behavior for the build entrypoints and the script-level classes that drive a build.
| Symbol | Parameters | Default behavior | Returns | Throws or fails with | Notes |
|---|---|---|---|---|---|
scripts/build.php | Target, version, source paths, output paths, and flags as documented by the script. | Uses branch-specific target defaults. | Generated package tree. | Non-zero exit and stage-specific error output. | Main build entrypoint. Run on a build host, not in an application. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Version, source directory, output directory, target runtime lane, Pro inclusion flag, dry-run flag. | Targets PHP 8.1, includes Pro except for PHP 7.4, and writes unless dry-run is enabled. | Build | InvalidArgumentException for unsupported target; stage errors during run(). | Script-level class behind scripts/build.php. |
Build::run() | none. | Validates the contract, merges sources, adjusts composer.json metadata, and runs Rector passes. | bool | Returns false for expected stage failures; may throw for unexpected filesystem or runtime errors. | CI should fail on false. |
composer build:dry | Composer script wrapper. | Dry-run build validation. | Exit status and logs. | Non-zero exit on build or validation failure. | Used by CI gates. |
scripts/merge-sources.php | Source checkout paths and merge target. | Merges selected source packages for the target runtime. | Merged source tree. | Missing source, unsupported target, filesystem failure. | Keep source refs aligned with the release tag. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Source base directory, output directory, Pro inclusion flag, dry-run flag, core-only flag. | Merges all configured repositories, or only core when coreOnly is true. | MergeSources | Invalid source or output paths during run. | Script-level class behind scripts/merge-sources.php. |
MergeSources::run() | none. | Copies and normalizes selected source trees into the build target. | bool | Returns false for expected merge failures. | Logs can be read with getLog(). |
MergeSources::getLog() | none. | Returns accumulated stage log entries. | array | none expected. | Use for CI diagnostics. |
scripts/adjust-composer.php | Generated composer.json metadata and version. | Writes package constraints and replace entries for generated output. | Adjusted composer.json. | Invalid version or missing generated files. | Owns generated package identity. |
AdjustComposer::__construct(string $version, string $target = 'php81') | Version string and target lane. | PHP 8.1 target. | AdjustComposer | Invalid target errors in generation paths. | Used by build scripts and tests. |
AdjustComposer::generatePublicComposer() | none. | Produces metadata for nextpdf/backport. | array | none expected. | Pure generation API for tests. |
AdjustComposer::generateProComposer() | none. | Produces metadata for nextpdf/backport-pro. | array | none expected. | Pure generation API for proprietary build lane. |
AdjustComposer::writePublicComposer(string $outputDir) | Output directory. | Writes generated public composer.json. | void | Filesystem errors. | Use only in generated output directories. |
AdjustComposer::writeProComposer(string $proOutputDir) | Pro output directory. | Writes generated Pro composer.json. | void | Filesystem errors. | Requires the Pro output tree to exist. |
ValidateBuildContract::__construct(string $repoRoot) | Repository root. | Uses the provided repository root as the contract base. | ValidateBuildContract | none expected. | Script-level contract validator. |
ValidateBuildContract::run() | none. | Checks required inputs and build assumptions. | bool | Returns false on contract failure. | Run before build output is trusted. |
Rector configuration
Section titled “Rector configuration”Use this table to see which Rector config file drives each target lane and where each pass fits in the PHP 8.1 single-pass or PHP 7.4 two-pass pipeline.
| Symbol | Parameters | Default behavior | Returns | Throws or fails with | Notes |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Source tree and Rector runtime. | Single-pass downgrade to PHP 8.1 target. | Transformed source. | Rector parse or transform failure. | Used for the PHP 8.1 distribution lane. |
rector/config/rector-php74-enums.php | Source tree and Rector runtime. | First PHP 7.4 pass for enum conversion. | Intermediate transformed source. | Rector parse or transform failure. | Runs before the full PHP 7.4 pass. |
rector/config/rector-php74.php | Intermediate source and Rector runtime. | Full PHP 7.4 downgrade pass. | PHP 7.4-compatible source. | Rector parse or transform failure. | Used for the PHP 7.4 distribution lane. |
Custom rules
Section titled “Custom rules”Use this table when you maintain or extend the three project-specific Rector rules and need each rule’s method contract and the syntax it transforms.
| Symbol | Parameters | Default behavior | Returns | Throws or fails with | Notes |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Properties or promoted parameters using asymmetric visibility. | Plain visibility compatible with older runtimes. | Preserves read visibility where possible. | Rector rule failure. | Setter restrictions are compile-time only and are removed in generated output. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | none. | Returns Rector rule metadata and examples. | RuleDefinition | none expected. | Keeps rule docs visible to Rector tooling. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | none. | Selects node types inspected by the rule. | array<class-string<Node>> | none expected. | Scope should stay narrow for deterministic transforms. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | AST node. | Converts asymmetric visibility where present. | `Node | null` | Rector rule failure. |
DowngradeCloneWithRector | clone() with property overrides. | Clone plus explicit property assignments. | Uses generated temporary variables. | Rector rule failure. | Must run after readonly-property downgrades. |
DowngradeCloneWithRector::getRuleDefinition() | none. | Returns rule metadata and examples. | RuleDefinition | none expected. | Used by Rector diagnostics. |
DowngradeCloneWithRector::getNodeTypes() | none. | Selects return and expression nodes. | array<class-string<Node>> | none expected. | Keeps the rule focused on clone-with syntax. |
DowngradeCloneWithRector::refactor(Node $node) | AST node. | Rewrites clone-with into clone plus assignments. | `array | null` | Rector rule failure. |
DowngradeTraitConstantsRector | Trait constants and references to them. | Static properties and property references. | Preserves visibility where possible. | Rector rule failure. | Removes final because older properties cannot be final. |
DowngradeTraitConstantsRector::getRuleDefinition() | none. | Returns rule metadata and examples. | RuleDefinition | none expected. | Used by Rector diagnostics. |
DowngradeTraitConstantsRector::getNodeTypes() | none. | Selects trait and class-constant-fetch nodes. | array<class-string<Node>> | none expected. | Keeps the rule limited to trait constants. |
DowngradeTraitConstantsRector::refactor(Node $node) | AST node. | Rewrites trait constants and references into compatible properties. | `Node | null` | Rector rule failure. |
Generated package contract
Section titled “Generated package contract”Use this table to see what the builder emits: the package names downstream projects install and the package that carries the Pro distribution.
| Produced package | Runtime role | Notes |
|---|---|---|
nextpdf/backport | Generated open-source runtime distribution. | Replaces selected nextpdf/* packages for the target runtime. |
nextpdf/backport-pro | Generated proprietary Pro distribution when Pro source is present. | Published separately from the open-source package. |
Development notes
Section titled “Development notes”- The builder consumes source releases and emits generated artifacts. Do not patch generated output as the source of truth.
- Each custom rule must have fixture tests before it enters the build pipeline.
- Release jobs must validate generated output on the target runtime, not only on the build host.