README

PHP library for building structured PDFs using TCPDF and FPDI.

Provides a Builder/Modelizer pattern for generating multi-page PDFs with YAML-driven configuration, automatic config inheritance, color/font management, and unit conversion utilities.

Requirements

• PHP >= 8.1
• TCPDF ^6.3
• FPDI ^2.6
• Symfony YAML ^7.2

Installation

composer require jdz/pdfbuilder

PDF 1.5+ support (optional)

FPDI natively handles PDF documents up to version 1.4. To import PDF 1.5+ files (those using compressed cross-references and object streams), you need the commercial FPDI PDF-Parser add-on from Setasign.

1. Purchase a license at setasign.com

2. Add the Setasign private Composer repository to your project's composer.json:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://www.setasign.com/downloads/"
        }
    ]
}

1. Require the package (you will be prompted for your Setasign credentials):

composer require setasign/fpdi_pdf-parser

Once installed, FPDI automatically detects the parser and enables PDF 1.5+ support — no code changes needed.

Architecture

Core classes

Built-in modelizers

Supporting classes

Configuration

Modelizer configs are YAML files stored in a config/ directory. They support inheritance via the inherits key.

Example: modelizer.formation.yml

inherits:
  - base
  - catalogue

colors:
  pictoNewColor: "#cc0000"
  pictoCpfColor: "#01a6ba"

marginTop: 120
marginBottom: 62
pagePadding: 18

The base config provides defaults for all colors, fonts, and font sizes:

colors:
    white: "#FFFFFF"
    black: "#000000"
    textColor: "#000000"
    linkColor: "#0b8181"

fonts:
    default: helvetica
    black: helvetica
    light: helvetica

h1Fsize: 17
h2Fsize: 16
pFsize: 9
borderWidth: 0.1

Configs are loaded via Builder::loadModelizerConfig('formation'), which resolves the full inheritance chain and merges colors, fonts, and all other properties.

Usage

1. Create a Modelizer (page layout)

use JDZ\Pdf\Modelizer;

class InvoiceModelizer extends Modelizer
{
    protected bool $printHeader = true;
    protected bool $printFooter = true;

    public function Header(): void
    {
        $this->pdf->SetFont('helvetica', 'B', 14);
        $this->pdf->Cell(0, 10, 'INVOICE', 0, 1, 'C');
    }

    public function Page(): void
    {
        $invoice = $this->data->get('invoice');

        $this->pdf->SetFont('helvetica', '', 10);
        $this->pdf->Cell(0, 8, 'Client: ' . $invoice->client, 0, 1);
        $this->pdf->Cell(0, 8, 'Amount: ' . $invoice->amount, 0, 1);
    }

    public function Footer(): void
    {
        $this->pdf->SetY(-15);
        $this->pdf->SetFont('helvetica', '', 8);
        $this->pdf->Cell(0, 10, 'Page ' . $this->pdf->getAliasNumPage(), 0, 0, 'C');
    }
}

2. Create a Builder

use JDZ\Pdf\Builder;
use JDZ\Pdf\Pdf;
use JDZ\Pdf\Data;

class InvoiceBuilder extends Builder
{
    private object $invoiceData;

    public function setInvoiceData(object $data): void
    {
        $this->invoiceData = $data;
    }

    public function build(): void
    {
        $pdf = new Pdf();
        $pdf->SetTitle('Invoice');
        $pdf->set('izSourcesPath', $this->sourcesPath);

        // Load YAML config with inheritance
        $modelizerData = new Data();
        $modelizerData->sets($this->loadModelizerConfig('invoice'));
        $modelizerData->set('invoice', $this->invoiceData);

        // Create modelizer, render page
        $modelizer = new InvoiceModelizer($pdf, $modelizerData);
        $modelizer->load();
        $modelizer->toPdf();

        // Write PDF to disk
        $pdf->Output($this->targetPath, 'F');
    }
}

3. Generate the PDF

use JDZ\Utils\Data as jData;

$data = new jData();
$data->set('label', 'Invoice #001');

$builder = new InvoiceBuilder(
    sourcesPath: __DIR__ . '/resources/',
    targetPath: __DIR__ . '/files/invoice.pdf',
    data: $data
);

$builder->setInvoiceData((object)[
    'client' => 'Acme Corp',
    'amount' => '1 500,00 EUR',
]);

$builder->build();

Custom fonts

Register fonts in your Builder's build() method before creating the Modelizer:

$pdf->set('font', (object)[
    'name' => 'montserrat',
    'styles' => [null, 'B', 'I', 'BI'],
]);

Font definition files (PHP arrays) go in your resources/fonts/ directory. The library ships with Helvetica, Courier, Montserrat, and Merienda.

Color manipulation

// Get a color clone and lighten it
$color = $data->getColorObject('theme');
$color->lighten(20);
$lightTheme = $color->toArray(); // [r, g, b]

The Color class supports hex-to-RGB conversion, HSV transformations, and lighten()/darken() methods.

Examples

The examples/ directory contains complete working examples:

Run an example:

php examples/cv.php
# Output: examples/files/cv-1.pdf

License

MIT - See LICENSE for details.