Legal — Referensi Mendalam

Sekilas

• Menghasilkan stempel nomor Bates berurutan sebagai fragmen content stream PDF per-halaman.
• Tiga tipe publik: BatesNumberConfig (konfigurasi imutabel), BatesNumberer (mesin), BatesPosition (enum posisi enam-kasus).
• Setiap fragmen bersifat mandiri. Graphics state disimpan dan dipulihkan, sehingga penambahan tidak pernah mengganggu konten halaman yang ada.
• Keluarannya deterministik: sebuah fragmen adalah fungsi murni dari konfigurasi, teks stempel, dan ukuran halaman.
• Modul ini tidak memunculkan exception apa pun. Input di luar rentang menurun secara anggun mengikuti aturan fallback yang terdokumentasi.

Ketersediaan & lisensi

Kapabilitas ini dikapalkan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada bendera lisensi per-fitur. Ini adalah kapabilitas edisi Pro.

composer require nextpdf/pro:^3

Permukaan API publik

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
BatesNumberConfig::__construct	string $prefix = '', string $suffix = '', int $startNumber = 1, int $padding = 5, BatesPosition $position = BatesPosition::BottomRight, float $fontSize = 9.0, string $fontFamily = 'Courier', float $opacity = 1.0, bool $useLayer = true, string $layerName = 'Bates Numbers', float $inset = 15.0	Konfigurasi tampilan dan penomoran yang imutabel	BatesNumberConfig	—	Kesebelas properti bersifat public dan readonly.
BatesNumberConfig::formatNumber	int $pageIndex (berbasis 0)	prefix + (startNumber + pageIndex) yang di-pad nol + suffix	string	—	Angka yang lebih lebar dari padding tidak dipotong.
BatesNumberConfig::getRange	int $pageCount	Stempel terformat pertama dan terakhir untuk proses tersebut	array{first: string, last: string}	—	Mengasumsikan pageCount >= 1; jumlah 0 memformat indeks halaman -1.
BatesNumberer::__construct	BatesNumberConfig $config	Mengikat konfigurasi	BatesNumberer	—	Kelas ini bersifat final dan readonly.
BatesNumberer::generate	int $pageCount, array $pageSizes, string $prefix = '', int $startFrom = 1	Jalur cepat statis dengan tampilan bawaan	list<string>	—	Suffix, position, font, opacity, dan layer tetap pada nilai bawaannya.
BatesNumberer::generateStreams	int $pageCount, list<array{width: float, height: float}> $pageSizes	Satu fragmen mandiri per halaman	list<string>	Tidak pernah throw; entri ukuran yang hilang jatuh ke A4 portrait	Jumlah fragmen sama dengan pageCount; entri ukuran berlebih diabaikan.
BatesNumberer::buildPageStream	string $text, float $pageWidth, float $pageHeight	Membangun fragmen stempel satu halaman	string	—	Dibungkus q/Q; teks stempel di-escape untuk sintaks literal-string.
BatesNumberer::getConfig	—	Mengembalikan konfigurasi yang terikat	BatesNumberConfig	—	—
BatesPosition	kasus enum BottomLeft, BottomCenter, BottomRight, TopLeft, TopCenter, TopRight	Kosakata posisi berbasis-string	—	—	Nilai backing bersifat kebab-case (misalnya bottom-right).
BatesPosition::coordinates	float $pageWidth, float $pageHeight, float $textWidth, float $inset = 15.0	X/Y untuk baseline stempel dalam ruang PDF-native	array{x: float, y: float}	—	Titik asal berada di kiri-bawah; baris atas menempatkan baseline inset dari tepi atas.

Signature titik masuk

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

Kontrak perilaku

Penomoran

BatesNumberConfig::formatNumber menghitung startNumber + pageIndex, mem-pad angka tersebut di kiri dengan nol hingga padding digit, dan membungkusnya dengan prefix dan suffix. getRange mengembalikan stempel terformat pertama dan terakhir untuk suatu jumlah halaman. Gunakan untuk merantai penomoran lanjutan antar production.

Anatomi fragmen

Setiap fragmen, secara berurutan, adalah: penyimpanan graphics-state (q), operator fill-color, awal marked-content opsional, blok teks yang memosisikan dan menampilkan stempel, akhir marked-content opsional, dan pemulihan (Q). Koordinat dan ukuran fon diserialkan dengan enam angka desimal, sehingga input yang identik menghasilkan byte yang identik. Teks stempel meng-escape \, (, dan ) sebelum masuk ke literal string.

Pengikatan fon

Blok teks memilih nama resource fon tetap /BatesFont. Resource dictionary halaman yang menyematkan harus memetakan nama tersebut ke sebuah fon yang cocok dengan fontFamily yang dikonfigurasi, dan keluarga tersebut harus dapat diselesaikan dalam registri fon. Pembuatan fragmen itu sendiri tidak pernah berkonsultasi dengan registri.

Penempatan

BatesPosition::coordinates menghitung baseline stempel dalam ruang PDF-native; titik asalnya di kiri-bawah. Penempatan tengah dan kanan mengurangi perkiraan lebar teks: panjang byte dikali 0.6 dikali ukuran fon, sebuah aproksimasi monospace. Fon proporsional dan teks multi-byte menggeser perkiraan tersebut. Penempatan kiri tidak bergantung padanya.

Layer

Dengan useLayer diaktifkan (bawaan), fragmen membungkus teks di antara operator marked-content BDC dan EMC. Nama marked-content memiliki bentuk /Lyr_<name>, diturunkan dari layerName dengan karakter non-word diganti oleh garis bawah. Pembungkusan tersebut hanya bersifat tingkat-fragmen: pendaftaran optional content group yang bersesuaian dalam dokumen — langkah yang membuat layer dapat di-toggle di penampil — adalah tanggung jawab writer yang menyematkan.

Opasitas

opacity di bawah 1.0 dipancarkan sebagai fill grayscale yang lebih terang. Stempel yang sepenuhnya opak dirender hitam.

Cakupan

Mesin menerapkan penomoran Bates persis sebagaimana dikonfigurasi. Ia tidak menegaskan bahwa dokumen bernomor dapat diterima di pengadilan atau sah secara hukum. Skema penomoran, retensi, dan penanganan barang bukti tetap menjadi tanggung jawab pelanggan; konsultasikan dengan tim hukum dan kepatuhan Anda untuk kecukupan prosedural.

Kasus tepi & mode kegagalan

• generateStreams tidak pernah throw pada ketidaksesuaian pageSizes. Entri yang hilang jatuh ke A4 portrait, 595.276 kali 841.890 poin; entri berlebih diabaikan.
• Jumlah fragmen selalu sama dengan pageCount.
• Angka yang lebih lebar dari padding tidak dipotong; teks stempel hanya bertambah panjang.
• getRange mengasumsikan pageCount >= 1. Jumlah 0 memformat indeks halaman -1, yaitu startNumber - 1.
• Opasitas adalah pencerahan grayscale, bukan transparansi ExtGState; konten yang tumpang tindih di bawah stempel tidak di-blend.
• Byte stempel selain \, (, dan ) diteruskan tanpa disandikan. Ketepatan penyandian untuk teks non-ASCII bergantung pada fon yang terikat.
• Tanda Bates adalah konten overlay. Ia tidak menyamarkan, menghapus, atau mengenkripsi apa pun pada halaman.
• Modul tidak melakukan operasi kriptografis apa pun; mode FIPS tidak mengubah perilakunya.

Kesesuaian

Behavior	Reference	Status
Pembungkusan layer via operator marked-content BDC/EMC	ISO 32000-2:2020 §8.11.3.2	Parsial — fragmen memancarkan pembungkusan; pendaftaran optional content group adalah langkah writer yang menyematkan

Baris-baris ini mencatat spesifikasi yang menjadi dasar pembangunan modul, bukan sebuah sertifikasi; NextPDF tidak memegang sertifikasi kesesuaian apa pun. Tabel ini juga bukan pernyataan keabsahan hukum atau kecukupan barang bukti.

Catatan pengembangan

• Fragmen adalah nilai string murni. Uji dengan perbandingan byte langsung; tidak diperlukan konteks dokumen.
• buildPageStream bersifat publik dan dapat diuji-unit secara terisolasi: berikan teks yang telah diformat dan dimensi halaman eksplisit.
• Untuk penomoran lanjutan antar production, seed startNumber dari proses sebelumnya dan catat keluaran getRange di log production Anda.
• Nama layer dibersihkan menjadi karakter word. Utamakan nama layer ASCII agar nama marked-content tetap terbaca di peralatan inspeksi.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang teramati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Ikhtisar kapabilitas Legal
• Merge — Referensi Mendalam
• Security — Referensi Mendalam