Pro 에디션

Chart

한눈에 보기

NextPDF Pro는 막대형, 꺾은선형, 원형 차트를 벡터 콘텐츠 연산자로 PDF 페이지에 직접 렌더링합니다. 래스터화 단계도 없고 헤드리스 브라우저 의존성도 없으므로 출력은 결정적이며 재현 가능합니다.

설치

composer require nextpdf/pro:^3

개념 개요

Chart 모듈은 세 가지 네이티브 차트 렌더러를 제공합니다. 각각은 자체 완결형 그리기 프리미티브입니다. 즉, 제공한 고정 사각형 박스 안에 렌더링하며, 리플로우도 없고, 컨테이너 인식도 없고, 레이아웃 협상도 없습니다. 박스를 배치하면 렌더러가 그 안을 채웁니다.

막대형 차트 — 막대 색상, 축 색상, 막대 간격, 레이블 글꼴 크기를 설정할 수 있는 세로 막대형 차트입니다.
꺾은선형 차트 — 시리즈별 색상, 선택적 데이터 포인트 마커, 선택적 그리드, 설정 가능한 선 너비를 갖춘 단일 또는 다중 시리즈 꺾은선형 차트입니다.
원형 차트 — 자동 팔레트 할당, 선택적 백분율 레이블, 선택적 범례를 갖춘 원형 차트입니다.

모든 렌더러는 동일한 형태를 따릅니다. fromData(...) 팩토리, 플루언트 with*() 구성, 그리고 PDF 콘텐츠 스트림 연산자를 반환하는 render(ChartBox $box): string 호출입니다. 출력은 결정적입니다. 동일한 입력과 구성은 동일한 연산자를 생성하므로 차트가 포함된 문서는 재현 가능하며 서명하거나 보관하기에 안전합니다.

렌더러는 이미지가 아니라 벡터 연산자를 방출하므로, 차트는 어떤 확대 배율에서도 선명하게 유지되며 문서에 래스터 페이로드를 추가하지 않습니다.

이렇게 작동하는 이유

핵심을 지탱하는 결정은 이미지를 래스터화하거나 헤드리스 브라우저를 구동하는 대신 네이티브 PDF 벡터 연산자를 방출하는 것입니다. 그 선택 덕분에 출력이 결정적이 됩니다. 동일한 데이터와 구성은 언제나 바이트 단위로 동일한 연산자를 생성합니다. 결정적 연산자는 차트가 포함된 문서를 재현 가능하게 유지하므로 서명하거나 보관하기에 안전합니다. 외부 렌더러를 피하는 것은 프로세스 의존성도 제거하므로, 처리량은 브라우저 시작 비용이 아니라 데이터 포인트 수에 따라 확장됩니다. 각 렌더러는 자신의 연산자를 q/Q 그래픽 상태 쌍으로 감싸고 결코 리플로우하지 않으므로, 예측 가능하고 저렴하게 조합됩니다.

설계 배경: High-volume document generation.

API 표면

composer require nextpdf/pro:^3

Chart 공개 표면은 NextPDF\Pro\Chart의 다섯 개 클래스입니다.

BarChart — fromData(), withBarColor(), withAxisColor(), withBarGap(), withFontSize(), render().
LineChart — create(), fromData(), addSeries(), withAxisColor(), withLineWidth(), withFontSize(), withDots(), withGrid(), render().
PieChart — fromData(), withColors(), withStrokeColor(), withFontSize(), withPercentages(), withLegend(), render().
ChartBox — 배치 사각형입니다. fromUserSpace()는 좌측 상단 원점의 사용자 공간 사각형을 PDF의 좌측 하단 원점으로 변환하며, inset()은 패딩을 적용합니다.
ChartColor — rgb(), hex(), palette(), 그리고 스트로크/채우기 연산자 방출기입니다.

코드 샘플 — 빠른 시작

use NextPDF\Pro\Chart\BarChart;
use NextPDF\Pro\Chart\ChartBox;

$box = ChartBox::fromUserSpace(72, 72, 400, 240, pageHeight: 842);
$stream = BarChart::fromData(['Q1', 'Q2', 'Q3', 'Q4'], [100, 200, 150, 300])
    ->render($box);
// $stream is appended to the target page content.

코드 샘플 — 프로덕션

use NextPDF\Pro\Chart\ChartBox;
use NextPDF\Pro\Chart\ChartColor;
use NextPDF\Pro\Chart\LineChart;

$box = ChartBox::fromUserSpace(72, 72, 460, 260, pageHeight: 842)
    ->inset(8, 8, 8, 8);

$stream = LineChart::create(['Jan', 'Feb', 'Mar', 'Apr'])
    ->addSeries('Revenue', [120, 180, 150, 220], ChartColor::hex('#336699'))
    ->addSeries('Cost', [80, 90, 110, 130], ChartColor::palette(1))
    ->withGrid(true)
    ->withDots(true, 2.5)
    ->withLineWidth(1.2)
    ->render($box);

엣지 케이스 및 함정

빈 데이터는 예외를 던지지 않고 빈 문자열을 반환하므로, 데이터셋이 없으면 페이지를 깨뜨리는 대신 아무것도 렌더링하지 않습니다.
합계가 0이거나 음수인 원형 차트는 빈 문자열을 반환합니다.
단일 포인트만 있는 꺾은선형 시리즈는 선분을 그리지 않습니다(단일 포인트에는 경로가 없습니다).
크기가 0인 ChartBox는 의미 있는 것을 렌더링하지 않습니다. 렌더링하기 전에 박스 크기를 지정하십시오.
렌더러는 박스에 맞게 클리핑하지 않습니다. 의도한 페이지 영역에 맞는 박스를 제공하십시오.

성능

렌더링은 단일 패스이며 데이터 포인트 수에 선형적입니다. 래스터화도, 이미지 버퍼도, 외부 프로세스도 없습니다. 방출되는 연산자 문자열의 크기가 메모리 비용을 한정합니다. 다중 시리즈 꺾은선형 차트는 시리즈 전반의 총 포인트 수에 선형적으로 확장됩니다.

보안 참고

차트 렌더러는 숫자 및 레이블 데이터만 소비합니다. 입력을 평가하거나 실행하지 않습니다. 렌더러는 레이블을 PDF 텍스트 연산자로 방출하며 결코 해석하지 않습니다. 모듈은 차트 데이터를 로그에 기록하지 않습니다. 애플리케이션은 차트로 만들기 전에 민감한 레이블을 살균해야 합니다.

적합성

차트는 외부 표준의 적용을 받지 않습니다. 출력은 ISO 32000-2 콘텐츠 스트림 시맨틱에 따라 페이지에 렌더링된 PDF 콘텐츠 스트림입니다. 이 모듈에는 심볼로지나 암호 적합성 표면이 없습니다.

게시 경계

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