Pro редакция

Chart — глубокий справочник

С первого взгляда

Эта страница — справочник контрактного уровня по модулю NextPDF Pro Chart. Поверхность — пять публичных классов в NextPDF\Pro\Chart: рендереры BarChart, LineChart и PieChart, прямоугольник размещения ChartBox и объект-значение ChartColor. Каждый рендерер — это примитив рисования. Статическая фабрика создаёт его, текучие вызовы with*() настраивают его, а render(ChartBox $box): string возвращает операторы потока содержимого PDF для переданного прямоугольника. Вывод чисто векторный и детерминированный: одинаковый вход и конфигурация дают одинаковые байты. Вырожденные входы возвращают пустую строку, а не выбрасывают исключение, поэтому диаграмма никогда не ломает окружающую страницу. Ориентированное на задачи представление находится на странице возможности.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без такого права не загружает классы возможности. Сравните редакции и получите лицензию.

Рендереры диаграмм лицензируются по возможностям в семействе chart.*. Когда возможность не лицензирована, рендереры диаграмм недоступны.

Публичная поверхность API

composer require nextpdf/pro:^3

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или падает с	Примечания
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Значения приводятся к float	`self`	Не выбрасывает	Единственный путь создания; конструктор приватный
`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`	Диаграмма без рядов	`self`	Не выбрасывает	Конструктор приватный
`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`	Не выбрасывает	Маркеры рисуются как аппроксимированные Безье окружности
`LineChart::withGrid()`	`bool $show`	Горизонтальная квартильная сетка; включена по умолчанию	`self`	Не выбрасывает	—
`LineChart::render()`	`ChartBox $box`	Сетка, оси, по одному пути на ряд, подписи	операторы `string`	Не выбрасывает; отсутствие рядов возвращает `''`	Ряд короче двух точек не рисует путь
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Пропорции вычисляются из суммы значений	`self`	Не выбрасывает	Конструктор приватный
`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`	Не выбрасывает; пустые данные или сумма, не превышающая ноль, возвращают `''`	Дуги разбиваются на сегменты Безье не более 90 градусов
`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`	Принимает hex с префиксом `#` или голый шестизначный	`self`	Не выбрасывает	Отсутствующие завершающие цифры декодируются как ноль
`ChartColor::palette()`	`int $index`	Встроенная палитра из 12 цветов	`self`	`TypeError` при отрицательном индексе	Неотрицательные индексы заворачиваются по модулю 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() читает конфигурацию, не мутируя её, поэтому один настроенный рендерер может рендерить в несколько рамок. Каждый рендеринг оборачивает свой вывод в пару сохранения/восстановления состояния графики, поэтому состояние диаграммы никогда не утекает на страницу. Координаты выводятся с двумя знаками после запятой, а компоненты цвета — с тремя, что делает вывод байт-стабильным. Текст рендерится через имя ресурса шрифта /ChartFont заданного размера; вызывающая сторона регистрирует шрифт под этим именем в словаре ресурсов целевой страницы. Строки подписей экранируют обратную косую черту и скобки перед попаданием в строковые операнды. Рендереры не выполняют ни перекомпоновки, ни обрезки, ни согласования контейнера: размещением владеет вызывающая сторона.

Масштабирование и компоновка

Столбчатые и линейные диаграммы резервируют фиксированный отступ области построения внутри рамки: 40 пунктов слева, 20 снизу, 10 справа, 10 сверху. Оставшаяся область построения масштабирует значения линейно относительно максимума ряда. Максимум, равный нулю или ниже, масштабируется относительно 1.0, поэтому данные из одних нулей рендерят оси с плоским содержимым, а не делят на ноль. Обе рисуют оси X и Y толщиной 0.5 пункта и пять делений значений в квартильных позициях. Столбчатые диаграммы форматируют значения делений с суффиксами K и M выше тысячи и миллиона; линейные диаграммы печатают обычные числа.

Столбчатая диаграмма

Каждое значение занимает равный слот по ширине области построения. Столбец заполняет слот за вычетом заданной доли зазора и центрируется в слоте. Подписи категорий рисуются на 12 пунктов ниже области построения.

Линейная диаграмма

Сетка, когда включена, рисует четыре горизонтальные квартильные линии светло-серым (0.85 0.85 0.85 RG) под осями и рядами. Каждый ряд рисует одну ломаную через свои точки, охватывая всю ширину области построения. Необязательные маркеры рисуются как четырёхсегментные окружности Безье в каждой точке данных. Цвета рядов по умолчанию — последовательные элементы палитры в порядке вставки.

Круговая диаграмма

Секторы располагаются в порядке данных, начиная с положительной оси X и разворачиваясь против часовой стрелки. Каждый путь сектора замыкается и закрашивается совмещённой заливкой и обводкой (h B); дуги разбиваются на сегменты Безье не более 90 градусов. Подписи процентов округляются до целых процентов и рендерятся только на секторах с разворотом более 15 градусов. Легенда, когда включена, резервирует 80 пунктов ширины рамки справа и рендерит образец в 8 пунктов на запись при межстрочном интервале 12 пунктов. Радиус — половина меньшего из оставшейся ширины и высоты рамки, минус отступ в 10 пунктов.

Объекты-значения размещения и цвета

ChartBox — неизменяемый прямоугольник в пользовательских единицах PDF (пунктах) с началом координат в нижнем левом углу. ChartBox::fromUserSpace() преобразует прямоугольник с началом в верхнем левом углу, переворачивая его относительно переданной высоты страницы. inset() возвращает новую, меньшую рамку; right() и top() — методы-аксессоры. ChartColor самодостаточен и не зависит от классов цвета Core. Его палитра из 12 элементов назначает цвета рядам и секторам, когда вызывающая сторона не указывает их.

Матрица поддержки (подкреплённая доказательствами)

Тип диаграммы или возможность получает статус Verified только тогда, когда фикстура pro/tests/** прорабатывает её. Никакой внешний стандарт не регулирует диаграммы, поэтому доказательство — это поведенческий охват на модульном уровне.

Тип диаграммы / возможность	Статус	Доказательство (путь к тесту)	Уверенность	Примечания
Столбчатая диаграмма — рендеринг, оси, прямоугольники столбцов, ограничение зазора, пустые/все-нулевые данные, форматирование значений K/M	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	Обёртка состояния графики, линии осей, пропорции высот столбцов, число делений и границы форматирования утверждены.
Линейная диаграмма — один и несколько рядов, линейный путь, оси, точки, сетка, одна точка	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	Несколько рядов, отсутствие линии для одной точки, пустой ряд, пути сетки и точек охвачены.
Круговая диаграмма — секторы, сегментация Безье, проценты, легенда, нулевая/отрицательная сумма	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	Пути секторов, число сегментов на разворот, порог подписей в 15 градусов, геометрия легенды и поведение с пустой строкой охвачены.
`ChartBox` — преобразование координат (пользовательское пространство → PDF), верх/низ страницы, нулевые размеры, отступ	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	Преобразование из начала в верхнем левом углу в начало в нижнем левом углу у верха, низа страницы и на краях с нулевым размером.
`ChartColor` — масштабирование RGB, разбор hex, палитра, операторы обводки/заливки	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	high	Масштабирование 0–255 → 0–1, hex с префиксом `#` и голый, смешанный регистр, заворачивание палитры после 12 элементов.
Усиление от регрессий между рендерерами	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	Общий регрессионный набор по трём рендерерам плюс арифметика форматирования значений.
Типы диаграмм помимо столбчатой/линейной/круговой (область, точечная, со стопкой, кольцевая и т. д.)	Not supported	—	high	Рендерер не поставляется. Поверхность модуля — ровно столбчатая, линейная, круговая. Сказано честно: это не «каждый тип диаграммы».

Честный подсчёт: Verified 6 строк, Claimed 0, Not supported 1 (любой тип диаграммы, кроме столбчатой, линейной, круговой).

Граничные случаи и режимы отказа

Ни один рендерер не выбрасывает исключение на данных. Вырожденный вход деградирует до пустой строки: пустые данные столбчатой или линейной диаграммы, пустой список рядов и сумма круговой диаграммы, не превышающая ноль, — все возвращают ''.
Ряд линейной диаграммы менее чем из двух точек не рисует ни пути, ни маркеров; оси и подписи всё же рендерятся.
Отрицательные значения столбцов не отклоняются; прямоугольник столбца выходит ниже оси X.
Число подписей и значений не сверяется взаимно. Вызывающая сторона поставляет списки совпадающей длины.
ChartBox с нулевыми или отрицательными размерами принимается и даёт вырожденный вывод; вызывающие стороны должны задать размер рамки.
Рендереры не обрезают. Диаграмма избыточного размера, её подписи категорий под областью построения или длинная легенда могут выходить за пределы предполагаемой области страницы.
Страница без шрифта под именем ресурса шрифта диаграммы оставляет текстовые операторы, ссылающиеся на неопределённый ресурс; поведение просмотрщика при этом не определено.
ChartColor::hex() не выполняет проверки; вход короче шести цифр декодирует отсутствующие компоненты как ноль. ChartColor::palette() падает с TypeError при отрицательном индексе, потому что отрицательный модуль в PHP не разрешает ни одного ключа палитры.
Модуль не выполняет криптографии; режим FIPS не имеет специфичного для диаграмм поведения.

Соответствие

Модуль Chart выдаёт операторы потока содержимого PDF. Никакой внешний стандарт диаграмм, символики или криптографии не регулирует его вывод, поэтому единственная поверхность соответствия — выдаваемый поток операторов.

Утверждение	Стандарт	Пункт
Выдаваемая графика следует модели операторов потока содержимого; вывод вложен в сохранённое и восстановленное состояние графики.	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 и безопасными для подписи или архивации.
Регистрируйте шрифт под именем ресурса шрифта диаграммы один раз на каждую страницу, где размещаются диаграммы.
Переиспользуйте настроенный рендерер между рамками свободно; render() не выполняет мутации состояния.
Доказательства из тестов находятся в pro/tests/Unit/Chart/; матрица поддержки привязывает каждую строку Verified к её набору.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области рассмотрения.

См. также

Chart (возможность) — ориентированный на задачи обзор, установка и примеры кода.
Barcode — глубокий справочник — родственная поверхность рисования Pro со своей матрицей поддержки, подкреплённой доказательствами.