PHP 8.4 temelleri

Spec: ISO 32000-2, §7.5.2 Evidence: Code-backed PHP kısıtlaması: ≥8.4 <9.0

Bir bakışta

NextPDF, PHP 8.4 gerektirir. Bu sayfa, motorun hangi PHP 8.4 dil özelliklerine dayandığını, bu sürümün neden nazik bir öneri değil de katı bir taban olduğunu ve ayrı bir geriye uyarlama derlemesinin, okuduğunuz kod tabanını zayıflatmadan daha eski bir çalışma zamanında çalıştırma seçeneğini nasıl koruduğunu açıklar.

Bunun neden önemli olduğu

Bir PDF motoru, belirsiz girdiyi bayt düzeyinde kesin bir dosya biçimine dönüştürür. PDF, sağlam ve değişmez kurallara sahip, uzun süredir yerleşmiş bir biçimdir ve yanlış bir tahminin maliyetli olacağı kadar katıdır. Motorun yazıldığı dil, bu tahminlerin ya yakalandığı ya da denetlenmeden geçirildiği ilk yerdir. Bir sürüm tabanı, salt kısıtlama koymak için belirlenmiş bir sınır değildir. Bu, motorun, tasarımının geri kalanının dayandığı tür güvencelerini artık sağlayamadığı sınır çizgisidir.

Bu taban belirsizse, iki maliyet ortaya çıkar. Kod tabanı, asıl mantığı gölgeleyen uyumluluk ara katmanlarıyla dolar. Tür sistemi de taşıyıcı yapı olmaktan çıkar; bu ise tam olarak bir belge işlem hattının kaybetmeyi göze alamayacağı özelliktir.

Kısa özet

Core paketi "php": ">=8.4 <9.0" bildirir. Gerçek kısıtlama budur; composer.json içinde doğrulanmıştır, belgede kalan bir temenni değildir.
8.4’ün taban olmasının nedeni, motorun 8.4 (ve yakın zamanlı 8.x) dil özelliklerini yapısal güvenceler olarak kullanmasıdır: asimetrik görünürlük, davranış taşıyan backed enum’lar, türlü sınıf sabitleri, readonly durum ve genel API’de birinci sınıf adlandırılmış argümanlar.
PHP 8.1–8.3 üzerinde çalıştırmak, ayrı bir geriye uyarlama derlemesi (backport) aracılığıyla yine de mümkündür. Bu, bir çalışma zamanı bağımlılığı değil, derleme aracıdır. Core deposunda okuduğunuz kodu değiştirmez.
Üst sınır <9.0 bilinçlidir: yeni bir ana PHP sürümü, varsayılacak değil, doğrulanacak bir şey olarak ele alınır.

NextPDF buna nasıl yaklaşıyor

Taban, kodun yaptığı işe göre belirlenir. Bu nedenle en dürüst açıklama yolu, özellikleri soyut olarak listelemek yerine kod içinde göstermektir.

Asimetrik görünürlük, her alan için elle yazılmış bir alıcı yöntem gerektirmeden durumun herkese açık şekilde okunabilir ama yalnızca özel olarak yazılabilir olmasını sağlar. İşleme bağlamı bunu doğrudan kullanır:

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

Bu tek dil özelliği, kazara dışarıdan değiştirmeye dair tüm bir hata kategorisini ortadan kaldırır. İmleç, motorun dışından hareket ettirilemez. Bu güvence, incelemecilerin akılda tutmasına bırakılan bir kurala göre değil, çalışma zamanı tarafından zorunlu kılınır.

Davranış taşıyan backed enum’lar, dağınık boole bayraklarının ve dize sabitlerinin yerine, kendisi hakkındaki soruları da yanıtlayan tek bir türlü değer koyar. Belge uyumluluğu ayırt edicisi, spesifikasyon düzeyindeki sonuçlara yöntemleriyle karar veren bir backed enum’dur:

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

Enum, “bu belge spesifikasyona göre etiketli mi?” ve “hangi ISO bölümü geçerli?” sorularını tek yerde yanıtlar. Bu sorular gevşek boole değerleriyle ifade edildiğinde, birden çok yer bunları tutarsız biçimde yanıtlayabilir.

Türlü sınıf sabitleri, sabitleri bile tür sözleşmesinin bir parçası hâline getirir. HTML motorunun kesin sınırları, türlü sabitler olarak bildirilir:

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

Adlandırılmış argümanlar, içsel bir numara değil, genel API yüzeyinin bir parçasıdır. Örnek programlar, bunları okuyucunun kopyalaması beklenen çağrı noktalarında kullanır:

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

Bunlar, yeni söz diziminin süs amaçlı kullanımları değildir. Her biri, aksi durumda bir incelemecinin elle uygulaması gereken bir kuralı, çalışma zamanının zorunlu kıldığı bir özelliğe dönüştürür.

Kanıtlar ne söylüyor

Bu sayfa Evidence: Code-backed olarak sınıflandırılmıştır. Yukarıdaki her iddia, bir özellik listesine değil, core deposundaki bir dosyaya karşılık gelir:

Sürüm kısıtlaması, require.php alanının ">=8.4 <9.0" değeridir; bu değer, core composer.json içinde yer alır.
Asimetrik görünürlük örneği, src/Core/RenderingContext.php içindeki gerçek bildirim biçimidir (public private(set) alanları).
Enum örneği, src/Conformance/ConformanceMode.php dosyasını yansıtır; bu dosya, backed bir enum … : string türüdür ve match tabanlı yöntemleri uyumluluk kararlarını yönlendirir.
Türlü sabitler, src/Html/HtmlParser.php içindedir (private const int MAX_NESTING_DEPTH, MAX_ELEMENT_COUNT).
Adlandırılmış argüman çağrısı, dağıtımla birlikte gelen examples/ programlarındandır.

Bu tabanın bir de standartlar boyutu vardır. Motorun görevi, şu standarda uyan dosyalar üretmektir: Spec: ISO 32000-2, §7.5.2 . Uyumlu bir PDF 2.0 yazıcısı, belge sürümünü dosya başlığında veya katalogda 2.0 olarak bildirmelidir. Bu kadar kesin bir yükümlülüğü yerine getirmek, yazıcının altında çalışan dil uyumsuz bir durumun en baştan oluşturulmasını zorlaştırdığında çok daha kolaydır. Sürüm tabanı ile biçimin katılığı birbiriyle uyumludur.

Uygulamalı örnek

En küçük doğru program bile bu tabanın üzerinde çalışır. PHP 8.4 üzerinde çalışır, adlandırılmış bir argüman kullanır ve uyumlu bir dosya üretir:

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

Burada sıra dışı hiçbir şey yoktur. Asıl nokta şu: Motorun iç yapılarını güvenilir kılan aynı katı tipleme, enum ve asimetrik görünürlük düzeneği, bu beş satırlık programın altında zaten etkindir. Bunu açıkça etkinleştirmeniz gerekmez.

Yaygın yanlış anlama

En yaygın yanlış okuma, “PHP 8.4 gerektirir” ifadesinin “8.4’e yükseltmediğiniz sürece çalışmaz” anlamına geldiğini sanmaktır; oysa bu, core kaynak kodunun 8.4’ü hedeflediği anlamına gelir. PHP 8.1–8.3’e sabitlenmiş ekipler için ayrı bir geriye uyarlama derlemesi mevcuttur.

Bu derlemenin ne olduğu konusunda net olmak önemlidir. Bu, 8.4 kaynağını daha eski söz dizimine sahip çıktıya dönüştüren, Rector tabanlı bir geriye uyarlama işlem hattıdır. Bu, uygulamanızın bağımlılıklarına eklediğiniz bir çalışma zamanı kütüphanesi değil, bir derleme altyapısıdır. Paralel, daha zayıf türlenmiş bir kod tabanı getirmez. Bu sayfalarda incelenen kod ile dağıtılan kod aynı koddur. Backport, ona uygulanan bir dönüşümdür; ona bir alternatif değildir.

Sınırlar ve kapsam

Bu sayfa, 8.4’ün neden taban olduğunu ve backport’un neyi koruduğunu açıklar. Geriye uyarlama işlem hattının nasıl çalıştırılacağını, desteklenen hedef sürümlerini veya işletimsel uyarılarını belgelemez. Bunlar, backport derlemesinin kendi belgelerine aittir. Bu araçların iç paket düzeni burada kapsam dışıdır. Gösterilen özellik kullanımları, motorun biçemini örnekler. Kod tabanının kullandığı her 8.x özelliğinin eksiksiz envanteri değildir. Tam API’ler, bu açıklama tarafından değil, başvuru belgeleri tarafından tanımlanır. Sürüm kısıtlaması, bu sayfanın inceleme tarihi itibarıyla doğrudur. Yetkili değer her zaman require bloğudur; bu blok, core composer.json içinde yer alır.

Sürümün dil tabanı üzerinde hiçbir etkisi yoktur. Her sürüm, aynı PHP 8.4 kaynağından derlenir:

PHP 8.4 source floor — edition availability
Edition	Availability
Core	Core, PHP 8.4 hedefiyle yazılmıştır.
Pro	Pro, aynı 8.4 kaynak tabanı üzerine kuruludur.
Enterprise	Enterprise, aynı 8.4 kaynak tabanı üzerine kuruludur.

İlgili belgeler

Her yerde katı türler — statik analiz disiplininin dil tabanını nasıl güvenceye dönüştürdüğü.
İşlem hattı modeli — bu dil özelliklerinin bir arada tuttuğu mimari.
NextPDF tasarım felsefesi — motorun neden açık, çalışma zamanında zorunlu kılınan sözleşmeleri tercih ettiği.

Sözlük

Sürüm tabanı — core kaynağının hedeflediği en düşük PHP sürümü (>=8.4). Bu seviyenin altında, motorun tür güvenceleri ifade edilemez.
Asimetrik görünürlük — bir özelliğin herkese açık şekilde okunabilir ama yalnızca daha dar bir kapsamdan yazılabilir olmasına izin veren bir PHP 8.4 özelliği (public private(set)).
Backed enum — durumları skaler değerlere bağlı olan ve davranış (yöntemler) taşıyabilen, burada tek bir türlü doğruluk kaynağı olarak kullanılan bir PHP enum’u.
Backport — 8.4 kaynağını daha eski PHP üzerinde çalıştırılabilir çıktıya dönüştüren, ayrı Rector tabanlı geriye uyarlama derlemesi. Bir çalışma zamanı bağımlılığı değil, derleme aracıdır.
Uyumluluk modu — bir belgenin hangi ISO uyumluluk sözleşmesini karşılaması gerektiğine ilişkin motorun türlü ayırt edicisi.