Ga naar inhoud
getnextpdf.com

Migreren van FPDF naar NextPDF

Deze handleiding helpt je een FPDF-gebaseerde codebase over te zetten naar NextPDF core. FPDF is een van de breedst ingezette oude PHP Portable Document Format (PDF)-bibliotheken, en het tekenoppervlak ervan — AddPage, SetFont, Cell, MultiCell, Write, Text, Image, Output aangedreven door een handmatige x/y-cursor — wordt schoon toegewezen aan NextPDF’s eigen cell/text-API, omdat NextPDF’s tekenmethodes op laag niveau dezelfde FPDF/TCPDF-afstamming volgen. NextPDF is geen drop-in FPDF-kloon: het is een moderne PDF 2.0-engine met strikte types, lettertype-subsetting, ondertekening, PDF/A en toegankelijkheid (tagged PDF). De twee echte verschuivingen zijn het eenheidsmodel (NextPDF werkt in PDF-punten; FPDF gebruikt standaard millimeters) en de uitvoerwerkwoorden (een getypeerde OutputDestination-enum in plaats van FPDF’s tekens 'I'/'D'/'F'/'S').

Er is geen FPDF-klasse-shim in core. Herschrijf elke aanroepplek met de werkwoordtoewijzing. Als je in plaats daarvan de kleinste initiële wijziging voor een TCPDF 6.x-codebase wilt, zie de TCPDF-compatibiliteitsadapter, die een bijna-bron-compatibel drop-in-pad meelevert; FPDF heeft geen zo’n adapter.

Terminal window
composer require nextpdf/core:^3

Houd setasign/fpdf (of je fpdf/fpdf) geïnstalleerd tijdens de migratie. Verwijder het na de definitieve overstap (zie veilige migratievolgorde).

FPDF en NextPDF delen hetzelfde mentale model: een document opgebouwd uit pagina’s, een cursor (de huidige x/y-positie), en werkwoorden die op of voorbij die cursor tekenen. SetXY, Cell, Ln en MultiCell lezen en muteren de cursor in beide bibliotheken, dus de meeste procedurele FPDF-code vertaalt regel voor regel.

De verschillen zijn opzettelijk, niet toevallig:

  • Eenheden. De constructor van FPDF (new FPDF($orientation, $unit, $size)) gebruikt standaard millimeters. NextPDF werkt in PDF-punten (1 pt = 1/72 in, ISO 32000-2 §7). Er is geen documentbrede eenheidsknop — converteer mm naar punten één keer (pt = mm * 72 / 25.4).
  • De Y-richting blijft voor jou hetzelfde. Net als FPDF plaatsen NextPDF’s gebruikerscoördinaten y = 0 aan de paginatop en nemen ze naar beneden toe, dus cursorrekenwerk port rechtstreeks. NextPDF converteert intern naar de PDF-eigen oorsprong linksonder.
  • Constructie is expliciet. FPDF vouwt oriëntatie, eenheid en grootte in de constructor; NextPDF neemt een onveranderlijk value object NextPDF\Core\Config (paginagrootte, marges, lettertypemap) en een expliciete addPage().
  • Altijd Unicode, altijd subset. FPDF’s core-build is Latin-1 en heeft de tFPDF/UTF-8-variant nodig voor Unicode. NextPDF is overal UTF-8 en sluit lettertypen altijd in als subset-programma’s (ISO 32000-2 §9). FPDF’s AddFont/ lettertypemetriekbestanden hebben geen analoog; registreer een TrueType/OpenType-lettertypemap en selecteer de familie op naam.

De core-toegangspunten die hieronder worden gebruikt zijn Document::createStandalone(), Document::addPage(), Document::setFont(), Document::cell(), Document::multiCell(), Document::text(), Document::write(), Document::ln(), Document::image(), de cursoraccessors (setXY/setX/ setY/getX/getY), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, en het value object NextPDF\Core\Config. De volledige referentie voor deze core-teken-, tekst- en uitvoermethodes staat in de core-modules en de referentie-index, auto-gegenereerd uit PHPDoc. De Html-module is gerelateerde leesstof voor HTML-naar-PDF, niet de referentie voor de werkwoorden op deze pagina.

De openbare methodenamen van FPDF zijn al lang bestaand en bekend. De NextPDF-kolom hieronder is geverifieerd aan de hand van core-bronhandtekeningen (zie Bewijs / traceerbaarheid).

FPDFNextPDFOpmerkingen
new FPDF($orient, $unit, $size)Document::createStandalone($config)De constructorargumenten orientation/unit/size worden een NextPDF\Core\Config (pageSize, margins, fontsDirectory). Geen $unit — werk in punten. De standaardpagina van createStandalone() is A4 staand.
$pdf->AddPage($orient, $size)$doc->addPage($size, $orientation)Directe toewijzing. $size is een value object PageSize; $orientation is de enum Orientation (Portrait/Landscape).
$pdf->SetFont($family, $style, $size)$doc->setFont($family, $style, $size)Directe toewijzing. $style gebruikt dezelfde codes ''/'B'/'I'/'BI' (plus 'U' voor onderstreping).
$pdf->Cell($w, $h, $txt, $border, $ln, $align, $fill)$doc->cell($w, $h, $txt, $border, $newLine, $align, $fill)Directe toewijzing. $align is de enum Alignment (Left/Center/Right/Justify); $border accepteert bool of een 'LTRB'-string; $ln wordt de bool $newLine.
$pdf->MultiCell($w, $h, $txt, $border, $align, $fill)$doc->multiCell($w, $h, $txt, $border, $align)Breekt woorden af op werkelijke lettertypemetrieken. Geen $fill-argument; teken eerst een gevulde rect() als je een achtergrond nodig hebt.
$pdf->Write($h, $txt, $link)$doc->write($h, $txt, $link)Doorlopende tekst vanaf de cursor; $link voegt een URL-link-annotatie toe.
$pdf->Text($x, $y, $txt)$doc->text($x, $y, $txt)Tekst op absolute positie. Directe toewijzing.
$pdf->Ln($h)$doc->ln($h)Regelafbreking naar de linkermarge; 0 = standaard regelhoogte.
$pdf->Image($file, $x, $y, $w, $h)$doc->image($file, $x, $y, $w, $h)Directe toewijzing; $x/$y/$w/$h zijn nullable (null = huidige cursor / intrinsieke grootte).
$pdf->SetXY($x, $y) / SetX / SetY$doc->setXY($x, $y) / setX / setYDirecte toewijzing. getX()/getY() lezen de cursor.
$pdf->SetMargins($l, $t, $r)$doc->setMargins(new Margin($t, $r, $bottom, $l))Eén value object Margin; de constructorvolgorde is (top, right, bottom, left)niet FPDF’s (left, top, right). FPDF SetMargins heeft geen bottom-argument (de ondermarge komt van SetAutoPageBreak($auto, $margin)), dus kies $bottom zelf — vaak gelijk aan de bovenmarge, of geef de auto-page-break-marge door.
$pdf->SetAutoPageBreak($auto, $margin)$doc->setAutoPageBreak($auto, $margin)Directe toewijzing.
$pdf->SetDrawColor / SetFillColor / SetTextColor$doc->setDrawColor / setFillColor / setTextColorRGB (r, g, b), of één waarde voor grijswaarden.
$pdf->Line / Rect / SetLineWidth$doc->line / rect / setLineWidthDirecte toewijzing. rect() neemt een stijlstring ('S'/'F'/'DF').
$pdf->SetTitle/SetAuthor/SetSubject/SetKeywords/SetCreator$doc->setTitle/setAuthor/setSubject/setKeywords/setCreatorDirecte toewijzing. Komt terecht in het informatiewoordenboek / Extensible Metadata Platform (XMP) van ISO 32000-2 §14.
$pdf->Output($dest, $name)$doc->output($name, OutputDestination::…)FPDF-bestemmingstekens (I/D/F/S) worden toegewezen aan de enum OutputDestination; let op dat de argumentvolgorde verwisselt (naam eerst in NextPDF).
$pdf->Output('S')$doc->getPdfData()Retourneert de PDF-bytes.
$pdf->Output('F', $path)$doc->save($path)Schrijft naar een bestandspad.
$pdf->GetStringWidth($s)(geen openbare methode)De stringbreedte wordt intern berekend tijdens het afbreken van cell()/multiCell(); er is geen openbaar werkwoord voor meting per string. Stuur het afbreken via multiCell() in plaats van met de hand te meten.
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;
// FPDF:
// $pdf = new FPDF(); // mm, A4 portrait
// $pdf->AddPage();
// $pdf->SetFont('Arial', 'B', 16);
// $pdf->Cell(40, 10, 'Invoice');
// $pdf->Output('F', 'out.pdf');
// NextPDF — points, default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->setFont('Helvetica', 'B', 16.0);
$doc->cell(113.4, 28.3, 'Invoice', false, true, Alignment::Left); // ~40mm x ~10mm in points
$doc->save(__DIR__ . '/out.pdf');
echo "Wrote out.pdf\n";

Dit voorbeeld is afgestemd op examples/04-text-and-fonts.php. Het gebruikt een expliciete paginagrootte, marges, een geregistreerde lettertypemap, en het cursorgestuurde cellmodel dat een FPDF-codebase al gebruikt.

<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
// Equivalent of: new FPDF('P', 'mm', 'A4') + SetMargins(20, 16, 20)
// i.e. FPDF left=20mm, top=16mm, right=20mm. FPDF SetMargins has no bottom
// argument, so we pick bottom = top = 16mm. Convert each mm to points
// (pt = mm * 72 / 25.4): 16mm = 45.354pt, 20mm = 56.693pt.
// Margin constructor order is (top, right, bottom, left) — NOT FPDF's (L, T, R).
$config = new Config(
pageSize: new PageSize(595.276, 841.890, 'A4'),
margins: new Margin(45.354, 56.693, 45.354, 56.693), // top,right,bottom,left in points
fontsDirectory: __DIR__ . '/fonts',
);
$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->setAuthor('Finance');
$doc->addPage();
// SetFont + Cell, the FPDF way — but in points and with a real Unicode font.
$doc->setFont('DejaVuSans', 'B', 18.0);
$doc->setTextColor(30, 58, 138);
$doc->cell(0, 24.0, 'Quarterly Report', false, true, Alignment::Left);
$doc->setFont('DejaVuSans', '', 11.0);
$doc->setTextColor(0, 0, 0);
$doc->multiCell(0, 16.0, "Body text wraps on real font metrics. Unicode is "
. "native, so accented and non-Latin characters need no tFPDF variant — "
. "register the family in the fonts directory and select it by name.");
// Equivalent of $pdf->Output('D', 'report.pdf'):
$doc->output('report.pdf', OutputDestination::Download);
  • Eenheden. Elke numerieke coördinaat, breedte, hoogte en marge die je uit FPDF kopieert is standaard in millimeters. Vermenigvuldig met 72 / 25.4 om punten te krijgen, één keer, tijdens de port. De twee mengen mis-maatvoert stilzwijgend alles.
  • Argumentvolgorde van Output(). FPDF is Output($dest, $name); NextPDF is output($name, $dest). De bestemming is de enum OutputDestination, geen teken. Geef de voorkeur aan save() / getPdfData() voor bestands- / stringuitvoer.
  • Volgorde van SetMargins. FPDF is (left, top, right); het NextPDF-value-object Margin is (top, right, bottom, left). Herorden, transcribeer niet.
  • Lettertypen. FPDF’s AddFont() + .php-metriekbestanden hebben geen equivalent. Plaats het TrueType/OpenType-bestand in de lettertypemap en roep setFont() aan met de familienaam. De Base14-namen van Core (Helvetica, Times, Courier) herleiden zonder bestand; onder PDF/A of tagged PDF worden ze automatisch vervangen door een insluitbaar lettertype.
  • GetStringWidth. Er is geen openbare methode voor stringmeting. Als je FPDF-code strings meet om kolommen met de hand uit te lijnen, schakel dat blok dan over naar multiCell() (dat op metrieken afbreekt) of vastebreedte-cell()-aanroepen.

NextPDF stoot inhoud uit in één streaming-doorloop (architecture decision record ADR-001); het piekgeheugen volgt de documentgrootte, geen vastgehouden objectboom. Het budget voor het voorbeeld in deze handleiding is wall_ms: 2000, peak_mb: 128. Stuur voor lange documenten inhoud over addPage()-aanroepen — dezelfde lusvorm die een FPDF-rapport al gebruikt.

  • Metadata. SetTitle()/SetAuthor() worden toegewezen aan getypeerde setters die het informatiewoordenboek / XMP van ISO 32000-2 §14 schrijven. Bewaar daar nooit geheimen.
  • Afbeeldingspaden. image() wijst stream-wrapper-schema’s en ingesloten NUL-bytes af voordat het leest. Geef applicatie-beheerde paden door.
  • Geen code in het document. NextPDF voert geen scripts in het document uit; niets in FPDF verandert dat.
BeweringSpecificatieClausule
Paginaformaat/oriëntatie wordt toegewezen aan de paginagrensbox.ISO 32000-2§7
Lettertypen worden geschreven als embedded/subset lettertypeprogramma’s.ISO 32000-2§9
Titel- / metadata komen terecht in het informatiewoordenboek / XMP.ISO 32000-2§14
Lijnen, rechthoeken en afbeeldingen zijn content-stream-painting.ISO 32000-2§8

NextPDF produceert ISO 32000-2-inhoud; het claimt geen visuele identiteit met FPDF. Beoordeel de uitvoer opnieuw wanneer je van renderer wisselt.

Niet van toepassing. NextPDF core dekt het hier beschreven FPDF-migratiepad.


Teams die FPDF (of tFPDF) gebruiken voor server-side, procedurele PDF-generatie. Als je code een reeks AddPage / SetFont / Cell / MultiCell / Image / Output-aanroepen is, aangedreven door SetXY en Ln, dan dekt de werkwoordtoewijzing je hele oppervlak.

In scope: de FPDF-tekenwerkwoorden, het cursormodel, lettertypen, kleuren, lijnen en rechthoeken, metadata, en uitvoer. Buiten scope: FPDF’s AddFont-metriekbestand-tooling en FPDF-script-extensies van derden (barcodes, rotatie, bladwijzers) — wijs die toe aan de bijbehorende NextPDF-modules (Barcode, Transforms, Navigation), die hier niet worden behandeld.

Gedragscompatibiliteit, geen drop-in shim: core biedt geen FPDF-klasse-shim. Herschrijf elke aanroepplek. De werkwoorden liggen nauw in lijn omdat NextPDF’s cell/text-API FPDF/TCPDF-afstamming deelt, maar het eenheidsmodel, de Output-argumentvolgorde en de Margin/enum-types verschillen — dus een transcriptie is fout, een vertaling is goed.

FPDF-constructNextPDFOpmerkingen
$unit ('mm' standaard)(geen equivalent)Werk in PDF-punten. Converteer afmetingen met pt = mm * 72 / 25.4 één keer tijdens de port.
$orientation ('P'/'L')Orientation-enum op addPage(), of verwissel width/height van PageSizeLandschap = width > height.
$size ('A4', [w,h])Config->pageSize (value object PageSize)Benoemde formaten worden expliciete puntafmetingen; PageSize::A4()A0() en Letter/Legal-factories bestaan.
SetMargins($l, $t, $r)Config->margins (Margin VO)Constructorvolgorde (top, right, bottom, left).
AddFont($family, $style, $file)lettertypemap + setFont() op naamLaat het metriekbestand vallen; plaats de TTF/OTF in Config->fontsDirectory.
  • Lettertypemappen. FPDF’s AddFont-registratie per lettertype klapt samen tot een lettertypemap plus setFont()-familieovereenkomst. Begin met Config->fontsDirectory (het standaardzoekpad); registreer extra mappen via FontRegistry::addFontDirectory() of Document::addFontDirectory() wanneer lettertypen op meer dan één plek staan.
  • Altijd Unicode. Geen Latin-1-standaard en geen aparte tFPDF-build; UTF-8-invoer is de norm.
  • Maakt altijd subsets. NextPDF maakt altijd subsets van ingesloten lettertypen (ISO 32000-2 §9); FPDF’s keuzes voor lettertype-insluiting hebben geen equivalent en zijn niet nodig.
  • Herbaseline glyphs. Lettertype-overeenkomst en terugval zijn engine-specifiek; een FPDF-lettertypealias kan een exacte familienaam nodig hebben. Vervangingsverschillen zijn te verwachten, geen defecten.
  • Eenheidsconversie (mm → pt) — de meest voorkomende porting-fout; zie hierboven.
  • De Output-argumentvolgorde verwisselt en de bestemming wordt een enum.
  • Margin / Alignment / Orientation zijn getypeerde objecten/enums, geen tekens of positionele (l, t, r)-triples.
  • Geen openbare GetStringWidth — stuur het afbreken via multiCell().
  • Onafhankelijke rasterisatie — regelafbreking en paginering op dichte inhoud kunnen verschillen; herbaseline visuele diffs.

Dit zijn gedocumenteerde gedragsverschillen, geen defecten in een van beide engines.

  • FPDF $unit-selector — niet gemodelleerd (altijd punten).
  • AddFont() + .php/.z-metriekbestanden — vervangen door een lettertypemap.
  • GetStringWidth() — geen openbaar werkwoord voor stringmeting.
  • FPDF’s bestemmingstekens 'I'/'D'/'F'/'S' — vervangen door de OutputDestination-enum + save()/getPdfData().

Code die afhangt van deze zaken “migreert” niet verbatim. Druk hem opnieuw uit met de rijen hierboven.

  1. Voeg nextpdf/core toe naast FPDF; houd FPDF voorlopig geïnstalleerd.
  2. Kies één document met een laag risico. Converteer de constructor via de eenheidstoewijzing, en port daarna elk werkwoord met de werkwoordtoewijzing. Converteer elke mm-coördinaat naar punten.
  3. Plaats de lettertypen van het document in Config->fontsDirectory en selecteer ze op familienaam; laat de AddFont-aanroepen vallen.
  4. Genereer beide PDF’s voor dezelfde invoer en vergelijk ze visueel. Verschillen (lettertypevervanging, regelafbreking) zijn te verwachten voor onafhankelijke engines — accepteer ze per document.
  5. Vervang elke GetStringWidth-gebaseerde handmatige layout door multiCell() of vastebreedte-cell()-aanroepen.
  6. Herhaal per document, het laagste risico eerst; houd FPDF geïnstalleerd tot de laatste overstap.
  7. Verwijder FPDF uit composer.json na de definitieve overstap.
  • Maak een snapshot van de FPDF-uitvoer voor representatieve documenten voordat je code wijzigt (golden inputs; de bytes zullen verschillen).
  • Bepaal voor elk gemigreerd document de acceptatie met je eigen controle (visuele diff
    • tekstextractie). Het cell/lettertype-gedrag van NextPDF wordt getest door examples/04-text-and-fonts.php plus de core tests/ Font- en tekstuitvoersuites. De acceptatie van de migratie is documentspecifiek en blijft je verantwoordelijkheid.
  • Voeg per gemigreerd document een regressietest toe.

Elke gedragsbewering van NextPDF op deze pagina wordt onderbouwd door een in-repo bronhandtekening, voorbeeld of architecture decision record (ADR), of, voor PDF-formaateigenschappen, door de ISO 32000-2-clausules in de frontmatter citations: en de Conformiteit-tabel. FPDF-gedrag wordt alleen beweerd als “onafhankelijke engine — verwacht gedocumenteerde verschillen”; deze pagina claimt geen pariteit die een in-repo artefact niet bewijst.

NextPDF-gedragsbeweringIn-repo bewijs (pad)
AddPage wordt toegewezen aan addPage(?PageSize, Orientation): static.src/Core/Concerns/HasPages.php (addPage()).
SetFont($family, $style, $size) wordt toegewezen aan setFont(string, string, float): static; ''/'B'/'I'/'BI'/'U'-stijlen.src/Core/Concerns/HasTypography.php (setFont()).
Cell wordt toegewezen aan cell($w, $h, $txt, $border, $newLine, $align, $fill): static.src/Core/Concerns/HasTextOutput.php (cell()).
MultiCell wordt toegewezen aan multiCell($w, $h, $txt, $border, $align): static (metriek-gebaseerde afbreking).src/Core/Concerns/HasTextOutput.php (multiCell(), wrapText()).
Write/Text/Ln worden toegewezen aan write()/text()/ln().src/Core/Concerns/HasTextOutput.php (write(), text(), ln()).
SetXY/SetX/SetY/GetX/GetY worden direct toegewezen; SetMargins neemt een Margin VO.src/Core/Concerns/HasPages.php (setXY(), getX(), setMargins()); src/ValueObjects/Margin.php ((top, right, bottom, left)).
Image wordt toegewezen aan image($file, ?$x, ?$y, ?$w, ?$h): static; wijst scheme/NUL-paden af.src/Core/Concerns/HasImages.php (image(), assertImageFilePath()).
Line/Rect/SetLineWidth/SetDrawColor/SetFillColor/SetTextColor worden direct toegewezen.src/Core/Concerns/HasDrawing.php (line(), rect(), setLineWidth()); src/Core/Concerns/HasColors.php (setDrawColor(), setFillColor(), setTextColor()).
createStandalone() is standaard A4 staand (595.276 × 841.890 pt).src/Core/Document.php (createStandalone()); src/ValueObjects/PageSize.php (A4()).
De uitvoerbestemming is de enum OutputDestination (Inline/Download/File/String); Output('S')getPdfData(), Output('F', $p)save($p).src/Contracts/OutputDestination.php; src/Core/Concerns/HasOutput.php (output()).
SetTitle/SetAuthor/… worden toegewezen aan getypeerde metadata-setters; komen terecht in het informatiewoordenboek / XMP.src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); ISO 32000-2 §14 (frontmatter citations:).
Lettertypen worden altijd ingesloten als subset-programma’s.src/Core/Concerns/HasTypography.php (buildFontData()); ISO 32000-2 §9 (frontmatter citations:).
Inhoud wordt in één doorloop uitgestoten.docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md.

Beide pakketten blijven geïnstalleerd tot de definitieve overstap, dus terugdraaien per aanroepplek betekent dat je die aanroepplek terugzet naar het FPDF-pad. Na de definitieve overstap betekent terugdraaien dat je FPDF en de eerdere code uit versiebeheer herstelt. Er is geen gegevensmigratie bij betrokken.

Zie Prestaties. Het model met één doorloop verwijdert elke vastgehouden bufferkost. De nieuwe kosten per document zitten in de eager herleiding van lettertypen (stap 3), die via de lettertypemap te cachen is.

  • Millimeter-coördinaten als punten transcriberen zonder de * 72 / 25.4-conversie.
  • Output() in FPDF’s ($dest, $name)-volgorde laten staan, of een teken doorgeven in plaats van de OutputDestination-enum.
  • SetMargins($l, $t, $r) rechtstreeks in Margin transcriberen (waarvan de volgorde top, right, bottom, left is).
  • Verwachten dat AddFont-metriekbestanden porten; plaats de TTF/OTF in plaats daarvan in de lettertypemap.
  • Grijpen naar een GetStringWidth-equivalent; gebruik multiCell() voor afbreking.
  • Byte/pixel-identieke uitvoer verwachten (onafhankelijke engines — deze handleiding claimt nooit een drop-in of 100% compatibiliteit).