Migrating off FPDF, from Cell coordinates to markup

What ports and what does not

The data layer. Nothing else. FPDF documents are sequences of Cell calls with explicit widths, heights and line-break flags, and a subclassed Header and Footer that run per page. There is no styling, no template and no separation between layout and content: the code interleaves them, which is what makes these modules hard to read and easy to underestimate. The upside is that the arithmetic is unambiguous, so it makes a precise specification for the markup you write.

What the call becomes

AddPage, SetFont, Cell, MultiCell and Output collapse into a single POST to /v1/pdf with html. The constructor's orientation and format arguments become options.landscape and options.format. SetMargins becomes options.margin. SetAutoPageBreak becomes the bottom margin plus break-inside rules. AliasNbPages, which FPDF substituted at output time to give a total page count, becomes the totalPages class in the footer markup. The Header and Footer methods become options.header_html and options.footer_html.

Side by side

The old shape and the new one, with the parts that have no counterpart called out in comments rather than quietly omitted.

<?php
// Before
class Invoice extends FPDF {
    function Header() {
        $this->SetFont('Arial', 'B', 12);
        $this->Cell(0, 10, 'Invoice', 0, 1, 'L');
    }
    function Footer() {
        $this->SetY(-15);
        $this->SetFont('Arial', '', 8);
        $this->Cell(0, 10, 'Page ' . $this->PageNo() . '/{nb}', 0, 0, 'C');
    }
}
$pdf = new Invoice('P', 'mm', 'A4');
$pdf->AliasNbPages();
$pdf->AddPage();
$pdf->SetFont('Arial', '', 10);
foreach ($rows as $r) {
    $pdf->Cell(80, 6, $r['desc'], 'B', 0, 'L');
    $pdf->Cell(30, 6, $r['qty'],  'B', 0, 'R');
    $pdf->Cell(30, 6, $r['amt'],  'B', 1, 'R');
}
$out = $pdf->Output('S');

// After: the widths in the Cell calls are the column widths.
$html = $twig->render('invoice.html.twig', ['rows' => $rows]);

$response = $client->post('https://api.pdfpipe.xyz/v1/pdf', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('PDFPIPE_KEY')],
    'json' => [
        'html' => $html,
        'options' => [
            'format' => 'A4',
            'header_html' => '<div style="font:bold 12pt Arial">Invoice</div>',
            'footer_html' => '<div style="font-size:8pt;text-align:center">Page '
                           . '<span class="pageNumber"></span>/'
                           . '<span class="totalPages"></span></div>',
        ],
    ],
]);

/* The Cell widths 80, 30, 30 in millimetres are the table's column
   widths. Read them out of the loop rather than guessing:
     td.desc { width: 80mm } td.qty { width: 30mm } td.amt { width: 30mm }
   The 'B' border argument is border-bottom. The 1 in the last call is
   the line break, which is the end of the table row. */

The CSS delta, in both directions

What the old engine accepted that a current one does not, and what it refused that a current one wants. The second direction is the one people forget, and it is where the value of the migration is.

• There is nothing to migrate and everything to write. The Cell arguments are the specification: the widths are column widths in millimetres, the border flags are borders, and the alignment characters are text-align.
• The line-break flag on each Cell marks where a row ends, which is how you recover the table structure from a flat sequence of calls.
• SetAutoPageBreak's trigger margin becomes the bottom page margin, and the manual page-break checks scattered through the loop become break-inside rules.
• Everything else in CSS is new capability that the old document could not express at all.

What changes without anything erroring

The dangerous list. Each of these produces a different document and no diagnostic, so none of them are caught by a test that only checks the render succeeded.

• Everything visual, because it is a rewrite.
• Page count.
• Fonts, from FPDF's core font set and its own font files to @font-face.
• Any manual page-break arithmetic in the loop, which stops running and is replaced by pagination that works differently.

What to diff before cutting over

Diff the extracted text against the old output to prove the content came across. Then check the column widths against the Cell arguments, because those numbers are the only record of the intended layout and transcribing them is where an error hides.

The one thing that always breaks

The total page count. FPDF's AliasNbPages worked by writing a placeholder string into the document and replacing it at output, and templates use the raw brace token in their footer text. Copied into markup, that token is just characters, so the footer prints the literal placeholder next to the page number rather than a total.

Frequently asked

Other migrations

The nearest neighbours first, then others that started from the same kind of tool, because the model matters more than the language.