NextPDF Backport Builder quickstart

Build tooling — not a runtime dependency. Run this walkthrough on a maintainer or continuous-integration (CI) host. A downstream project consumes the archive you produce. These steps never run on an application server.

At a glance

You run three commands. First, run the dry-run to confirm the pipeline is wired without touching files. Next, run a full PHP 8.1 build. Then run a full PHP 7.4 build. Each step uses one command, backed by a Composer script or a documented scripts/build.php invocation.

Prerequisites

• A build host on PHP >=8.4 <9.0, with build dependencies installed (composer install, no --no-dev). See /integrations/backport/install/.
• The source repositories checked out as sibling directories under one source root. The PHP 8.1 build reads nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, and nextpdf-Pro (for Pro). The PHP 7.4 build reads only nextpdf. Verified against scripts/merge-sources.php.

Step 1 — dry-run

The dry-run runs every stage in report-only mode. The merge stage lists the files it would copy. The command announces Rector but does not run it. The composer-generation, asset-copy, and validation stages print their intent. Nothing is written. Run this first because it is the fastest way to confirm your source layout and flags.

composer build:dry

composer build:dry resolves to php scripts/build.php --dry-run. Verified against composer.jsonscripts and scripts/build.php (the dryRun branch in each stage). With the default flags, the target is php81, and the source root uses the script default. You can override either value, as shown in step 2.

If the dry-run reports a missing source repository, it stops immediately and names that repository. Fix the source layout before you continue. See /integrations/backport/troubleshooting/.

Step 2 — full PHP 8.1 build

The PHP 8.1 build runs several steps in order. It merges core with the framework adapters and the tcpdf-compatibility layer. It runs the single-pass Rector configuration. It generates nextpdf/backportcomposer.json. It copies the license, writes CHANGELOG.md, and counts the emitted PHP files.

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

Verified against the scripts/build.php command-line interface (CLI) entry point. The five stages run in order: merge sources, run Rector downgrade, generate composer.json, copy static assets, validate output. Each stage prints a check mark on success. The first failing stage stops the build and prints its error. To exclude Pro, add --no-pro.

On success, the orchestrator prints the elapsed time and output path. When Pro is included, it also prints the Pro output path. The output directory then contains src/, tests/, a generated composer.json that declares the replace map and polyfill requirements, LICENSE, and CHANGELOG.md.

Step 3 — full PHP 7.4 build

The PHP 7.4 build is core-only and uses the two-pass pipeline. It runs enum pre-processing, clears the cache, applies the post-Rector fix-ups, and then performs the full downgrade.

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

Verified against scripts/build.php. Here, --target=php74 forces core-only, disables Pro, and makes runRector() select the two-pass path. The generated composer.json carries the constraint >=7.4 <8.1. It replaces only nextpdf/core and adds the PHP 8.0 and 8.1 polyfills on top of the 8.2–8.5 polyfills.

Step 4 — read the output

The validation stage counts PHP files in output/src and fails if the count is zero. It does not run a syntax check locally. The local interpreter is the build host’s modern PHP, not the target runtime. Instead, it prints the Docker command to validate against the real target runtime. Verified against scripts/build.php (validateOutput()).

To validate fully, run the syntax check under the target PHP. The release workflow follows the same path. It syntax-checks the output on PHP 8.1 (or PHP 7.4), then installs and exercises it across the support matrix. See /integrations/backport/production-usage/.

What you have built

Artifact	Built by	Constraint	Replaces
nextpdf/backport (PHP 8.1)	Step 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Step 2, when Pro included	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Step 3	>=7.4 <8.1	nextpdf/core

Verified against scripts/adjust-composer.php.

Next

• /integrations/backport/production-usage/ — Wire this into the event-driven release workflow.
• /integrations/backport/configuration/ — the rule and flag reference behind these commands.
• /integrations/backport/troubleshooting/ — every stage failure and its meaning.