Development and Packaging

Development workflow, QA targets, and packaging options for tc-lib-pdf

Updated:

Table of contents

Composer is how tc-lib-pdf is normally installed. This page covers the other side: working on the library itself, and building the RPM and DEB packages that some deployment models need.

Development Workflow

Use the project Makefile as the main entry point for local development tasks:

# Install all development dependencies
make deps

# List all available Make targets
make help

# Run the full quality pipeline (dependency checks, formatting, lint, static analysis, tests)
make qa

# Run the same checks and produce the coverage report
make qa-coverage

# Generate one sample per conformance mode and run the external validators (if installed)
make preflight

Build artifacts and reports are written to target/.

Preflight Matrix

make preflight builds one sample PDF for every PDF/A, PDF/X and PDF/UA mode, each carrying the metadata its mode requires, and fails if generating a sample raises a warning. It then runs whatever validators are on the machine:

  • qpdf --check for the structural check.
  • verapdf against the matching PDF/A flavour (1a, 1b, 2a, 2b, 2u, 3a, 3b, 3u) and PDF/UA flavour (ua1, ua2).
  • The command in PDFX_VALIDATOR_CMD, when set, for the PDF/X samples.

veraPDF has no PDF/X profile, so PDF/X samples get the structural check and that optional hook only. Reports land under target/preflight/report/.

A passing matrix is not a compliance claim: that needs profile-specific preflight policies and review by your own validation authority.

Packaging

Composer is the default distribution channel. For system-level deployments, RPM and DEB packages are also available:

make rpm   # build RPM package  -> target/RPM/
make deb   # build DEB package  -> target/DEB/

When using the RPM or DEB package, bootstrap the library with its system autoloader:

require_once '/usr/share/php/Com/Tecnick/Pdf/autoload.php';

When To Use These Targets

  • Use make deps when working on the library itself rather than consuming it as a dependency.
  • Use make qa before opening pull requests or validating larger refactors, and make qa-coverage when you also need the coverage report.
  • Use make preflight when you need external standards validation of the PDF/A, PDF/X and PDF/UA output.
  • Use make rpm or make deb only when your deployment model relies on system packages instead of Composer installs.

Security Configuration Note

tc-lib-pdf restricts both remote and local resource loading.

  • Remote HTTP/HTTPS fetches are disabled unless you set fileOptions.allowedHosts.
  • Local file reads for internal library IO are controlled by fileOptions.allowedPaths, and reads triggered by rendered HTML, CSS, or SVG markup by fileOptions.markupAllowedPaths.
  • Supplying either key replaces the computed defaults, so include every required local asset directory.

For the full fileOptions reference and examples, see the remote resources guide below.

Previous: /docs/fonts/

Overview: /docs/

Next: /docs/enums/