README

Bite-sized charting library that focuses on text (ASCII) rendering, with an HTML renderer for web usage. Ideal for CLIs, logs, and minimalist dashboards.

Note: The library is usable today; the examples below reflect the current API and behavior.

• Documentation: see the docs/ directory or start at docs/README.md
• License: MIT

Features

• Data input: PHP arrays and Illuminate Collections
• Chart types: ProgressBar, BarChart, LineChart
• Outputs: ASCII (terminal), HTML (browser)
• Elements: Axes, Labels, Annotations
• Fluent builder-style configuration

Installation

composer require molbal/smolchart

Requires PHP ^8.2.

Quick Examples

Below are copy-pastable examples that reflect the current API.

Progress Bar (ASCII)

<?php

use Molbal\Smolchart\Charts\ProgressBar;
use Molbal\Smolchart\Rendering\ASCII\AsciiRenderer;

$progress = (new ProgressBar())
    ->setData(['completed' => 45, 'total' => 100])
    ->setLabels(['title' => 'Build'])
    ->setAnnotations(['note' => 'Halfway there']);

echo $progress->render(new AsciiRenderer());

Bar Chart (HTML)

<?php

use Molbal\Smolchart\Charts\BarChart;
use Molbal\Smolchart\Rendering\HTML\HtmlRenderer;

$bar = (new BarChart())
    ->setData([
        'Apples' => 10,
        'Bananas' => 6,
        'Cherries' => 14,
    ])
    ->setLabels(['x' => 'Fruit', 'y' => 'Quantity'])
    ->setAnnotations(['peak' => 'Cherries lead']);

$markup = $bar->render(new HtmlRenderer());

Line Chart (ASCII)

<?php

use Molbal\Smolchart\Charts\LineChart;
use Molbal\Smolchart\Rendering\ASCII\AsciiRenderer;

$line = (new LineChart())
    ->setData([
        ['t' => '2025-09-01', 'value' => 10],
        ['t' => '2025-09-02', 'value' => 12],
        ['t' => '2025-09-03', 'value' => 7],
    ])
    ->setLabels(['x' => 'Date', 'y' => 'Value'])
    ->setAnnotations(['dip' => 'Anomaly on 09-03']);

echo $line->render(new AsciiRenderer());

Builder Pattern

Most configuration methods return $this to enable chaining ending with ->render($renderer).

<?php

use Molbal\Smolchart\Charts\BarChart;
use Molbal\Smolchart\Rendering\ASCII\AsciiRenderer;
use Molbal\Smolchart\Rendering\HTML\HtmlRenderer;

$chart = (new BarChart())
    ->setData(['A' => 1, 'B' => 2])
    ->setLabels(['x' => 'Key', 'y' => 'Value'])
    ->setAnnotations(['note' => 'Demo']);

$ascii = $chart->render(new AsciiRenderer());
$html  = $chart->render(new HtmlRenderer());

See the full Builder guide at docs/builder.md.

ASCII Renderer options

You can customize the ASCII renderer via a fluent builder:

<?php
use Molbal\Smolchart\Rendering\ASCII\AsciiRenderer;

$renderer = (new AsciiRenderer())
    ->withCharacter('▓')  // custom fill character (default already ▓)
    ->withBorder(true)    // draw a border box around the content
    ->withTitle('Weekly Sales')
    ->withWidth(30)       // Bar & Progress: total width incl. borders; Line: drawing width. (default 20 for unspecified)
    ->withLabelWidth(12); // reserve 12 chars for labels; defaults to longest label

• If a border is enabled, the title is centered within the top border line.
• Without a border, the title (from withTitle or chart labels['title']) is printed as the first line.
• Bars/lines use the selected character for their filled portions.
• For bar charts, category labels are padded or truncated to a uniform width. By default this width is the longest label; you can override it with withLabelWidth().

Documentation

• Start here: docs/README.md
• Getting started: docs/getting-started.md
• Data & processing: docs/data.md
• Charts:
  • Progress Bar: docs/charts/progress-bar.md
  • Bar Chart: docs/charts/bar-chart.md
  • Line Chart: docs/charts/line-chart.md
• Renderers:
  • ASCII: docs/renderers/ascii.md
  • HTML: docs/renderers/html.md

Contributing

Contributions are welcome. Please open issues or pull requests on GitHub.

Security

Please review the repository's security policy for reporting vulnerabilities.

License

The MIT License (MIT). Please see LICENSE.md for more information.