Flow Layout

Sekilas pandang

NextPDF Pro menempatkan sebuah urutan elemen alir — teks, gambar, tabel, spacer — ke halaman-halaman, menetapkan masing-masing halaman dan posisi konkret. Perilaku page-break dapat dipilih: greedy, orphan-avoiding, atau keep-together.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Tidak ada flag lisensi per-fitur terpisah; envelope Pro yang mengaktifkannya. Bandingkan edisi dan dapatkan lisensi.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Mesin tata letak streaming mengambil sebuah daftar elemen alir dan sebuah region konten, lalu menelusuri elemen secara berurutan dan menetapkan masing-masing sebuah halaman dan posisi. Ketika sebuah elemen tidak muat pada ruang vertikal yang tersisa, mesin memulai halaman baru sesuai strategi yang dikonfigurasi:

• StreamingLayoutEngine — mesinnya. Dibangun dengan sebuah LayoutRegion (area konten per halaman) dan sebuah PageBreakStrategy. Ia mengembalikan sebuah LayoutResult berupa elemen yang ditempatkan.
• FlowElement / FlowElementType — model elemen. Teks dan tabel dapat terpotong lintas halaman; mesin menempatkan gambar dan spacer secara atomik.
• PageBreakStrategy — sebuah enum dengan tiga perilaku:
  • Greedy — pecah segera setelah elemen berikutnya tidak muat.
  • AvoidOrphans — pecah lebih awal ketika hanya tersisa sedikit ruang, untuk menghindari meninggalkan satu elemen tunggal di puncak halaman baru.
  • KeepTogether — hormati penanda keep-with-next sehingga elemen berpasangan tetap pada halaman yang sama bila memungkinkan.

Flow Layout adalah mesin penempatan-elemen. Ia menghitung penetapan halaman dan posisi; ia bukan mesin perenderan HTML atau CSS. Untuk HTML-ke-PDF, gunakan pipeline HTML Core.

Mengapa cara kerjanya demikian

Mesin menetapkan halaman dan posisi untuk setiap elemen dalam satu lintasan maju. Ia tidak pernah membuffer pohon dokumen yang utuh untuk di-reflow kemudian. Itu menjaga memori tetap terbatas seberapa pun panjang dokumen berjalan, dan membuat biaya linear terhadap jumlah elemen. Setiap keputusan page-break adalah predikat lokal atas kursor saat ini dan strategi yang dipilih. Jadi greedy, orphan-avoidance, dan keep-together semuanya terselesaikan dalam penelusuran streaming yang sama. Trade-off-nya adalah komitmen maju: elemen yang terlalu tinggi meluap alih-alih diskalakan ulang, dan keep-together hanya berlaku ketika kedua elemen berpasangan berbagi satu halaman.

Latar belakang desain: Pembuatan dokumen bervolume tinggi.

Permukaan API

Class	Responsibility
StreamingLayoutEngine	Menetapkan halaman dan posisi pada elemen alir.
FlowElement, FlowElementType	Model elemen dan enum tipe.
LayoutRegion	Area konten per-halaman.
PageBreakStrategy	Enum perilaku page-break.
LayoutResult, PlacedElement	Keluaran penempatan.

Contoh kode — Mulai cepat

use NextPDF\Pro\FlowLayout\{StreamingLayoutEngine, LayoutRegion, PageBreakStrategy};

$engine = new StreamingLayoutEngine(
    region:   new LayoutRegion(/* x, y, width, height */),
    strategy: PageBreakStrategy::AvoidOrphans,
);
$result = $engine->layout($elements);

Contoh kode — Produksi

$result = $engine->layout($elements);
foreach ($result->placements as $placed) {
    $logger->debug('flow.placed', [
        'page' => $placed->pageIndex,
        'type' => $placed->element->type->value,
    ]);
}

Kasus tepi & jebakan

• Mesin tetap menempatkan elemen yang lebih tinggi dari region, tetapi mungkin meluap; ukur elemen di dalam tinggi region.
• KeepTogether menjaga pasangan tetap bersama hanya ketika keduanya muat pada satu halaman.
• AvoidOrphans mencadangkan setidaknya dua tinggi elemen sebelum memecah.

Performa

Tata letak bersifat linear terhadap jumlah elemen. Mesin bersifat streaming: ia tidak menyimpan pohon dokumen yang utuh.

Catatan keamanan

Flow Layout beroperasi pada metadata elemen yang Anda sediakan. Ia tidak melakukan I/O.

Konformansi

Flow Layout mengimplementasikan perilaku penempatan NextPDF; ia tidak menargetkan standar tata letak eksternal.

Kontrak perilaku

• StreamingLayoutEngine dibangun dengan sebuah LayoutRegion dan sebuah PageBreakStrategy dan mengembalikan sebuah LayoutResult berupa elemen yang ditempatkan dengan penetapan halaman dan posisi konkret.
• PageBreakStrategy memiliki tiga perilaku: Greedy (pecah ketika elemen berikutnya tidak muat), AvoidOrphans (pecah lebih awal, mencadangkan setidaknya dua tinggi elemen), dan KeepTogether (hormati keep-with-next sehingga elemen berpasangan tetap pada satu halaman ketika keduanya muat).
• Teks dan tabel dapat terpotong lintas halaman; gambar dan spacer ditempatkan secara atomik. Elemen yang lebih tinggi dari region tetap ditempatkan tetapi mungkin meluap.
• Mesin bersifat streaming: ia tidak menyimpan pohon dokumen yang utuh dan tidak melakukan I/O.
• Ini adalah mesin penempatan-elemen. Ia menghitung penetapan halaman dan posisi; ia bukan mesin perenderan HTML atau CSS.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Flow Layout. Enterprise menambahkan fitur tingkat-lebih-tinggi yang didokumentasikan terpisah; fitur tersebut tidak diwajibkan untuk menggunakan mesin penempatan.

Fallback / alternatif Core

Tidak ada mesin penempatan-elemen Core dengan strategi page-break. Untuk perenderan HTML-ke-PDF, gunakan pipeline HTML Core sumber terbuka. Lihat /modules/html/.

Batas publikasi

Halaman ini mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung saja. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Flow Layout — Deep Reference — referensi kelas dan metode lengkap.
• Document — penyusunan dokumen.
• Core HTML module — perenderan HTML-ke-PDF.