Siklus hidup sesi yang aman untuk worker di NextPDF Connect

Sekilas

Gunakan siklus hidup sesi yang dibatasi per permintaan pada worker PHP yang berjalan lama (RoadRunner, Swoole, Laravel Octane). Setiap permintaan membuat sesi dokumennya sendiri, lalu menghancurkannya setelah output_pdf. State untuk font, halaman, dan handle tetap berada dalam batas permintaan worker. Alat yang digunakan adalah create_pdf, set_font, add_text, dan output_pdf — semuanya termasuk Core.

Pemasangan

composer require nextpdf/server

Ikat transport. Pola ini bekerja dengan cara yang sama untuk transport apa pun.

Gambaran konsep

Sebuah document_id adalah handle opaque yang cakupannya dibatasi untuk satu permintaan. Ikuti satu aturan ini: buat untuk setiap permintaan, hancurkan untuk setiap permintaan, jangan pernah simpan dalam cache atau bagikan. Dengan nilai standar destroy: true, output_pdf merender dokumen dan membebaskan sesi dalam satu langkah atomik. Permintaan berikutnya di worker yang sama mendapatkan sesi baru yang independen. Font dan konten dari sesi sebelumnya telah hilang. Setiap hasil alat berupa respons transport biasa (PSR-18 §p2). Kode server terisolasi oleh batas autoload (PSR-4 §3). Penyimpanan sesi adalah satu-satunya state antarpermintaan, dan pengunciannya berdasarkan id.

Permukaan API

Alat	Peran	Tingkat risiko
`create_pdf`	Membuka sesi per permintaan	Aman
`set_font`	Mengatur font aktif (per sesi)	Perhatian
`add_text`	Menulis konten	Perhatian
`output_pdf`	Merender dan menghancurkan sesi	Persetujuan Diperlukan / Tinjauan (base64)

Katalog alat adalah sumber rujukan resmi. Alat yang dapat Anda gunakan bergantung pada tier yang terpasang.

Contoh kode — Mulai cepat

Permintaan 1 menjalankan: create_pdf → set_font → add_text → output_pdf (destroy: true). Permintaan 2 di worker yang sama memulai sesi create_pdf yang baru. Id lama kini tidak valid. Atur font lagi karena font tidak ikut terbawa.

Contoh kode — Produksi

Bungkus siklus hidupnya agar pembersihan selalu berjalan:

Peroleh sesi saat permintaan dimulai.
Susun konten.
Dalam blok yang setara dengan finally, panggil output_pdf; panggilan ini menghancurkan sesi. Jika Anda menggunakan destroy: false untuk alur inspeksi-setelah-keluaran, hancurkan sesi secara eksplisit sebagai gantinya.

Jangan pernah menyimpan document_id di kontainer global worker, statis, atau bersama. Jangan pernah meneruskannya antarcoroutine, fiber, atau penangan permintaan.

Kasus tepi & jebakan

Id digunakan ulang setelah dihancurkan. Mengembalikan galat dokumen-tidak-dikenal. Buat sesi baru untuk setiap permintaan.
output_pdf terlupakan. Memori terus bertambah diam-diam hingga TTL sesi kedaluwarsa atau proses dimulai ulang. Selalu finalisasi sesi.
Batas sesi saat beban tinggi. Penyimpanan memiliki batas konkurensi. Menghancurkan sesi dengan cepat membantu Anda tetap di bawah batas itu.
destroy: false tanpa pembersihan. Memori bertambah secara bertahap. Gunakan ini hanya untuk alur inspeksi-setelah-keluaran yang eksplisit, lalu hancurkan sesi.
Id yang dibagikan antarpermintaan konkuren. Ini memicu race yang merusak keluaran. Setiap permintaan memiliki sesinya sendiri.

Kinerja

Keluaran per permintaan berukuran beberapa KB. Manfaatnya adalah penggunaan memori worker tetap terbatas sepanjang masa hidup worker. Profilnya adalah structural.

Catatan keamanan

Isolasi sesi juga merupakan properti kerahasiaan. Konten dari satu permintaan tidak pernah mencapai permintaan lain karena handle tidak dibagikan dan sesi dihancurkan saat keluaran dibuat.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Setiap hasil alat adalah respons transport biasa.	PSR-18	§p2
Kode diisolasi melalui pemetaan kelas→berkas autoload.	PSR-4	§3

Konteks komersial

Tidak berlaku — semua alat termasuk Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	Satu proses stdio per worker lazim digunakan.
REST	Ya	Batas permintaan HTTP dipetakan ke batas sesi.
gRPC	Ya	Satu sesi per urutan RPC.

Tingkat risiko HITL

create_pdf bersifat Aman. set_font dan add_text bersifat Perhatian. output_pdf bersifat Persetujuan Diperlukan, diturunkan menjadi Tinjauan dalam mode base64. Dalam worker, keluaran base64 adalah jalur umum dan tidak menambahkan gerbang (tingkat risiko HITL).

Amplop JSON untuk gerbang konfirmasi

Keluaran base64 dari worker:

{ "allowed": true }