PHPackages sugarcraft/sugar-charts - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. sugarcraft/sugar-charts ActiveLibrary[CLI & Console](/categories/cli) sugarcraft/sugar-charts ======================= PHP port of NimbleMarkets/ntcharts — terminal charts (canvas, sparkline, bar, line, heatmap, scatter, time-series, OHLC, streamline, waveline) for SugarCraft. 11181PHP Since Jul 1Pushed 1mo agoCompare [ Source](https://github.com/sugarcraft/sugar-charts)[ Packagist](https://packagist.org/packages/sugarcraft/sugar-charts)[ RSS](/packages/sugarcraft-sugar-charts/feed)WikiDiscussions master Synced 3w ago READMEChangelogDependenciesVersions (1)Used By (1) [![sugar-charts](.assets/icon.png)](.assets/icon.png) SugarCharts =========== [](#sugarcharts) [![CI](https://github.com/detain/sugarcraft/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/detain/sugarcraft/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/e8b57d32290c3793f3c3910443d55b4eaaddaa06c19f5c48c3bc7d19d7f8a4ca/68747470733a2f2f636f6465636f762e696f2f67682f64657461696e2f737567617263726166742f6272616e63682f6d61737465722f67726170682f62616467652e7376673f666c61673d73756761722d636861727473)](https://app.codecov.io/gh/detain/sugarcraft?flags%5B0%5D=sugar-charts)[![Packagist Version](https://camo.githubusercontent.com/cfbc35de0028bab0924abc840cc34b0945e52aa10f31c680dd2cc8febc77ce9e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737567617263726166742f73756761722d6368617274733f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/sugarcraft/sugar-charts)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/fd3accad83cd317a9843432403191b4e555c55d57d63e10897f3f1dff5ed169e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135382e332d3838393262662e737667)](https://www.php.net/) [![demo](.vhs/heatmap.gif)](.vhs/heatmap.gif) ``` composer require sugarcraft/sugar-charts ``` PHP port of [NimbleMarkets/ntcharts](https://github.com/NimbleMarkets/ntcharts) — terminal charts for SugarCraft. v0 ships the canvas foundation plus three self-contained chart types. ``` use SugarCraft\Charts\Sparkline\Sparkline; use SugarCraft\Charts\BarChart\BarChart; use SugarCraft\Charts\LineChart\LineChart; echo Sparkline::new([1, 3, 2, 8, 5, 4, 7, 6], 8)->view() . PHP_EOL; // ▁▃▂█▅▄▇▆ echo BarChart::new([['cpu', 0.7], ['mem', 0.4], ['disk', 0.9]], 20, 5)->view() . PHP_EOL; // 0.9 ┤ ▏ █ // 0.7 ┤█ ▏ █ // 0.4 ┤█ █ █ // └──────── // cpu mem disk echo LineChart::new([1, 4, 2, 8, 6, 3, 7], 30, 6)->view() . PHP_EOL; ``` > Charts also expose short-form aliases on the most-used setters: `data` / `size` / `min` / `max` / `point` / `xRange` / `yRange` / `colors` / `palette` / `bars` / `barWidth` / `showLabels` / `showAxis`, etc. The upstream-mirroring `with*` long forms still work; pick the form that reads best at the call site. Components ---------- [](#components) ComponentRoleNotable knobs`Charts\Canvas\Canvas`Fixed-size cell grid; each cell holds a rune + optional Sprinkles `Style`.`setCell` / `setLines` / `setString` / `setRunes` / `fill` / `fillLine` / `shiftUp` / `shiftDown` / `shiftLeft` / `shiftRight` / `setCellStyle` / `getCellStyle``Charts\Canvas\BrailleGrid`Sub-cell scratch buffer (2 cols × 4 rows of dots per cell). Paint dots, then copy to a `Canvas`.`set` / `unset` / `toggle` / `isSet` / `rune` / `paint(Canvas, x0, y0, ?Style)` / `clear``Charts\Canvas\Graph`Drawing primitives over a `Canvas`.`drawHLine` / `drawVLine` / `drawXYAxis` / `drawXYAxisLabel` / `drawString` / `drawLine` / `drawLinePoints` / `fillRect` / `drawColumn` / `drawColumns` / `drawRows` / `drawCandlestick` / `drawBrailleRune` / `drawBraillePatterns` / `drawVerticalLineUp` / `drawVerticalLineDown` / `drawHorizontalLineLeft` / `drawHorizontalLineRight` / `getCirclePoints` / `getCirclePointsWithLimit` / `getFullCirclePoints` / `getFullCirclePointsWithLimit` / `getLinePointsWithLimit``Charts\Sparkline\Sparkline`Single-row series renderer using the 8 Unicode bar glyphs.`push` / `pushAll` / `clear` / `withMin` / `withMax` / `withStyle(?Style)` / `withNoAutoMaxValue(bool)` / `withWidth``Charts\BarChart\BarChart`Labeled vertical bars; auto-scales to a configurable min / max.`withBarWidth` / `withBarGap` / `withNoAutoBarWidth` / `push(Bar|array)` / `pushAll(iterable)` / `clear``Charts\LineChart\LineChart`Single-series ASCII plot drawn onto a Canvas with configurable axes.`withYRange` / `withXRange` / `withXYRange` / `autoAdjustRange` / `withXLabelFormatter` / `withYLabelFormatter` / `withAxes` / `withXLabels` / `withYLabels` / `withCanvas` / `withTheme` / `withFill``Charts\LineChart\TimeSeries`LineChart variant accepting `[\DateTimeImmutable, value]` tuples.`push` / `withPoints` / `withTimeFormat` / `withXLabelCount` / `withTimeRange(?start, ?end)` / `getTimeRange()``Charts\LineChart\Streamline`Single-row streaming line — auto-windowed to width.`push` / `pushAll` / `clear` / `withSize` / `withMin` / `withMax` / `withYRange``Charts\LineChart\Waveline`XY scatter / wave plot driven by `(x, y)` pairs.`push` / `pushAll` / `clear` / `withSize` / `withXRange` / `withYRange` / `withXYRange` / `withPoint``Charts\Heatmap\Heatmap`2D grid coloured by value with optional palette / legend.`withSize` / `withMin` / `withMax` / `withPalette` / `withLegend` / `withColors(cold, hot)` / `withColorProfile` / `withCellStyle(?Style)` / `withAutoValueRange(bool)` / `pushPoint(HeatPoint)` / `pushAll``Charts\OHLC\OHLCChart`Candlestick chart for `(high, open, close, low)` rows.`withSize` / `withBodyRunes(bull,bear)` / `withWickRune(rune)` / `withMin` / `withMax` / `withColors``Charts\Scatter\Scatter`XY scatter plot.`withPoints` / `withSize` / `withXRange` / `withYRange` / `withRune``Charts\Aggregation\BucketByTime`Groups timestamped values into time buckets with configurable aggregation.`sum` / `mean` / `min` / `max` / `first` / `last` factory methods + `add` / `addMany` / `compute``Charts\Aggregation\MovingAverage`Sliding-window aggregator — SMA and EMA.`simple` / `centered` / `ema` static factories + `add` / `addMany` / `computeSimple` / `values` / `clear``Charts\Aggregation\Resample`Upsample or downsample timestamped series to a target cadence.`last` / `mean` / `linear` / `nearest` factories + `resample` auto-detection`Charts\Picture\Picture`Inline image renderer (Sixel today; Kitty / iTerm2 protocols pending).`fromGrid` / `fromPng` / `withProtocol` / `withPaletteSize` / `view`### Aggregation [](#aggregation) Aggregation classes process raw time-series data before charting: ``` use SugarCraft\Charts\Aggregation\{BucketByTime, MovingAverage, Resample}; // BucketByTime: group into 1-hour buckets, sum values per bucket. $buckets = BucketByTime::sum(3600, [ ['ts' => strtotime('2024-01-01 00:10'), 'value' => 10], ['ts' => strtotime('2024-01-01 00:45'), 'value' => 15], ['ts' => strtotime('2024-01-01 01:05'), 'value' => 20], ]); // → [{ts: 0, value: 25}, {ts: 3600, value: 20}] // MovingAverage: 3-point SMA and EMA. $sma = MovingAverage::simple(3, [1, 4, 2, 8, 6]); // → [0.0, 0.0, 2.33…, 4.67…, 5.33…] $ema = MovingAverage::ema(3, [1, 4, 2, 8, 6]); // → [1.0, 2.5, 2.25, 5.13, 5.56] // Resample: downsample to 30-second cadence (last value), or upsample (linear interp). $down = Resample::last(30, $timestampedData); $up = Resample::linear(30, $timestampedData); ``` ### Braille canvas rendering [](#braille-canvas-rendering) Charts support high-resolution dot-matrix (braille) rendering via `SugarCraft\Dash\Plot\Braille\BrailleCanvas`. Pass a `BrailleCanvas`instance via `withCanvas()` to switch from character-cell to 2×4 sub-cell resolution: ``` use SugarCraft\Charts\LineChart\LineChart; use SugarCraft\Dash\Plot\Braille\BrailleCanvas; $canvas = new BrailleCanvas(80, 24); $chart = LineChart::new([1, 4, 2, 8, 6], 80, 24) ->withCanvas($canvas); echo $chart->view(); ``` ### Named color themes [](#named-color-themes) Charts inherit [candy-sprinkles](https://github.com/detain/sugarcraft/tree/master/candy-sprinkles)`Theme` palette support via `withTheme()`. All `Theme::` factory methods are supported: ``` use SugarCraft\Charts\LineChart\LineChart; use SugarCraft\Sprinkles\Theme; $chart = LineChart::new([3, 1, 4, 1, 5, 9, 2, 6], 40, 8) ->withTheme(Theme::dracula()) ->withLegend(); echo $chart->view(); ``` Available themes: `Theme::ansi()` / `Theme::dark()` / `Theme::light()` / `Theme::dracula()` / `Theme::tokyoNight()` / `Theme::oneDark()` / `Theme::githubDark()` / `Theme::solarizedDark()` / `Theme::solarizedLight()`. Shared foundations ------------------ [](#shared-foundations) All chart renderers build their output via [candy-buffer](https://github.com/detain/sugarcraft/tree/master/candy-buffer). Do not re-implement string padding or cell-grid assembly — use the `Buffer` class directly. Graph primitives at a glance ---------------------------- [](#graph-primitives-at-a-glance) `Graph` is a static-method utility — every draw call takes a `Canvas`plus coordinates in canvas (cell) space (top-left origin). Pair with `BrailleGrid` for sub-cell precision: ``` use SugarCraft\Charts\Canvas\{Canvas, BrailleGrid, Graph}; $canvas = new Canvas(40, 8); Graph::drawXYAxis($canvas, 1, 6, 38); Graph::drawString($canvas, 4, 0, 'Demo'); // Sub-cell line via BrailleGrid. $grid = new BrailleGrid(38, 6); foreach (Graph::getLinePointsWithLimit(0, 0, 75, 23, limit: 200) as [$x, $y]) { $grid->set($x, $y); } $grid->paint($canvas, 1, 0); echo $canvas->view(); ``` ### Palette / colour profile [](#palette--colour-profile) `Heatmap::withPalette([Color, …])` interpolates between an arbitrary number of stops (≥ 2). `withColors(Color $cold, Color $hot)` is the two-stop shortcut. `withColorProfile(ColorProfile)` overrides the auto-detected output profile when piping to non-tty / Sixel-capable sinks. `Heatmap::withCellStyle(Style)` overlays additional attributes (bold / background / etc.) on top of every cell's foreground gradient. Demos ----- [](#demos) ### Bar chart [](#bar-chart) [![bar](.vhs/bar.gif)](.vhs/bar.gif) ### Heatmap [](#heatmap) [![heatmap](.vhs/heatmap.gif)](.vhs/heatmap.gif) ### Line chart [](#line-chart) [![line](.vhs/line.gif)](.vhs/line.gif) ### OHLC (candlestick) [](#ohlc-candlestick) [![ohlc](.vhs/ohlc.gif)](.vhs/ohlc.gif) ### Picture (Sixel) [](#picture-sixel) [![picture](.vhs/picture.gif)](.vhs/picture.gif) ### Scatter [](#scatter) [![scatter](.vhs/scatter.gif)](.vhs/scatter.gif) ### Sparkline [](#sparkline) [![sparkline](.vhs/sparkline.gif)](.vhs/sparkline.gif) ### Time series [](#time-series) [![timeseries](.vhs/timeseries.gif)](.vhs/timeseries.gif) Status ------ [](#status) ComponentStateCanvas, BrailleGrid, Graph primitives🟢 v1Sparkline🟢 v1BarChart🟢 v1 (multi-bar grouped datasets pending)LineChart🟢 v1 (zoom/pan + dataset styles pending)TimeSeries🟢 v1 (multi-dataset + update-handler variants pending)Streamline, Waveline🟢 v1Heatmap🟢 v1 (default-color-scale getter/setter pending)OHLC🟡 candlestick rendering only — volume sub-pane + multi-series pendingScatter🟡 single-dataset only — per-point rune/style sets pendingPicture🟡 Sixel renderer only — Kitty graphics protocol + iTerm2 inline + half-block fallback pendingSnapshot tests -------------- [](#snapshot-tests) Render output is covered by golden-file snapshot tests. Fixture files live in `tests/fixtures/` with a `.golden` extension and are compared against actual ANSI byte output via `SugarCraft\Testing\Snapshot\Assertions::assertGoldenAnsi()`. To re-record fixtures after intentional output changes: ``` UPDATE_GOLDENS=1 vendor/bin/phpunit ``` Test ---- [](#test) ``` cd sugar-charts && composer install && vendor/bin/phpunit ``` Related ------- [](#related) - [SugarCraft monorepo](https://github.com/detain/sugarcraft) - Upstream: [NimbleMarkets/ntcharts](https://github.com/NimbleMarkets/ntcharts) ### Health Score 23 — LowBetter than 25% of packages Maintenance59 Moderate activity, may be stable Popularity13 Limited adoption so far Community10 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 99.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/b1036e0717211b8030b83cbe729e8ba6ba442fdbd5285fb97a39d7dcfe339342?d=identicon)[detain](/maintainers/detain) --- Top Contributors [![detain](https://avatars.githubusercontent.com/u/1364504?v=4)](https://github.com/detain "detain (113 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags bar-chartcandlestickcandycorecanvaschartsdata-visualizationgraphsheatmapline-chartntchartsntcharts-portohlcplotscatter-plotsparklinestreamingterminalterminal-chartstime-seriestui ### Embed Badge ![Health badge](/badges/sugarcraft-sugar-charts/health.svg) ``` [![Health](https://phpackages.com/badges/sugarcraft-sugar-charts/health.svg)](https://phpackages.com/packages/sugarcraft-sugar-charts) ``` ### Alternatives [illuminate/console The Illuminate Console package. 13046.0M6.8k](/packages/illuminate-console)[styleci/cli The CLI tool for StyleCI 71470.5k9](/packages/styleci-cli)[winbox/args Windows command-line formatter 20720.9k21](/packages/winbox-args)[mallardduck/laravel-traits A collection of useful Laravel snippets in the form of easy to use traits. 136.2k2](/packages/mallardduck-laravel-traits) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)