Pro 에디션

Chart — 심층 참조

한눈에 보기

이 페이지는 NextPDF Pro Chart 모듈에 대한 계약 수준 레퍼런스입니다. 표면은 NextPDF\Pro\Chart에 있는 다섯 개의 공개 클래스입니다. BarChart, LineChart, PieChart 렌더러, ChartBox 배치 사각형, 그리고 ChartColor 값 객체입니다. 각 렌더러는 그리기 프리미티브입니다. 정적 팩토리가 이를 생성하고, 플루언트 with*() 호출이 이를 구성하며, render(ChartBox $box): string이 제공된 사각형에 대한 PDF 콘텐츠 스트림 연산자를 반환합니다. 출력은 벡터 전용이며 결정적입니다. 동일한 입력과 구성은 동일한 바이트를 생성합니다. 퇴화된 입력은 예외를 던지는 대신 빈 문자열을 반환하므로, chart가 주변 페이지를 깨뜨리는 일은 결코 없습니다. 작업 중심 관점은 기능 페이지에 있습니다.

제공 여부 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 엔타이틀먼트가 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으세요.

Chart 렌더러는 chart.* 기능 패밀리 아래에서 기능별로 라이선스가 부여됩니다. 해당 기능에 라이선스가 없으면 chart 렌더러를 사용할 수 없습니다.

공개 API 표면

composer require nextpdf/pro:^3

심볼	매개변수	기본 동작	반환값	던지거나 실패하는 경우	비고
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	값은 float로 캐스트됩니다	`self`	던지지 않음	유일한 생성 경로. 생성자는 private입니다
`BarChart::withBarColor()`	`ChartColor $color`	막대 채우기. 기본값은 팔레트 항목 0	`self`	던지지 않음	플루언트. 수신자를 변경합니다
`BarChart::withAxisColor()`	`ChartColor $color`	축 스트로크. 기본값 `#333333`	`self`	던지지 않음	—
`BarChart::withBarGap()`	`float $gap`	슬롯 너비 대비 비율로서의 간격. 기본값 `0.2`	`self`	던지지 않음	`0.0`–`0.9`로 클램프. 범위를 벗어난 입력은 거부되지 않고 클램프됩니다
`BarChart::withFontSize()`	`float $size`	레이블 글꼴 크기(포인트). 기본값 `7.0`	`self`	던지지 않음	—
`BarChart::render()`	`ChartBox $box`	축, 막대, 카테고리 레이블, 다섯 개의 값 눈금	`string` 연산자	던지지 않음. 빈 데이터는 `''` 반환	양수가 아닌 최댓값은 `1.0`에 대해 스케일됩니다
`LineChart::create()`	`list<string> $labels`	시리즈 없는 chart	`self`	던지지 않음	생성자는 private입니다
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	이름 없는 시리즈 하나를 추가	`self`	던지지 않음	단일 시리즈 편의 기능
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	`null` 색상은 시리즈 인덱스에 따라 팔레트에서 자동 할당됩니다	`self`	던지지 않음	시리즈 이름은 범례용으로 예약됩니다
`LineChart::withAxisColor()`	`ChartColor $color`	축 스트로크. 기본값 `#333333`	`self`	던지지 않음	—
`LineChart::withLineWidth()`	`float $width`	시리즈 스트로크 너비. 기본값 `1.5`	`self`	던지지 않음	—
`LineChart::withFontSize()`	`float $size`	레이블 글꼴 크기. 기본값 `7.0`	`self`	던지지 않음	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	데이터 포인트 마커. 기본적으로 켜짐	`self`	던지지 않음	마커는 Bezier 근사 원으로 그려집니다
`LineChart::withGrid()`	`bool $show`	수평 사분위 그리드. 기본적으로 켜짐	`self`	던지지 않음	—
`LineChart::render()`	`ChartBox $box`	그리드, 축, 시리즈당 하나의 경로, 레이블	`string` 연산자	던지지 않음. 시리즈 없음은 `''` 반환	두 점 미만인 시리즈는 경로를 그리지 않습니다
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	값 합계로부터 비율을 계산	`self`	던지지 않음	생성자는 private입니다
`PieChart::withColors()`	`list<ChartColor> $colors`	순서대로 슬라이스당 하나의 색상	`self`	던지지 않음	누락된 항목은 팔레트로 폴백합니다
`PieChart::withStrokeColor()`	`ChartColor $color`	슬라이스 외곽선. 기본값 흰색	`self`	던지지 않음	—
`PieChart::withFontSize()`	`float $size`	레이블 글꼴 크기. 기본값 `7.0`	`self`	던지지 않음	—
`PieChart::withPercentages()`	`bool $show`	백분율 레이블. 기본적으로 켜짐	`self`	던지지 않음	레이블은 15도를 초과하여 휩쓰는 슬라이스에만 렌더링됩니다
`PieChart::withLegend()`	`bool $show`	우측 범례. 기본적으로 켜짐	`self`	던지지 않음	범례는 박스 너비 중 80포인트를 예약합니다
`PieChart::render()`	`ChartBox $box`	섹터, 선택적 레이블, 선택적 범례	`string` 연산자	던지지 않음. 빈 데이터 또는 0 이하 합계는 `''` 반환	호는 최대 90도의 Bezier 세그먼트로 분할됩니다
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	PDF 좌하단 원점, 포인트 단위	—	던지지 않음	`final readonly`. 치수는 검증되지 않습니다
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	좌상단 원점 사각형을 PDF 좌표로 뒤집습니다	`self`	던지지 않음	—
`ChartBox::right()`	없음	`x + width`	`float`	던지지 않음	프로퍼티가 아니라 메서드
`ChartBox::top()`	없음	`y + height`	`float`	던지지 않음	프로퍼티가 아니라 메서드
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	주어진 인셋만큼 축소된 서브 박스	`self`	던지지 않음	과대한 인셋은 음수 치수를 생성합니다. 검증되지 않습니다
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, 각각 `0.0`–`1.0`	—	—	던지지 않음	`final readonly`. 컴포넌트는 클램프되지 않습니다
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, 각각 `0`–`255`	컴포넌트를 `0.0`–`1.0`로 스케일	`self`	던지지 않음	—
`ChartColor::hex()`	`string $hex`	`#` 접두사 또는 베어 6자리 16진수를 허용	`self`	던지지 않음	누락된 후행 자릿수는 0으로 디코드됩니다
`ChartColor::palette()`	`int $index`	내장 12색 팔레트	`self`	음수 인덱스에서 `TypeError`	음수가 아닌 인덱스는 modulo 12로 순환합니다
`ChartColor::strokeOperator()`	없음	스트로크 색상 연산자(`RG`), 소수점 세 자리	`string`	던지지 않음	프로퍼티가 아니라 메서드
`ChartColor::fillOperator()`	없음	채우기 색상 연산자(`rg`), 소수점 세 자리	`string`	던지지 않음	프로퍼티가 아니라 메서드

진입점 시그니처

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

동작 계약

공통 렌더러 형태

세 렌더러 모두 하나의 수명 주기를 따릅니다. 정적 팩토리, 플루언트 구성, 하나의 render() 호출입니다. 구성 메서드는 수신자를 변경하고 이를 반환합니다. 렌더러는 불변 값 객체가 아닙니다. render()는 구성을 변경하지 않고 읽으므로, 하나의 구성된 렌더러가 여러 박스에 렌더링할 수 있습니다. 모든 렌더는 출력을 저장/복원 그래픽 상태 쌍으로 감싸므로, chart 상태가 페이지로 새어 나가는 일은 결코 없습니다. 좌표는 소수점 두 자리로, 색상 컴포넌트는 세 자리로 방출되어 출력이 바이트 안정적으로 유지됩니다. 텍스트는 구성된 크기로 /ChartFont 글꼴 리소스 이름을 통해 렌더링됩니다. 호출자는 대상 페이지의 리소스 딕셔너리에 해당 이름으로 글꼴을 등록합니다. 레이블 문자열은 문자열 피연산자에 들어가기 전에 백슬래시와 괄호를 이스케이프합니다. 렌더러는 리플로, 클리핑, 컨테이너 협상을 수행하지 않습니다. 배치는 호출자의 몫입니다.

스케일링 및 레이아웃

Bar chart와 line chart는 박스 안에 고정된 플롯 인셋을 예약합니다. 왼쪽 40포인트, 아래 20포인트, 오른쪽 10포인트, 위 10포인트입니다. 남은 플롯 영역은 값을 시리즈 최댓값에 대해 선형으로 스케일합니다. 0 이하의 최댓값은 대신 1.0에 대해 스케일하므로, 전부 0인 데이터는 0으로 나누지 않고 평평한 내용의 축을 렌더링합니다. 둘 다 X축과 Y축을 0.5포인트 너비로, 다섯 개의 값 눈금을 사분위 위치에 그립니다. Bar chart는 천 단위와 백만 단위 초과에서 눈금 값을 K와 M 접미사로 형식화합니다. Line chart는 일반 숫자를 출력합니다.

막대 차트

각 값은 플롯 너비 전반에 걸쳐 동일한 슬롯을 차지합니다. 막대는 슬롯에서 구성된 간격 비율을 뺀 만큼을 채우고 슬롯 안에서 중앙에 배치됩니다. 카테고리 레이블은 플롯 영역 아래 12포인트에 그려집니다.

선 차트

그리드는 활성화되면 축과 시리즈 아래에 밝은 회색(0.85 0.85 0.85 RG)으로 네 개의 수평 사분위 선을 그립니다. 각 시리즈는 자신의 점들을 통과하는 하나의 폴리라인을 그리며, 전체 플롯 너비에 걸칩니다. 선택적 마커는 각 데이터 포인트에서 네 세그먼트 Bezier 원으로 그려집니다. 시리즈 색상은 삽입 순서로 연속된 팔레트 항목을 기본값으로 합니다.

파이 차트

슬라이스는 데이터 순서대로, 양의 X축에서 시작하여 반시계 방향으로 휩쓸며 배치됩니다. 각 섹터 경로는 닫히고 결합된 채우기와 스트로크(h B)로 페인팅됩니다. 호는 최대 90도의 Bezier 세그먼트로 분할됩니다. 백분율 레이블은 정수 백분율로 반올림되고 15도를 초과하여 휩쓰는 슬라이스에만 렌더링됩니다. 범례는 활성화되면 오른쪽에 박스 너비 중 80포인트를 예약하고 12포인트 줄 높이로 항목당 8포인트 스와치를 렌더링합니다. 반지름은 남은 너비와 박스 높이 중 작은 값의 절반에서 10포인트 여백을 뺀 것입니다.

배치 및 색상 값 객체

ChartBox는 좌하단 원점을 가진 PDF 사용자 단위(포인트)의 불변 사각형입니다. ChartBox::fromUserSpace()는 제공된 페이지 높이에 대해 뒤집어 좌상단 원점 사각형을 변환합니다. inset()은 새로운 더 작은 박스를 반환하고, right()와 top()은 접근자 메서드입니다. ChartColor는 자체 완결적이며 Core 색상 클래스에 의존하지 않습니다. 12개 항목 팔레트는 호출자가 아무것도 제공하지 않을 때 시리즈와 슬라이스 색상을 할당합니다.

지원 매트릭스 (근거 기반)

chart 유형이나 기능은 pro/tests/** 픽스처가 이를 실행할 때만 Verified를 얻습니다. chart를 관장하는 외부 표준이 없으므로, 근거는 단위 수준 동작 커버리지입니다.

chart 유형 / 기능	상태	근거 (테스트 경로)	신뢰도	비고
Bar chart — render, axes, bar rectangles, gap clamping, empty/all-zero data, K/M value formatting	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	그래픽 상태 래핑, 축 선, 막대 높이 비율, 눈금 개수, 형식화 경계가 단언됩니다.
Line chart — single and multi-series, line path, axes, dots, grid, single-point	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	다중 시리즈, 단일 점 무선(no-line), 빈 시리즈, 그리드 및 점 경로가 다뤄집니다.
Pie chart — sectors, Bezier segmentation, percentages, legend, zero/negative total	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	섹터 경로, 휩쓰기당 세그먼트 개수, 15도 레이블 임계값, 범례 기하, 빈 문자열 동작이 다뤄집니다.
`ChartBox` — coordinate conversion (user space to PDF), page top/bottom, zero dims, inset	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	페이지 상단, 하단, 0 치수 가장자리에서 좌상단 원점에서 좌하단 원점으로의 변환.
`ChartColor` — RGB scaling, hex parsing, palette, stroke/fill operators	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	high	0–255에서 0–1 스케일링, `#` 접두사 및 베어 16진수, 대소문자 혼합, 12개 항목 이후 팔레트 순환.
Cross-renderer regression hardening	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	세 렌더러 전반의 공유 회귀 스위트와 값 형식화 산술.
Chart types beyond bar/line/pie (area, scatter, stacked, donut, etc.)	Not supported	—	high	렌더러가 제공되지 않습니다. 모듈 표면은 정확히 bar, line, pie입니다. 정직하게 밝힙니다. 이는 “모든 chart 유형”이 아닙니다.

정직한 집계: Verified 6 행, Claimed 0, Not supported 1(bar, line, pie 이외의 모든 chart 유형).

엣지 케이스 및 실패 모드

어떤 렌더러도 데이터에 대해 던지지 않습니다. 퇴화된 입력은 빈 문자열로 강등됩니다. 빈 bar 또는 line 데이터, 빈 시리즈 목록, 0 이하의 pie 합계는 모두 ''를 반환합니다.
두 점 미만인 line 시리즈는 경로도 마커도 그리지 않습니다. 축과 레이블은 여전히 렌더링됩니다.
음수 막대 값은 거부되지 않습니다. 막대 사각형이 X축 아래로 확장됩니다.
레이블과 값 개수는 상호 검증되지 않습니다. 호출자가 길이가 일치하는 목록을 제공합니다.
0 또는 음수 치수의 ChartBox는 허용되며 퇴화된 출력을 생성합니다. 호출자가 박스 크기를 지정해야 합니다.
렌더러는 클리핑하지 않습니다. 과대한 chart, 그 플롯 아래 카테고리 레이블, 또는 긴 범례는 의도된 페이지 영역을 넘칠 수 있습니다.
chart 글꼴 리소스 이름으로 글꼴이 없는 페이지는 정의되지 않은 리소스를 참조하는 텍스트 연산자를 남깁니다. 그때 뷰어 동작은 정의되지 않습니다.
ChartColor::hex()는 검증을 수행하지 않습니다. 6자리보다 짧은 입력은 누락된 컴포넌트를 0으로 디코드합니다. ChartColor::palette()는 음수 인덱스에서 TypeError로 실패합니다. PHP의 음수 modulo가 어떤 팔레트 키도 해결하지 못하기 때문입니다.
이 모듈은 암호화를 수행하지 않습니다. FIPS 모드는 chart 관련 동작이 없습니다.

적합성

Chart 모듈은 PDF 콘텐츠 스트림 연산자를 방출합니다. 그 출력을 관장하는 외부 chart, 심볼로지, 암호화 표준이 없으므로, 유일한 적합성 표면은 방출된 연산자 스트림입니다.

주장	표준	조항
방출된 그래픽은 콘텐츠 스트림 연산자 모델을 따릅니다. 출력은 저장되고 복원된 그래픽 상태 안에 중첩됩니다.	ISO 32000-2	§8.1
막대, 선, 섹터, 마커는 경로 객체입니다. 구성은 `m` 또는 `re`로 시작하여 경로 페인팅 연산자로 끝납니다.	ISO 32000-2	§8.5.2
레이블은 텍스트 객체로 렌더링됩니다. 위치는 `BT` 이후에 설정되고, 글리프는 `Tj` 텍스트 표시 연산자로 페인팅됩니다.	ISO 32000-2	§9.2.2, §9.4.3

모든 조항은 의역되었습니다. 이 페이지는 어떤 규범 텍스트도 재현하지 않습니다. 이는 기능 진술이지 인증이 아닙니다. NextPDF는 어떤 인증도 보유하지 않으며 어떤 인증도 부여하지 않습니다. 스트림의 올바른 렌더링은 둘러싸는 문서가 올바르게 구성되어 있는지에도 달려 있으며, 이는 문서 작성자의 책임입니다.

개발 노트

다섯 클래스 모두 @since 1.9.0을 지니며 nextpdf/pro 3.1.0에서 최신 상태입니다.
모듈은 자체 완결적입니다. 렌더러는 ChartBox와 ChartColor에만 의존하며 Core 결합이 없습니다.
결정적 출력은 차트가 포함된 문서를 재현 가능하고 diff 안정적이며 서명하거나 아카이브하기에 안전하게 유지합니다.
chart를 호스팅하는 각 페이지에서 chart 글꼴 리소스 이름으로 글꼴을 한 번 등록하세요.
구성된 렌더러를 박스 전반에 걸쳐 자유롭게 재사용하세요. render()는 상태 변경을 수행하지 않습니다.
테스트 근거는 pro/tests/Unit/Chart/ 아래에 있습니다. 지원 매트릭스는 각 Verified 행을 해당 스위트에 앵커합니다.

발행 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

Chart (기능) — 작업 중심 개요, 설치, 코드 샘플.
Barcode — 심층 참조 — 자체 근거 기반 지원 매트릭스를 갖춘 형제 Pro 그리기 표면.