Fondasi PHP 8.4

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

Sekilas pandang

NextPDF membutuhkan PHP 8.4. Halaman ini menjelaskan fitur bahasa 8.4 mana yang diandalkan mesin, mengapa versi tersebut menjadi batas bawah yang tegas dan bukan sekadar rekomendasi, serta bagaimana build penurunan terpisah tetap membuka opsi untuk berjalan pada runtime yang lebih lama tanpa melemahkan basis kode yang Anda baca.

Mengapa ini penting

Mesin PDF mengubah masukan yang ambigu menjadi format berkas yang presisi hingga ke level byte. PDF adalah format lama yang matang, dengan aturan yang kokoh dan baku, serta cukup ketat sehingga tebakan yang keliru berbiaya mahal. Bahasa tempat mesin ini ditulis adalah titik pertama tempat tebakan seperti itu ditangkap, atau justru lolos tanpa pemeriksaan. Batas bawah versi bukan pembatasan demi pembatasan. Ini adalah garis batas yang, di bawahnya, mesin tidak lagi dapat memberikan jaminan tipe yang menjadi sandaran seluruh desainnya.

Jika batas bawah itu kabur, dua konsekuensi pun muncul. Basis kode akan dipenuhi lapisan kompatibilitas yang mengaburkan logika sebenarnya. Sistem tipe juga tidak lagi menjadi penopang utama, padahal properti itulah yang tidak boleh hilang dari sebuah alur dokumen.

Versi ringkasnya

• Paket inti mendeklarasikan "php": ">=8.4 <9.0". Itulah batasan yang sebenarnya, terverifikasi di composer.json, bukan sekadar aspirasi dalam dokumentasi.
• 8.4 menjadi batas bawah karena mesin menggunakan fitur bahasa 8.4 (dan 8.x terbaru) sebagai jaminan struktural: visibilitas asimetris, backed enum yang membawa perilaku, konstanta kelas bertipe, state readonly, serta named argument sebagai bagian utama dari API publik.
• Berjalan pada PHP 8.1–8.3 tetap dimungkinkan melalui build penurunan terpisah (backport). Ini adalah perkakas build, bukan dependensi runtime. Ini tidak mengubah kode yang Anda baca di repositori inti.
• Batas atas <9.0 disengaja: rilis mayor PHP yang baru diperlakukan sebagai sesuatu yang harus divalidasi, bukan diasumsikan.

Bagaimana NextPDF menyikapinya

Batas bawah ditentukan oleh apa yang benar-benar dilakukan kode. Jadi, cara paling jujur untuk menjelaskannya adalah menunjukkan fitur-fiturnya di dalam kode, bukan mendaftarnya secara abstrak.

Visibilitas asimetris memungkinkan state dibaca secara publik tetapi hanya ditulis secara privat, tanpa getter tulis tangan untuk setiap field. Konteks rendering menggunakannya secara langsung:

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

Satu fitur bahasa itu saja menghilangkan satu kategori penuh mutasi eksternal yang tidak disengaja. Kursor tidak dapat dipindahkan dari luar mesin. Jaminan ini ditegakkan oleh runtime, bukan oleh konvensi yang harus terus diingat peninjau.

Backed enum yang membawa perilaku menggantikan flag boolean dan konstanta string yang tersebar dengan satu nilai bertipe yang juga mampu menjawab pertanyaan tentang dirinya sendiri. Diskriminator konformitas dokumen adalah backed enum yang metode-metodenya menentukan keputusan pada tingkat spesifikasi:

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 ini menjadi satu-satunya sumber kebenaran untuk “apakah dokumen ini ditandai sesuai spesifikasi?” dan “bagian ISO mana yang berlaku?”. Ketika pertanyaan seperti itu dinyatakan sebagai boolean yang longgar, beberapa tempat bisa menjawabnya secara tidak konsisten.

Konstanta kelas bertipe menjadikan konstanta sebagai bagian dari kontrak tipe. Batas tegas mesin HTML dideklarasikan sebagai konstanta bertipe:

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

Named argument adalah bagian dari permukaan API publik, bukan trik internal. Program contoh meneruskannya pada titik pemanggilan yang memang dimaksudkan untuk disalin pembaca:

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

Ini bukan penggunaan sintaksis baru sebagai hiasan. Masing-masing mengubah konvensi yang semula harus ditegakkan secara manual oleh peninjau menjadi properti yang ditegakkan oleh runtime.

Apa yang dikatakan bukti

Halaman ini bersifat Evidence { } Code-backed Evidence: Code-backed . Setiap klaim di atas dipetakan ke berkas di repositori inti, bukan ke daftar fitur:

• Batasan versi adalah nilai require.php ">=8.4 <9.0" di composer.json inti.
• Contoh visibilitas asimetris adalah gaya deklarasi yang benar-benar digunakan di src/Core/RenderingContext.php (field public private(set)).
• Contoh enum mencerminkan src/Conformance/ConformanceMode.php, sebuah backed enum … : string yang metode-metodenya berbasis match dan menggerakkan keputusan konformitas.
• Konstanta bertipe tersebut ada di src/Html/HtmlParser.php (private const int MAX_NESTING_DEPTH, MAX_ELEMENT_COUNT).
• Pemanggilan named argument berasal dari program examples/ yang disertakan.

Batas bawah juga memiliki dimensi standar. Tugas mesin adalah menghasilkan berkas yang sesuai dengan Spec Spec: ISO 32000-2, §7.5.2 ISO 32000-2 §7.5.2 . Penulis PDF 2.0 yang konform harus mendeklarasikan versi dokumen sebagai 2.0 di header berkas atau di katalog. Memenuhi kewajiban seketat itu jauh lebih mudah ketika bahasa yang menopang penulis tersebut membuat state yang tidak cocok sulit dibentuk sejak awal. Batas bawah versi dan ketatnya format saling selaras.

Contoh praktis

Program valid paling minimal pun sudah memanfaatkan batas bawah ini. Program ini berjalan pada PHP 8.4, menggunakan named argument, dan menghasilkan berkas yang konform:

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

Di sini tidak ada yang eksotis. Intinya, mekanisme strict typing, enum, dan visibilitas asimetris yang sama, yang membuat internal mesin dapat dipercaya, sudah aktif di balik program lima baris ini. Anda tidak perlu mengaktifkannya secara khusus.

Kesalahpahaman umum

Kesalahpahaman paling umum adalah menganggap “membutuhkan PHP 8.4” berarti “tidak akan berfungsi kecuali Anda memutakhirkan ke 8.4.” Maksudnya, sumber inti ditargetkan untuk 8.4. Build penurunan terpisah tersedia bagi tim yang terkunci pada PHP 8.1–8.3.

Penting untuk tepat memahami apa sebenarnya build tersebut. Build ini adalah alur penurunan berbasis Rector yang mengubah sumber 8.4 menjadi keluaran dengan sintaks yang lebih lama. Ini adalah infrastruktur build, bukan pustaka runtime yang Anda tambahkan ke dependensi aplikasi Anda. Build ini tidak memunculkan basis kode paralel yang lebih lemah secara tipe. Kode yang ditinjau di halaman-halaman ini dan kode yang dirilis adalah kode yang sama. Backport adalah transformasi yang diterapkan pada kode itu, bukan alternatif darinya.

Human-factors note: Human-factors note

Halaman ini sengaja menampilkan empat bentuk kode nyata yang ringkas, bukan daftar prosa fitur bahasa yang panjang. Gagasan yang berkaitan dikelompokkan dan sengaja dijaga tetap sedikit. Sekumpulan kecil contoh konkret lebih mudah diingat dan dikenali kembali dibandingkan katalog yang menyeluruh. Ini adalah penalaran yang sama yang menjaga permukaan tipe mesin sendiri tetap kecil dan eksplisit, bukan luas dan implisit.

Batasan dan ruang lingkup

Halaman ini menjelaskan mengapa 8.4 menjadi batas bawah dan apa yang dipertahankan oleh backport. Halaman ini tidak mendokumentasikan cara menjalankan alur penurunan, versi target yang didukungnya, maupun catatan peringatan operasionalnya. Hal-hal itu termasuk dalam dokumentasi build backport itu sendiri. Tata letak paket internal perkakas tersebut berada di luar lingkup pembahasan ini. Penggunaan fitur yang ditampilkan bersifat ilustratif terhadap gaya mesin ini. Ini bukan inventaris lengkap dari setiap fitur 8.x yang digunakan basis kode. API yang persis didefinisikan oleh referensi, bukan oleh penjelasan ini. Batasan versi ini akurat per tanggal peninjauan halaman ini. Nilai otoritatifnya selalu blok require di composer.json inti.

Edisi tidak berpengaruh pada batas bawah bahasa. Setiap edisi dibangun dari sumber PHP 8.4 yang sama:

PHP 8.4 source floor — edition availability

Edition	Availability
Core	○ Core ditulis untuk target PHP 8.4.
Pro	○ Pro dibangun di atas batas bawah sumber 8.4 yang sama.
Enterprise	○ Enterprise dibangun di atas batas bawah sumber 8.4 yang sama.

Dokumen terkait

• Strict type di mana-mana — bagaimana disiplin analisis statis mengubah batas bawah bahasa menjadi sebuah jaminan.
• Model alur (pipeline) — arsitektur yang disatukan oleh fitur-fitur bahasa tersebut.
• Filosofi desain NextPDF — mengapa mesin lebih memilih kontrak yang eksplisit dan ditegakkan oleh runtime.

Glosarium

• Batas bawah versi — versi PHP minimum yang menjadi target sumber inti (>=8.4). Di bawahnya, jaminan tipe mesin tidak dapat dinyatakan.
• Visibilitas asimetris — fitur PHP 8.4 yang memungkinkan sebuah properti dapat dibaca secara publik tetapi hanya ditulis dari cakupan yang lebih sempit (public private(set)).
• Backed enum — enum PHP yang case-nya memiliki nilai skalar dan dapat membawa perilaku (metode), digunakan di sini sebagai satu sumber kebenaran yang bertipe.
• Backport — build penurunan terpisah berbasis Rector yang mengubah sumber 8.4 menjadi keluaran yang dapat dijalankan pada PHP yang lebih lama. Perkakas build, bukan dependensi runtime.
• Mode konformitas — diskriminator bertipe pada mesin untuk menentukan kontrak konformitas ISO mana yang harus dipenuhi sebuah dokumen.