NextPDF Backport Builder overview

Build tooling, not a runtime dependency. NextPDF maintainers use this package to produce PHP 8.1+ and PHP 7.4+ compatible distributions of NextPDF. Applications must never add it as a runtime dependency.

At a glance

The NextPDF Backport Builder is build infrastructure for producing a downgraded distribution of the NextPDF ecosystem for PHP runtimes older than the development baseline. NextPDF is written for a modern PHP version and uses syntax that earlier interpreters reject. The builder passes the source through Rector, an engine that transforms abstract syntax trees, and emits packages whose syntax a PHP 8.1 or PHP 7.4 runtime accepts.

The Composer package name is nextpdf/backport-builder. It declares "type": "project" and carries no NextPDF runtime dependency. Its requirements are limited to the build engine (rector/rector), static analysis (phpstan/phpstan), the test runner (phpunit/phpunit), and a set of symfony/polyfill-* packages used in the generated output. The repository-root composer.json verifies this.

What this package is not

This repository does not contain the NextPDF engine. It contains the rules and scripts that transform that engine into a backported form. That separation has three practical effects:

You do not install this to render PDFs. Install nextpdf/backport, the artifact this builder produces. Keep the builder on the maintainer or continuous integration (CI) host.
You do not develop against the generated code. The generated distribution is a machine-produced, read-only artifact. Send bug reports and feature requests to the original nextpdf/* source repositories.
The output ships as version tags, not as branches of this repository. The release pipeline tags the generated tree and attaches archives to a GitHub release.

What it produces

The builder emits Composer packages whose names and licenses are fixed by scripts/adjust-composer.php:

Produced package	License	Scope	Built when
`nextpdf/backport`	`Apache-2.0`	Core, framework adapters, and the tcpdf-compatibility layer for the PHP 8.1 target	Always
`nextpdf/backport-pro`	`proprietary`	The Pro module, emitted as a separate package	PHP 8.1 target, when Pro source is present and Pro is not excluded

The nextpdf/backport package declares Composer replace entries so that, after installation, it satisfies the original package constraints. For the PHP 8.1 target, the replaced packages are nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter, and nextpdf/compat-legacy. For the PHP 7.4 target, only nextpdf/core is replaced because the PHP 7.4 build is core-only. scripts/adjust-composer.php (buildReplace()) verifies this.

A consumer’s autoloader resolves the merged tree through one PHP Standards Recommendation 4 (PSR-4) prefix, NextPDF\, mapped to src/. PSR-4 maps a namespace prefix to a base directory and resolves each fully qualified class name to a file beneath it; see PHP Framework Interop Group (PHP-FIG) PSR-4. The Pro package maps NextPDF\Pro\ to its own src/.

Supported PHP matrix

The matrix below covers only what the Rector configurations and build scripts enforce. The build host always runs a modern PHP version. The output targets an older one.

Concern	Value	Evidence
Build host PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
CI build/test PHP	8.5	`.github/workflows/0-ci.yml`, `build.yml` (`shivammathur/setup-phpphp-version: '8.5'`)
PHP 8.1 target output constraint	`>=8.1 <8.5`	`scripts/adjust-composer.php` (`generatePublicComposer()`)
PHP 7.4 target output constraint	`>=7.4 <8.1`	`scripts/adjust-composer.php` (`generatePublicComposer()`)
PHP 8.1 target scope	Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, separate)	`scripts/merge-sources.php`, `scripts/adjust-composer.php`
PHP 7.4 target scope	Core only	`scripts/build.php` (`--target=php74` forces core-only, Pro disabled)

The PHP 8.1 build is validated on PHP 8.1, 8.2, 8.3, and 8.4. The PHP 7.4 build is validated on PHP 7.4 and 8.0. The validate-php81 and validate-php74 job matrices in .github/workflows/build.yml verify this. These are the runtimes the pipeline exercises. They are an observed validation set, not a conformance claim.

The dual-branch model

This repository has no main branch. PHP74 is the default branch, and PHP81 is the second permanent branch. Your branch determines two things: the local build’s default target and the source set that is merged. Apply a change that affects both targets to each branch through its own pull request. The CI workflow runs on both PHP74 and PHP81. This is verified against git branch -a and .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).

How a release happens

The release path is event-driven. When the NextPDF source organization publishes a release tag, a repository-dispatch event of type source-release triggers the build workflow. The workflow checks out each source repository at the matching tag, runs the pipeline, syntax-checks the output on the target runtime, validates it across the support matrix, and attaches the archives to a GitHub release. The version tag follows Semantic Versioning: a version number is MAJOR.MINOR.PATCH over a declared public API (Semantic Versioning 2.0.0 §2). .github/workflows/build.yml verifies this.

Where to go next

/integrations/backport/install/ — how to install the builder on a build host, and how consumers install the produced package.
/integrations/backport/configuration/ — Rector configurations, custom rules, and build flags.
/integrations/backport/quickstart/ — a source-backed dry run and full build invocation.
/integrations/backport/production-usage/ — how to wire the builder into a release workflow.
/integrations/backport/troubleshooting/ — failure modes the pipeline guards against and how to read them.
/integrations/backport/security-and-operations/ — supply-chain posture, the trust boundary, and operational guarantees.
/integrations/backport/boot-and-discovery/ — how the builder discovers source modules and boots.
/integrations/backport/integration/ — the build-host integration contract.