Installing the NextPDF Backport Builder

Install this build tooling on a maintainer workstation or a continuous integration (CI) runner. It is NOT a runtime dependency. A downstream application never installs the builder; it installs the package the builder produces.

At a glance

Two audiences install different things:

• A maintainer or CI operator clones this repository and installs its build dependencies. Install nextpdf/backport-builder only in this context.
• A downstream application on an older PHP runtime installs the generated nextpdf/backport package from its release channel. It never touches this repository.

This page covers both workflows. Read the section that matches your role.

Build-host installation

Requirements

Dependency	Constraint	Source of truth
PHP	>=8.4 <9.0	composer.jsonrequire.php
Composer	2.6+	CONTRIBUTING.md environment table
rector/rector	^2.0	composer.jsonrequire-dev
phpstan/phpstan	^2.1	composer.jsonrequire-dev
phpunit/phpunit	^13.0	composer.jsonrequire-dev

The CI workflow provisions PHP 8.5 for both the build and the dry-run job. Any build host running a PHP version inside >=8.4 <9.0 satisfies the Composer constraint. The PHP parser must accept the newest syntax used by the source. Verified against .github/workflows/0-ci.yml.

Steps

1. Clone the repository, then check out the branch for the target you want to build. PHP74 is the default branch and produces the PHP 7.4, core-only distribution. PHP81 produces the PHP 8.1 distribution with all adapters.

   git clone https://github.com/nextpdf-labs/backport.git
   cd backport
   git checkout PHP74

2. Install the build dependencies. Do not pass --no-dev: the Rector engine, PHPStan, and PHPUnit live in require-dev, and the build cannot run without them.

   composer install --prefer-dist --no-progress

3. Confirm that the toolchain resolves. The analyse script runs PHPStan at level 10 over rector/rules and scripts. A clean run shows that the build code itself is sound before you produce output.

   composer analyse

4. Run the rule fixture tests. Each custom Rector rule has a fixture suite that asserts the exact before/after transformation.

   composer test

After step 4, the host is ready to build. Go to /integrations/backport/quickstart/ for the dry-run and full-build invocations.

Source-tree expectation

The build merges several source repositories into one tree. Place them as sibling directories under a single source root; the merge script addresses each directory by name. For the PHP 8.1 target, it reads nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, and nextpdf-Pro when Pro is included. For the PHP 7.4 target, it reads only nextpdf. Verified against scripts/merge-sources.php (MergeSources::__construct()). Supply the source root with --source-dir. See /integrations/backport/configuration/ for the flag reference.

Downstream consumption of the produced package

When you support a project on an older PHP runtime, install the produced distribution, not this builder.

PHP 8.1 to 8.3

composer require nextpdf/backport

The installed package declares the constraint >=8.1 <8.5 and replaces nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, and nextpdf/compat-legacy. Application code keeps importing the NextPDF\ namespace unchanged. The package autoloads the merged tree through the single PHP Standard Recommendation 4 (PSR-4) prefix NextPDF\ mapped to src/. A PSR-4 autoloader appends the relative class name to a base directory registered for the prefix (PHP-FIG PSR-4). Verified against scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

PHP 7.4 to 8.0

composer require nextpdf/backport

The PHP 7.4 distribution is core only. It declares the constraint >=7.4 <8.1 and replaces only nextpdf/core. Framework adapters, the tcpdf-compatibility layer, and Pro are not included in the PHP 7.4 distribution. Verified against scripts/adjust-composer.php and scripts/build.php (PHP 7.4 target forces core-only). A project that needs a framework adapter needs PHP 8.1 or newer.

Pro

composer require nextpdf/backport-pro

The Pro distribution is a separate package, nextpdf/backport-pro, with a proprietary license. It requires nextpdf/backport at the matching major.minor and adds phpseclib/phpseclib ^3.0. It is produced only for the PHP 8.1 target. Verified against scripts/adjust-composer.php (generateProComposer()).

The PHP 7.4 distribution and the Pro distribution are mutually exclusive: by construction of the build script, there is no PHP 7.4 Pro build.

Polyfills in the produced package

The generated composer.json requires symfony/polyfill-* packages so that newer standard-library functions can resolve on the target runtime. The PHP 8.1 target requires polyfills for PHP 8.2 through 8.5. The PHP 7.4 target also requires the PHP 8.0 and 8.1 polyfills. These are runtime dependencies of the produced package, not of the builder. Verified against scripts/adjust-composer.php (generatePublicComposer()).

Next

• /integrations/backport/configuration/ — Rector configuration, custom rules, and the build flag reference.
• /integrations/backport/quickstart/ — your first dry-run and full build.