De fundamenten van PHP 8.4

Spec: ISO 32000-2, §7.5.2 Evidence: Code-backed PHP-restrictie: ≥8.4 <9.0

In een oogopslag

NextPDF vereist PHP 8.4. Deze pagina legt uit op welke PHP 8.4-taalfuncties de engine steunt, waarom die versie een harde ondergrens is en geen vrijblijvende suggestie, en hoe een afzonderlijke downgrade-build het mogelijk houdt om op een oudere runtime te draaien zonder de codebase die je leest te verzwakken.

Waarom dit belangrijk is

Een PDF-engine zet dubbelzinnige invoer om in een byte-exact bestandsformaat. PDF is een lang gevestigd formaat met vaste, onwrikbare regels, en het is zo streng dat een verkeerde gok duur uitpakt. De taal waarin de engine is geschreven, is de eerste plek waar zulke gissingen worden onderschept of ongecontroleerd worden doorgelaten. Een versie-ondergrens is geen doel op zich. Het is de grens waaronder de engine niet langer de typegaranties kan bieden waarvan de rest van zijn ontwerp afhankelijk is.

Als die ondergrens vaag is, betaal je op twee manieren. De codebase raakt vol met compatibiliteitsshims die de eigenlijke logica verhullen. Daarnaast is het typesysteem niet langer dragend, en dat is precies de eigenschap die een documentpijplijn zich niet kan veroorloven te verliezen.

De korte versie

Het core-pakket declareert "php": ">=8.4 <9.0". Dat is de werkelijke restrictie, geverifieerd in composer.json, geen wens uit de documentatie.
8.4 is de ondergrens omdat de engine taalfuncties uit 8.4 (en recente 8.x) inzet als structurele garanties: asymmetrische zichtbaarheid, backed enums met gedrag, getypeerde klasseconstanten, readonly-toestand, en benoemde argumenten als eersteklas onderdeel van de publieke API.
Draaien op PHP 8.1–8.3 blijft mogelijk via een afzonderlijke downgrade-build (de backport). Het is build-gereedschap, geen runtime-afhankelijkheid. Het verandert niets aan de code die u in de core-repository leest.
De bovengrens <9.0 is bewust: een nieuwe grote PHP-release wordt behandeld als iets om te valideren, niet om aan te nemen.

Hoe NextPDF dit aanpakt

De ondergrens wordt bepaald door wat de code doet. De zuiverste manier om dit uit te leggen is daarom de functies in de code te tonen in plaats van ze abstract op te sommen.

Asymmetrische zichtbaarheid maakt toestand publiek leesbaar maar alleen privé schrijfbaar, zonder een handgeschreven getter voor elk veld. De weergavecontext maakt er rechtstreeks gebruik van:

declare(strict_types=1);

final class RenderingContext
{
    // Readable everywhere, writable only inside the class.
    public private(set) float $x = 0.0;
    public private(set) float $y = 0.0;
    public private(set) int $currentPageIndex = -1;
    public private(set) string $currentContentStream = '';
}

Alleen al deze taalfunctie elimineert een hele categorie onbedoelde externe mutatie. De cursor kan niet van buiten de engine worden verplaatst. De garantie wordt afgedwongen door de runtime, niet door een conventie waaraan reviewers moeten blijven denken.

Backed enums met gedrag vervangen verspreide booleaanse vlaggen en stringconstanten door één getypeerde waarde die zelf ook vragen kan beantwoorden. De conformiteitsdiscriminator van het document is een backed enum waarvan de methoden beslissingen op specificatieniveau bepalen:

declare(strict_types=1);

enum ConformanceMode: string
{
    case Plain  = 'plain';
    case PdfUa2 = 'pdfua2';
    case PdfA4  = 'pdfa4';
    case PdfA4f = 'pdfa4f';

    public function isTagged(): bool
    {
        return match ($this) {
            self::Plain => false,
            default     => true,
        };
    }

    /** @return 2|3|4|null */
    public function pdfaPart(): ?int
    {
        return match ($this) {
            self::PdfA4, self::PdfA4f => 4,
            default                   => null,
        };
    }
}

De enum is de enige bron van waarheid voor de vragen “is dit document spec-getagd?” en “welk ISO-deel is van toepassing?”. Toen die vragen als losse booleans werden uitgedrukt, konden meerdere plekken ze inconsistent beantwoorden.

Getypeerde klasseconstanten maken zelfs constanten onderdeel van het typecontract. De harde limieten van de HTML-engine worden als getypeerde constanten gedeclareerd:

private const int MAX_NESTING_DEPTH = 100;
private const int MAX_ELEMENT_COUNT = 50_000;

Benoemde argumenten maken deel uit van het publieke API-oppervlak, niet van een interne truc. De voorbeeldprogramma’s gebruiken ze op aanroepplekken die je als lezer naar verwachting overneemt:

$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);

Dit zijn geen decoratieve toepassingen van nieuwe syntaxis. Elk ervan verandert een conventie die een reviewer anders handmatig zou moeten afdwingen in een eigenschap die de runtime afdwingt.

Wat het bewijs zegt

Deze pagina is Evidence: Code-backed . Elke bewering hierboven verwijst naar een bestand in de core-repository, niet naar een functielijst:

De versierestrictie is de waarde require.php ">=8.4 <9.0" in de core-composer.json.
Het voorbeeld van asymmetrische zichtbaarheid is de werkelijke declaratiestijl in src/Core/RenderingContext.php (public private(set)-velden).
Het enum-voorbeeld komt overeen met src/Conformance/ConformanceMode.php, een backed enum … : string waarvan de op match gebaseerde methoden de conformiteitsbeslissingen sturen.
De getypeerde constanten zijn src/Html/HtmlParser.php (private const int MAX_NESTING_DEPTH, MAX_ELEMENT_COUNT).
De aanroep met een benoemd argument komt uit de meegeleverde examples/-programma’s.

De ondergrens heeft ook een standaarden-dimensie. De taak van de engine is bestanden te produceren die voldoen aan Spec: ISO 32000-2, §7.5.2 . Een conforme PDF 2.0- writer moet de documentversie als 2.0 declareren in de bestandsheader of de catalogus. Aan zo’n precieze verplichting voldoen is veel eenvoudiger wanneer de taal waarop de writer is gebouwd het vanaf het begin moeilijk maakt om niet-overeenkomende toestand te construeren. De versie-ondergrens en de striktheid van het formaat zijn op elkaar afgestemd.

Praktisch voorbeeld

Het kleinste correcte programma leunt al op de ondergrens. Het draait op PHP 8.4, gebruikt een benoemd argument en levert een conform bestand op:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->save(__DIR__ . '/hello.pdf');

Niets hieraan is exotisch. Het punt is dat hetzelfde mechanisme van strikte typering, enums en asymmetrische zichtbaarheid dat de interne werking van de engine betrouwbaar maakt, al actief is onder dit programma van vijf regels. Je hoeft er niet expliciet voor te kiezen.

Veelvoorkomend misverstand

De meest voorkomende misinterpretatie is dat “vereist PHP 8.4” betekent “werkt niet tenzij je upgradet naar 8.4.” Het betekent dat de core-broncode zich op 8.4 richt. Er bestaat een afzonderlijke downgrade-build voor teams die vastzitten aan PHP 8.1–8.3.

Het is belangrijk om precies te zijn over wat die build is. Het is een op Rector gebaseerde downgrade-pijplijn die de 8.4-broncode omzet in uitvoer met oudere syntaxis. Het is build-infrastructuur, geen runtime-bibliotheek die je aan de afhankelijkheden van je applicatie toevoegt. Het introduceert geen parallelle, zwakker getypeerde codebase. De code die op deze pagina’s wordt besproken, is dezelfde code als de code die wordt uitgeleverd. De backport is een transformatie die erop wordt toegepast, geen alternatief ervoor.

Limieten en grenzen

Deze pagina legt uit waarom 8.4 de ondergrens is en wat de backport behoudt. Het documenteert niet hoe je de downgrade-pijplijn uitvoert, welke doelversies worden ondersteund of welke operationele voorbehouden er gelden. Die horen thuis in de eigen documentatie van de backport-build. De interne pakketindeling van dat gereedschap valt hier buiten de scope. De getoonde toepassingen van functies zijn illustratief voor de stijl van de engine. Ze vormen niet de volledige inventaris van elke 8.x-functie die de codebase gebruikt. Exacte API’s worden gedefinieerd door de referentie, niet door deze uitleg. De versierestrictie klopt op de beoordelingsdatum van deze pagina. De gezaghebbende waarde is altijd het require-blok in de core-composer.json.

De editie heeft geen invloed op de taalondergrens. Elke editie wordt gebouwd uit dezelfde PHP 8.4-broncode:

PHP 8.4 source floor — edition availability
Edition	Availability
Core	Core is geschreven voor PHP 8.4.
Pro	Pro bouwt voort op dezelfde 8.4-broncode-ondergrens.
Enterprise	Enterprise bouwt voort op dezelfde 8.4-broncode-ondergrens.

Gerelateerde documentatie

Strikte typen, overal — hoe de discipline van statische analyse de taalondergrens omzet in een garantie.
Het pijplijnmodel — de architectuur waarin die taalfuncties samenkomen.
De ontwerpfilosofie van NextPDF — waarom de engine de voorkeur geeft aan expliciete, door de runtime afgedwongen contracten.

Verklarende woordenlijst

Versie-ondergrens — de minimale PHP-versie waarop de core-broncode zich richt (>=8.4). Daaronder kunnen de typegaranties van de engine niet worden uitgedrukt.
Asymmetrische zichtbaarheid — een PHP 8.4-functie waarmee een eigenschap publiek leesbaar is maar uitsluitend vanuit een beperktere scope beschrijfbaar (public private(set)).
Backed enum — een PHP-enum waarvan de cases scalaire waarden hebben en die gedrag kan bevatten (methoden), hier gebruikt als één getypeerde bron van waarheid.
Backport — de afzonderlijke, op Rector gebaseerde downgrade-build die de 8.4-broncode omzet in uitvoer die op oudere PHP kan draaien. Build-gereedschap, geen runtime-afhankelijkheid.
Conformiteitsmodus — de getypeerde discriminator van de engine voor welk ISO-conformiteitscontract voor een document geldt.