Contributing

Contributing

The library lives entirely under build/. All commands must be run from that directory, not from the repository root.

Setup

git clone https://github.com/dragonofmercy/phppdf.git
cd build/
composer install

Commands

Command	What it does
composer check	PHPStan level max + full PHPUnit suite (unit + golden)
composer analyse	PHPStan only
composer test	PHPUnit only (1,000+ tests across unit + golden)

Run a single test file:

vendor/bin/phpunit tests/Unit/PageMarginsTest.php

Run a single test by name:

vendor/bin/phpunit --filter testSomeBehaviour

Requirements:

• PHP ^8.4
• PHPStan runs at level: max on src/ and tests/. New code must pass with zero errors. Do not add @phpstan-ignore to silence a finding - add a real accessor instead (e.g. if PHPStan reports an onlyWritten property, expose a getter).
• PHPUnit is configured with failOnWarning="true" and failOnRisky="true": a warning counts as a test failure.

Golden tests

Fixtures under tests/Golden/fixtures/ are byte-compared to a fresh render on every test run. Any change to rendering output - even an apparently harmless refactor that leaves the PDF visually identical - breaks the suite. This is intentional:

• It catches accidental output drift (operator order changes, whitespace shifts in streams, etc.).
• It documents intended changes: when you do change rendering on purpose, you regenerate the fixtures and the commit diff shows exactly what bytes changed.

Inputs (fonts, raster images used by the generators) live under tests/Golden/assets/. The fixtures/ directory is output-only. Fixtures are organised in sub-folders by category: doc/, page/, markdown/, form/, barcode/1d/, barcode/2d/, svg/<topic>/.

When you intentionally change generator output, rebuild the fixtures and commit them alongside the code:

php tests/Golden/regenerate.php

Each golden test also has a paired qpdf --check step. It auto-skips when qpdf is not on PATH, so the suite always passes on a minimal CI environment. When present, qpdf validates structural integrity: xref table, stream lengths, and object references. This means even a byte-identical fixture would be caught if you somehow produced a broken xref.

Installing qpdf:

• Linux: sudo apt-get install qpdf
• macOS: brew install qpdf
• Windows: choco install qpdf

Generating the standard font metrics

The 12 PHP files in src/Font/Metrics/ are generated from Adobe Type 1 AFM source files. Place the AFM files in bin/afm-source/ (that directory is gitignored), then run:

php bin/generate-font-metrics.php

The script applies the WinAnsi glyph-name mapping and emits one PHP file per font. You only need this if you are modifying the Standard 14 font metric data.

See also

• Architecture