Fundamenty PHP 8.4

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

W skrócie

NextPDF wymaga PHP 8.4. Ta strona wyjaśnia, na których funkcjach języka 8.4 opiera się silnik, dlaczego ta wersja jest twardą dolną granicą, a nie miękką sugestią, oraz jak odrębna kompilacja obniżająca wersję pozwala uruchamiać go w starszych środowiskach bez osłabiania kodu, który czytasz.

Dlaczego to ma znaczenie

Silnik PDF przekształca niejednoznaczne dane wejściowe w format pliku precyzyjny co do bajta. PDF to dojrzały format o twardych, utrwalonych regułach i jest na tyle rygorystyczny, że błędne zgadywanie szybko staje się kosztowne. Język, w którym napisano silnik, jest pierwszą warstwą, w której takie domysły zostają wychwycone albo przechodzą bez sprawdzenia. Dolna granica wersji nie istnieje dla samego ograniczania. To granica, poniżej której silnik nie jest już w stanie zapewnić gwarancji typów, na których opiera się reszta jego konstrukcji.

Jeśli ta granica jest niejasna, pojawiają się dwa koszty. Kod obrasta warstwami zgodności, które przesłaniają właściwą logikę. System typów przestaje też pełnić funkcję konstrukcyjną, a potok dokumentów nie może sobie pozwolić na utratę tej cechy.

W skrócie najważniejsze

• Pakiet rdzenia deklaruje "php": ">=8.4 <9.0". To rzeczywiste ograniczenie, potwierdzone w pliku composer.json, a nie życzeniowy zapis w dokumentacji.
• 8.4 jest dolną granicą, ponieważ silnik wykorzystuje funkcje języka z wersji 8.4 (oraz nowszych 8.x) jako gwarancje strukturalne: asymetryczną widoczność, wyliczenia z typem bazowym i zachowaniem, typowane stałe klasowe, stan readonly oraz pełnoprawne argumenty nazwane w publicznym API.
• Uruchamianie w PHP 8.1–8.3 jest nadal możliwe dzięki odrębnej kompilacji obniżającej wersję (backport). To mechanizm kompilacyjny, a nie zależność czasu wykonania. Nie zmienia kodu, który czytasz w repozytorium rdzenia.
• Górna granica <9.0 jest celowa: nowe wydanie główne PHP traktuje się jako coś, co należy zweryfikować, a nie zakładać z góry.

Jak podchodzi do tego NextPDF

Dolną granicę wyznacza to, co robi kod. Dlatego najuczciwiej wyjaśnić ją przez pokazanie tych funkcji w kodzie, zamiast wymieniać je w oderwaniu od niego.

Asymetryczna widoczność pozwala udostępnić stan do publicznego odczytu, a zapis ograniczyć do prywatnego zakresu, bez ręcznego pisania gettera dla każdego pola. Kontekst renderowania korzysta z niej bezpośrednio:

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 = '';
}

Ta jedna funkcja języka eliminuje całą kategorię przypadkowych modyfikacji z zewnątrz. Kursora nie da się przesunąć spoza silnika. Gwarancję egzekwuje środowisko uruchomieniowe, a nie konwencja, o której recenzenci muszą pamiętać.

Wyliczenia z typem bazowym i zachowaniem zastępują rozproszone flagi logiczne i stałe łańcuchowe jedną typowaną wartością, która sama odpowiada na pytania dotyczące swojego znaczenia. Dyskryminator zgodności dokumentu to wyliczenie z typem bazowym, którego metody decydują o wynikach na poziomie specyfikacji:

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,
        };
    }
}

Wyliczenie jest jedynym źródłem prawdy dla pytań „czy ten dokument jest oznaczony zgodnie ze specyfikacją?” oraz „która część normy ISO ma zastosowanie?”. Gdy te pytania wyrażano jako luźne wartości logiczne, kilka miejsc mogło odpowiadać na nie niespójnie.

Typowane stałe klasowe sprawiają, że nawet stałe stają się częścią kontraktu typów. Twarde limity silnika HTML są zadeklarowane jako typowane stałe:

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

Argumenty nazwane są częścią publicznego API, a nie wewnętrzną sztuczką. Przykładowe programy używają ich w miejscach wywołań, które czytelnik ma kopiować:

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

To nie są ozdobne użycia nowej składni. Każde z nich zamienia konwencję, której recenzent musiałby w przeciwnym razie pilnować ręcznie, we właściwość egzekwowaną przez środowisko uruchomieniowe.

Co mówią dowody

Ta strona ma status Evidence { } Code-backed Evidence: Code-backed . Każde z powyższych stwierdzeń ma odpowiednik w pliku repozytorium rdzenia, a nie w samej liście funkcji:

• Ograniczenie wersji to wartość require.php ">=8.4 <9.0" w pliku composer.json rdzenia.
• Przykład asymetrycznej widoczności pokazuje rzeczywisty styl deklaracji w pliku src/Core/RenderingContext.php (pola public private(set)).
• Przykład wyliczenia odzwierciedla src/Conformance/ConformanceMode.php — wyliczenie z typem bazowym enum … : string, którego metody oparte na match sterują decyzjami dotyczącymi zgodności.
• Typowane stałe to src/Html/HtmlParser.php (private const int MAX_NESTING_DEPTH, MAX_ELEMENT_COUNT).
• Wywołanie z argumentem nazwanym pochodzi z dostarczanych programów examples/.

Dolna granica ma też wymiar normatywny. Zadaniem silnika jest emitowanie plików zgodnych z Spec Spec: ISO 32000-2, §7.5.2 ISO 32000-2 §7.5.2 . Zgodny zapisujący PDF 2.0 musi deklarować wersję dokumentu jako 2.0 w nagłówku pliku lub w katalogu. Spełnienie tak precyzyjnego wymogu jest znacznie łatwiejsze, gdy język leżący u podstaw mechanizmu zapisującego utrudnia samo zbudowanie niespójnego stanu. Dolna granica wersji i rygor formatu są ze sobą spójne.

Przykład praktyczny

Najmniejszy poprawny program już korzysta z tej dolnej granicy. Działa w PHP 8.4, używa argumentu nazwanego i tworzy zgodny plik:

<?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');

Nie ma tu niczego egzotycznego. Chodzi o to, że ten sam mechanizm ścisłego typowania, wyliczeń i asymetrycznej widoczności, który sprawia, że wnętrze silnika jest godne zaufania, działa już pod tym pięciolinijkowym programem. Nie trzeba się na to osobno godzić — tak działa ten projekt z założenia.

Częste nieporozumienie

Najczęstsze błędne odczytanie polega na uznaniu, że „wymaga PHP 8.4” znaczy „nie zadziała, dopóki nie zaktualizujesz do 8.4.” Oznacza to, że kod źródłowy rdzenia jest pisany pod 8.4. Dla zespołów związanych z PHP 8.1–8.3 istnieje odrębna kompilacja obniżająca wersję.

Ważne, aby precyzyjnie określić, czym jest ta kompilacja. To oparty na narzędziu Rector potok obniżający wersję, który przekształca kod źródłowy 8.4 w wynik o starszej składni. To infrastruktura kompilacji, a nie biblioteka czasu wykonania dodawana do zależności aplikacji. Nie wprowadza równoległego kodu o słabszym typowaniu. Kod omawiany na tych stronach i kod dostarczany użytkownikom to ten sam kod. Backport to przekształcenie zastosowane do tego kodu, a nie jego alternatywa.

Human-factors note: Human-factors note

Ta strona celowo pokazuje cztery krótkie, rzeczywiste formy kodu zamiast długiej opisowej listy funkcji języka. Powiązane idee są zgrupowane i celowo nieliczne. Niewielki zestaw konkretnych przykładów łatwiej utrzymać w pamięci i później rozpoznać niż wyczerpujący katalog. To ten sam tok rozumowania, który utrzymuje powierzchnię typów samego silnika niewielką i jawną, a nie szeroką i niejawną.

Ograniczenia i granice

Ta strona wyjaśnia, dlaczego 8.4 jest dolną granicą i co zachowuje backport. Nie dokumentuje, jak uruchomić potok obniżający wersję, jakie wersje docelowe są obsługiwane ani jakie ma zastrzeżenia operacyjne. Te kwestie należą do osobnej dokumentacji kompilacji backport. Wewnętrzny układ pakietów tych narzędzi wykracza poza zakres tej strony. Pokazane zastosowania funkcji ilustrują styl silnika. Nie są pełnym wykazem każdej funkcji 8.x, z której korzysta kod. Dokładne API definiuje dokumentacja referencyjna, a nie to wyjaśnienie. Ograniczenie wersji jest aktualne na dzień przeglądu tej strony. Wartością miarodajną jest zawsze blok require w pliku composer.json rdzenia.

Edycja nie ma wpływu na dolną granicę języka. Każda edycja jest budowana z tego samego kodu źródłowego PHP 8.4:

PHP 8.4 source floor — edition availability

Edition	Availability
Core	○ Core jest pisany pod PHP 8.4.
Pro	○ Pro opiera się na tej samej dolnej granicy kodu źródłowego 8.4.
Enterprise	○ Enterprise opiera się na tej samej dolnej granicy kodu źródłowego 8.4.

Powiązana dokumentacja

• Ścisłe typy, wszędzie — jak dyscyplina analizy statycznej zmienia dolną granicę języka w gwarancję.
• Model potoku — architektura spajana przez te funkcje języka.
• Filozofia projektowa NextPDF — dlaczego silnik preferuje jawne kontrakty egzekwowane w czasie wykonania.

Słowniczek

• Dolna granica wersji — minimalna wersja PHP, pod którą pisany jest kod źródłowy rdzenia (>=8.4). Poniżej niej gwarancji typów silnika nie da się wyrazić.
• Asymetryczna widoczność — funkcja PHP 8.4 pozwalająca, aby właściwość była publicznie odczytywalna, lecz zapisywalna tylko z węższego zakresu (public private(set)).
• Wyliczenie z typem bazowym — wyliczenie PHP, którego przypadki mają wartości skalarne i które może nieść zachowanie (metody), wykorzystywane tutaj jako jedno typowane źródło prawdy.
• Backport — odrębna, oparta na narzędziu Rector kompilacja obniżająca wersję, która przekształca kod źródłowy 8.4 w wynik uruchamialny na starszym PHP. Mechanizm kompilacyjny, a nie zależność czasu wykonania.
• Tryb zgodności — typowany dyskryminator silnika określający, który kontrakt zgodności ISO musi spełniać dokument.