Chart — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi tingkat-kontrak untuk modul Chart NextPDF Pro. Permukaannya terdiri dari lima kelas publik di NextPDF\Pro\Chart: renderer BarChart, LineChart, dan PieChart, persegi panjang penempatan ChartBox, dan objek nilai ChartColor. Setiap renderer adalah primitif penggambaran. Sebuah static factory membuatnya, panggilan with*() yang fluent mengonfigurasinya, dan render(ChartBox $box): string mengembalikan operator content-stream PDF untuk persegi panjang yang disuplai. Keluarannya vector-only dan deterministik: input dan konfigurasi yang identik menghasilkan byte yang identik. Input degenerate mengembalikan string kosong alih-alih melempar, sehingga sebuah chart tidak pernah merusak halaman di sekitarnya. Tampilan berorientasi tugas ada di halaman kapabilitas.

Ketersediaan & lisensi

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

Renderer chart dilisensikan sebagai kapabilitas di bawah keluarga kapabilitas chart.*. Ketika kapabilitas tidak dilisensikan, renderer chart tidak tersedia.

Permukaan API publik

composer require nextpdf/pro:^3

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
BarChart::fromData()	list<string> $labels, list<int|float> $values	Nilai di-cast ke float	self	Tidak melempar	Satu-satunya jalur konstruksi; constructor bersifat private
BarChart::withBarColor()	ChartColor $color	Isian bar; default adalah entri palet 0	self	Tidak melempar	Fluent; memutasi receiver
BarChart::withAxisColor()	ChartColor $color	Goresan sumbu; default #333333	self	Tidak melempar	—
BarChart::withBarGap()	float $gap	Jarak sebagai fraksi lebar slot; default 0.2	self	Tidak melempar	Diclamp ke 0.0–0.9; input di luar rentang diclamp, bukan ditolak
BarChart::withFontSize()	float $size	Ukuran font label dalam poin; default 7.0	self	Tidak melempar	—
BarChart::render()	ChartBox $box	Sumbu, bar, label kategori, lima tick nilai	operator string	Tidak melempar; data kosong mengembalikan ''	Nilai maksimum non-positif diskalakan terhadap 1.0
LineChart::create()	list<string> $labels	Chart tanpa series	self	Tidak melempar	Constructor bersifat private
LineChart::fromData()	list<string> $labels, list<int|float> $values	Menambahkan satu series tanpa nama	self	Tidak melempar	Kemudahan single-series
LineChart::addSeries()	string $name, list<int|float> $values, ?ChartColor $color = null	Warna null otomatis diberikan dari palet berdasarkan indeks series	self	Tidak melempar	Nama series dicadangkan untuk penggunaan legenda
LineChart::withAxisColor()	ChartColor $color	Goresan sumbu; default #333333	self	Tidak melempar	—
LineChart::withLineWidth()	float $width	Lebar goresan series; default 1.5	self	Tidak melempar	—
LineChart::withFontSize()	float $size	Ukuran font label; default 7.0	self	Tidak melempar	—
LineChart::withDots()	bool $show, float $radius = 2.5	Penanda titik data; aktif secara default	self	Tidak melempar	Penanda digambar sebagai lingkaran yang diaproksimasi Bezier
LineChart::withGrid()	bool $show	Grid kuartil horizontal; aktif secara default	self	Tidak melempar	—
LineChart::render()	ChartBox $box	Grid, sumbu, satu path per series, label	operator string	Tidak melempar; tanpa series mengembalikan ''	Series yang lebih pendek dari dua titik tidak menggambar path
PieChart::fromData()	list<string> $labels, list<int|float> $values	Proporsi dihitung dari jumlah nilai	self	Tidak melempar	Constructor bersifat private
PieChart::withColors()	list<ChartColor> $colors	Satu warna per irisan, secara berurutan	self	Tidak melempar	Entri yang hilang di-fallback ke palet
PieChart::withStrokeColor()	ChartColor $color	Garis luar irisan; default putih	self	Tidak melempar	—
PieChart::withFontSize()	float $size	Ukuran font label; default 7.0	self	Tidak melempar	—
PieChart::withPercentages()	bool $show	Label persentase; aktif secara default	self	Tidak melempar	Label hanya dirender pada irisan yang menyapu lebih dari 15 derajat
PieChart::withLegend()	bool $show	Legenda di sisi kanan; aktif secara default	self	Tidak melempar	Legenda mencadangkan 80 poin lebar box
PieChart::render()	ChartBox $box	Sektor, label opsional, legenda opsional	operator string	Tidak melempar; data kosong atau total pada atau di bawah nol mengembalikan ''	Busur dipecah menjadi segmen Bezier paling banyak 90 derajat
ChartBox::__construct()	float $x, float $y, float $width, float $height	Origin kiri-bawah PDF, dalam poin	—	Tidak melempar	final readonly; dimensi tidak divalidasi
ChartBox::fromUserSpace()	float $x, float $y, float $width, float $height, float $pageHeight	Membalik persegi panjang origin kiri-atas ke koordinat PDF	self	Tidak melempar	—
ChartBox::right()	tidak ada	x + width	float	Tidak melempar	Method, bukan property
ChartBox::top()	tidak ada	y + height	float	Tidak melempar	Method, bukan property
ChartBox::inset()	float $left, float $bottom, float $right, float $top	Sub-box yang disusutkan oleh inset yang diberikan	self	Tidak melempar	Inset yang berlebihan menghasilkan dimensi negatif; tidak divalidasi
ChartColor::__construct()	float $r, float $g, float $b, masing-masing 0.0–1.0	—	—	Tidak melempar	final readonly; komponen tidak diclamp
ChartColor::rgb()	int $r, int $g, int $b, masing-masing 0–255	Menskalakan komponen ke 0.0–1.0	self	Tidak melempar	—
ChartColor::hex()	string $hex	Menerima hex enam digit berawalan # atau tanpa awalan	self	Tidak melempar	Digit akhir yang tidak ada didekode sebagai nol
ChartColor::palette()	int $index	Palet 12-warna bawaan	self	TypeError pada indeks negatif	Indeks non-negatif membungkus modulo 12
ChartColor::strokeOperator()	tidak ada	Operator warna goresan (RG), tiga desimal	string	Tidak melempar	Method, bukan property
ChartColor::fillOperator()	tidak ada	Operator warna isian (rg), tiga desimal	string	Tidak melempar	Method, bukan property

Tanda tangan entry-point

public static function fromData(array $labels, array $values): self
public function withBarColor(ChartColor $color): self
public function withAxisColor(ChartColor $color): self
public function withBarGap(float $gap): self
public function withFontSize(float $size): self
public function render(ChartBox $box): string

public static function create(array $labels): self
public static function fromData(array $labels, array $values): self
public function addSeries(string $name, array $values, ?ChartColor $color = null): self
public function withAxisColor(ChartColor $color): self
public function withLineWidth(float $width): self
public function withFontSize(float $size): self
public function withDots(bool $show, float $radius = 2.5): self
public function withGrid(bool $show): self
public function render(ChartBox $box): string

public static function fromData(array $labels, array $values): self
public function withColors(array $colors): self
public function withStrokeColor(ChartColor $color): self
public function withFontSize(float $size): self
public function withPercentages(bool $show): self
public function withLegend(bool $show): self
public function render(ChartBox $box): string

public function __construct(
    public float $x,
    public float $y,
    public float $width,
    public float $height,
)

public static function fromUserSpace(
    float $x,
    float $y,
    float $width,
    float $height,
    float $pageHeight,
): self

public function right(): float
public function top(): float
public function inset(float $left, float $bottom, float $right, float $top): self

public static function rgb(int $r, int $g, int $b): self
public static function hex(string $hex): self
public static function palette(int $index): self
public function strokeOperator(): string
public function fillOperator(): string

Kontrak perilaku

Bentuk renderer umum

Ketiga renderer mengikuti satu daur hidup: sebuah static factory, konfigurasi fluent, satu panggilan render(). Method konfigurasi memutasi receiver dan mengembalikannya; renderer bukan objek nilai yang immutable. render() membaca konfigurasi tanpa memutasinya, sehingga satu renderer yang telah dikonfigurasi dapat dirender ke beberapa box. Setiap render membungkus keluarannya dalam pasangan save/restore graphics-state, sehingga state chart tidak pernah bocor ke halaman. Koordinat dikeluarkan pada dua desimal dan komponen warna pada tiga, yang menjaga keluaran tetap byte-stable. Teks dirender melalui nama resource font /ChartFont pada ukuran yang dikonfigurasi; pemanggil mendaftarkan sebuah font di bawah nama tersebut dalam kamus resource halaman target. String label meng-escape backslash dan tanda kurung sebelum masuk ke operand string. Renderer tidak melakukan reflow, tidak melakukan clipping, dan tidak melakukan negosiasi kontainer: pemanggil yang memiliki penempatan.

Penskalaan dan tata letak

Bar chart dan line chart mencadangkan inset plot tetap di dalam box: 40 poin kiri, 20 bawah, 10 kanan, 10 atas. Area plot yang tersisa menskalakan nilai secara linear terhadap maksimum series. Maksimum nol atau di bawahnya diskalakan terhadap 1.0, sehingga data serba-nol merender sumbu dengan konten datar alih-alih membagi dengan nol. Keduanya menggambar sumbu X dan Y pada lebar 0,5 poin dan lima tick nilai pada posisi kuartil. Bar chart memformat nilai tick dengan sufiks K dan M di atas seribu dan sejuta; line chart mencetak angka biasa.

Bar chart

Setiap nilai menempati sebuah slot yang sama di sepanjang lebar plot. Bar mengisi slot dikurangi fraksi jarak yang dikonfigurasi dan dipusatkan di dalam slot. Label kategori digambar 12 poin di bawah area plot.

Line chart

Grid, ketika diaktifkan, menggambar empat garis kuartil horizontal dalam abu-abu muda (0.85 0.85 0.85 RG) di bawah sumbu dan series. Setiap series menggambar satu polyline melalui titik-titiknya, membentang di seluruh lebar plot. Penanda opsional digambar sebagai lingkaran Bezier empat-segmen di setiap titik data. Warna series secara default adalah entri palet berurutan dalam urutan penyisipan.

Pie chart

Irisan ditata dalam urutan data, dimulai dari sumbu X positif dan menyapu berlawanan arah jarum jam. Setiap path sektor menutup dan mengecat dengan isian dan goresan gabungan (h B); busur dipecah menjadi segmen Bezier paling banyak 90 derajat. Label persentase dibulatkan ke persen bulat dan hanya dirender pada irisan yang menyapu lebih dari 15 derajat. Legenda, ketika diaktifkan, mencadangkan 80 poin lebar box di sebelah kanan dan merender swatch 8-poin per entri pada tinggi baris 12-poin. Radius adalah setengah dari yang lebih kecil antara lebar yang tersisa dan tinggi box, dikurangi margin 10-poin.

Objek nilai penempatan dan warna

ChartBox adalah persegi panjang immutable dalam unit pengguna PDF (poin) dengan origin kiri-bawah. ChartBox::fromUserSpace() mengonversi persegi panjang origin kiri-atas dengan membaliknya terhadap tinggi halaman yang disuplai. inset() mengembalikan box baru yang lebih kecil; right() dan top() adalah method accessor. ChartColor bersifat mandiri dan tidak bergantung pada kelas warna Core. Palet 12-entri-nya menetapkan warna series dan irisan ketika pemanggil tidak menyediakannya.

Matriks dukungan (didukung bukti)

Sebuah tipe atau fitur chart memperoleh Verified hanya ketika sebuah fixture pro/tests/** menjalankannya. Tidak ada standar eksternal yang mengatur chart, sehingga buktinya adalah cakupan perilaku tingkat-unit.

Tipe / fitur chart	Status	Bukti (path pengujian)	Keyakinan	Catatan
Bar chart — render, sumbu, persegi panjang bar, clamping jarak, data kosong/serba-nol, pemformatan nilai K/M	Verified	pro/tests/Unit/Chart/BarChartTest.php; BarChartArithmeticCoverageTest.php; BarChartBoundaryCoverageTest.php	high	Pembungkusan graphics-state, garis sumbu, proporsi tinggi bar, hitungan tick, dan batas pemformatan diassert.
Line chart — single dan multi-series, path garis, sumbu, dot, grid, single-point	Verified	pro/tests/Unit/Chart/LineChartTest.php; LineChartCoverageTest.php; LineChartArithmeticCoverageTest.php; LineChartTypeCastCoverageTest.php	high	Multi-series, single-point tanpa-garis, empty-series, path grid dan dot tercakup.
Pie chart — sektor, segmentasi Bezier, persentase, legenda, total nol/negatif	Verified	pro/tests/Unit/Chart/PieChartTest.php; PieChartArithmeticCoverageTest.php; PieChartBoundaryCoverageTest.php	high	Path sektor, hitungan segmen per sapuan, ambang label 15-derajat, geometri legenda, dan perilaku empty-string tercakup.
ChartBox — konversi koordinat (user space ke PDF), atas/bawah halaman, dimensi nol, inset	Verified	pro/tests/Unit/Chart/ChartBoxTest.php	high	Konversi origin kiri-atas ke origin kiri-bawah pada atas halaman, bawah, dan tepi berdimensi-nol.
ChartColor — penskalaan RGB, parsing hex, palet, operator stroke/fill	Verified	pro/tests/Unit/Chart/ChartColorTest.php	high	Penskalaan 0–255 ke 0–1, hex berawalan # dan tanpa awalan, huruf campuran, pembungkusan palet setelah 12 entri.
Pengerasan regresi lintas-renderer	Verified	pro/tests/Unit/Chart/ChartCoverageTest.php	high	Suite regresi bersama di seluruh ketiga renderer ditambah aritmetika pemformatan nilai.
Tipe chart di luar bar/line/pie (area, scatter, stacked, donut, dll.)	Not supported	—	high	Tidak ada renderer yang dikirim. Permukaan modul persis bar, line, pie. Dinyatakan jujur: ini bukan “setiap tipe chart”.

Hitungan jujur: Verified 6 baris, Claimed 0, Not supported 1 (tipe chart apa pun selain bar, line, pie).

Kasus tepi & mode kegagalan

• Tidak ada renderer yang melempar pada data. Input degenerate terdegradasi menjadi string kosong: data bar atau line kosong, daftar series kosong, dan total pie pada atau di bawah nol semuanya mengembalikan ''.
• Sebuah line series dengan kurang dari dua titik tidak menggambar path dan tidak ada penanda; sumbu dan label tetap dirender.
• Nilai bar negatif tidak ditolak; persegi panjang bar memanjang di bawah sumbu X.
• Hitungan label dan nilai tidak divalidasi silang. Pemanggil menyuplai daftar dengan panjang yang cocok.
• Sebuah ChartBox dengan dimensi nol atau negatif diterima dan menghasilkan keluaran degenerate; pemanggil harus mengukur box.
• Renderer tidak melakukan clipping. Sebuah chart yang berukuran berlebihan, label kategorinya di bawah plot, atau legenda yang panjang dapat melampaui region halaman yang dituju.
• Sebuah halaman yang tidak memiliki font di bawah nama resource font chart menyisakan operator teks yang mereferensikan resource yang tidak terdefinisi; perilaku viewer kemudian menjadi tidak terdefinisi.
• ChartColor::hex() tidak melakukan validasi; input yang lebih pendek dari enam digit mendekode komponen yang tidak ada sebagai nol. ChartColor::palette() gagal dengan TypeError pada indeks negatif, karena modulo negatif PHP tidak menyelesaikan kunci palet.
• Modul tidak melakukan kriptografi; mode FIPS tidak memiliki perilaku spesifik-chart.

Konformansi

Modul Chart mengeluarkan operator content-stream PDF. Tidak ada standar chart, simbologi, atau kriptografi eksternal yang mengatur keluarannya, sehingga satu-satunya permukaan konformansi adalah stream operator yang dikeluarkan.

Klaim	Standar	Klausul
Grafis yang dikeluarkan mengikuti model operator content-stream; keluaran bersarang di dalam graphics state yang disimpan dan dipulihkan.	ISO 32000-2	§8.1
Bar, garis, sektor, dan penanda adalah objek path: konstruksi dimulai dengan m atau re dan diakhiri dengan operator path-painting.	ISO 32000-2	§8.5.2
Label dirender sebagai objek teks: posisi ditetapkan setelah BT, dan glyph dicat dengan operator text-showing Tj.	ISO 32000-2	§9.2.2, §9.4.3

Semua klausul diparafrasekan; halaman ini tidak mereproduksi teks normatif. Ini adalah pernyataan kapabilitas, bukan sertifikasi; NextPDF tidak memegang sertifikasi dan tidak memberikan apa pun. Rendering stream yang benar juga bergantung pada dokumen yang melingkupinya yang well-formed, yang merupakan tanggung jawab penulis dokumen.

Catatan pengembangan

• Kelima kelas membawa @since 1.9.0 dan sedang berlaku di nextpdf/pro 3.1.0.
• Modul ini bersifat mandiri: renderer hanya bergantung pada ChartBox dan ChartColor, tanpa kopling Core.
• Keluaran deterministik menjaga dokumen berbagan tetap reproducible, diff-stable, dan aman untuk ditandatangani atau diarsipkan.
• Daftarkan sebuah font di bawah nama resource font chart sekali per halaman yang menampung chart.
• Gunakan kembali renderer yang telah dikonfigurasi di seluruh box dengan bebas; render() tidak melakukan mutasi state.
• Bukti pengujian ada di bawah pro/tests/Unit/Chart/; matriks dukungan menautkan setiap baris Verified ke suite-nya.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati 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

• Chart (kapabilitas) — ikhtisar berorientasi tugas, instalasi, dan contoh kode.
• Barcode — Referensi Mendalam — permukaan penggambaran Pro serumpun dengan matriks dukungannya sendiri yang didukung bukti.