README

PHP CLI Charts

A PHP library for rendering beautiful charts in the command line using Unicode characters, Braille patterns, and ANSI colors.

Features

• 6 chart types: Bar, Vertical Bar, Line, Pie, Stacked Bar, and Percentage Bar
• High-resolution rendering using Braille characters for smooth curves and lines
• ANSI color support with automatic color cycling
• Customizable dimensions, titles, and display options
• Simple factory pattern API
• Requires PHP 8.4+

Installation

composer require daikazu/cli-charts

Quick Start

<?php

use Daikazu\CliCharts\ChartFactory;

$data = [
    'Jan' => 120,
    'Feb' => 180,
    'Mar' => 150,
    'Apr' => 220,
];

$chart = ChartFactory::create('bar', $data, [
    'title' => 'Monthly Sales',
    'width' => 60,
]);

echo $chart->render();

Chart Types

Bar Chart

Horizontal bar chart with colored bars proportional to values.

$chart = ChartFactory::create('bar', $data, $options);

Example:

$data = [
    'Food'          => 1200,
    'Rent'          => 1800,
    'Transport'     => 400,
    'Entertainment' => 350,
    'Utilities'     => 250,
];

$chart = ChartFactory::create('bar', $data, [
    'title' => 'Monthly Expenses ($)',
    'width' => 60,
]);

echo $chart->render();

Output:

                    Monthly Expenses ($)

Food          │ █████████████████████████████ 1200
Rent          │ ████████████████████████████████████████████ 1800
Transport     │ ██████████ 400
Entertainment │ █████████ 350
Utilities     │ ██████ 250

Vertical Bar Chart

Vertical bar chart with optional grid lines, value display, and legend.

$chart = ChartFactory::create('vbar', $data, $options);

Options:

Example:

$data = [
    'Jan' => 120,
    'Feb' => 180,
    'Mar' => 150,
    'Apr' => 220,
    'May' => 190,
    'Jun' => 250,
];

$chart = ChartFactory::create('vbar', $data, [
    'title' => 'Monthly Sales',
    'width' => 60,
    'height' => 15,
    'showValues' => true,
    'gridLines' => true,
]);

echo $chart->render();

Output:

                       Monthly Sales

  250 │·               █
      │          █     █
      │·         █     █
      │    █     █  █  █
      │·   █     █  █  █
      │    █  █  █  █  █
  125 │·█  █  █  █  █  █
      │ █  █  █  █  █  █
      │·█  █  █  █  █  █
      │ █  █  █  █  █  █
      │·█  █  █  █  █  █
      │ █  █  █  █  █  █
    0 │·█  █  █  █  █  █
      └──────────────────
        Ja Fe Ma Ap Ma Ju

      Jan: 120; Feb: 180; Mar: 150
      Apr: 220; May: 190; Jun: 250

Line Chart

Line chart using Braille characters for smooth, high-resolution lines.

$chart = ChartFactory::create('line', $data, $options);

Options:

Example:

$data = [
    'Jan' => 120,
    'Feb' => 180,
    'Mar' => 150,
    'Apr' => 220,
    'May' => 190,
    'Jun' => 250,
];

$chart = ChartFactory::create('line', $data, [
    'title' => 'Sales Trend',
    'width' => 60,
    'height' => 15,
    'lineColor' => 'cyan',
    'pointColor' => 'red',
]);

echo $chart->render();

Output:

                        Sales Trend

  250 │                                                  ⡠⠛
      │                                                ⡠⠊
      │                              ⢀⣄              ⡠⠊
      │                             ⢠⠊⠉⠑⠢⢄⡀        ⢀⠔⠁
  207 │                           ⢀⠔⠁     ⠈⠑⠤⣀   ⢀⠔⠁
      │                          ⡠⠃           ⠉⠲⡶⠁
      │         ⢀⠾⠦⣀           ⢠⠊
  163 │       ⢀⠔⠁   ⠉⠒⠤⡀     ⢀⠔⠁
      │     ⢀⠔⠁        ⠈⠑⠢⢄⣀⡠⠃
      │    ⡠⠃              ⠙⠁
      │  ⡠⠊
  120 │⣤⠊
      └────────────────────────────────────────────────────
      Jan      Feb       Mar        Apr       May       Ju

Pie Chart

Circular pie chart rendered using Braille characters with a color legend.

$chart = ChartFactory::create('pie', $data, $options);

Example:

$data = [
    'Chrome'  => 65,
    'Safari'  => 19,
    'Firefox' => 8,
    'Edge'    => 5,
    'Other'   => 3,
];

$chart = ChartFactory::create('pie', $data, [
    'title' => 'Browser Market Share',
    'width' => 60,
]);

echo $chart->render();

Output:

                    Browser Market Share

          ⢀⣀⣠⣤⣤⣤⣤⣤⣀⣀         
       ⣀⣴⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣄⡀     
     ⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⡀   
   ⢀⣼⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣄  
  ⢀⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣆ 
  ⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡀
  ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇
  ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇
  ⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃
  ⠘⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟ 
   ⠘⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟  
    ⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠋   
      ⠈⠛⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠋     
         ⠈⠙⠛⠻⠿⠿⠿⠿⠿⠛⠛⠉        

  ● Chrome   65.0% (65)
  ● Safari   19.0% (19)
  ● Firefox   8.0% (8)
  ● Edge      5.0% (5)
  ● Other     3.0% (3)

Stacked Bar Chart

Single horizontal bar divided into colored segments with percentages.

$chart = ChartFactory::create('stacked', $data, $options);
// Alias: ChartFactory::create('sbar', $data, $options);

Example:

$data = [
    'Chrome'  => 65,
    'Safari'  => 19,
    'Firefox' => 8,
    'Edge'    => 5,
    'Other'   => 3,
];

$chart = ChartFactory::create('stacked', $data, [
    'title' => 'Browser Market Share',
    'width' => 60,
]);

echo $chart->render();

Output:

                    Browser Market Share

[█████████████████████████████████████▊███████████████▋██▉█▊]
 Chrome 65%   Safari 19%   Firefox 8%   Edge 5%   Other 3%

Percentage Bar Chart

Vertical list where each item has a horizontal percentage bar.

$chart = ChartFactory::create('percent', $data, $options);
// Alias: ChartFactory::create('pbar', $data, $options);

Example:

$data = [
    'Chrome'  => 65,
    'Safari'  => 19,
    'Firefox' => 8,
    'Edge'    => 5,
    'Other'   => 3,
];

$chart = ChartFactory::create('percent', $data, [
    'title' => 'Browser Market Share',
    'width' => 60,
]);

echo $chart->render();

Output:

                    Browser Market Share

Chrome  █████████████████████████████▎                65.0%
Safari  ████████▌                                     19.0%
Firefox ███▋                                           8.0%
Edge    ██▎                                            5.0%
Other   █▍                                             3.0%

Common Options

All chart types support these base options:

Available Colors

Charts automatically cycle through these ANSI colors:

• red
• green
• yellow
• blue
• magenta
• cyan
• white

Colors are assigned based on a hash of the label, ensuring consistent colors for the same labels across renders.

API Reference

ChartFactory

ChartFactory::create(string $type, array $data, array $options = []): Chart

Parameters:

• $type - Chart type: 'bar', 'vbar', 'line', 'pie', 'stacked'/'sbar', 'percent'/'pbar'
• $data - Associative array of label => value pairs
• $options - Configuration options array

Returns: Chart instance

Throws: InvalidArgumentException for unsupported chart types

Chart Classes

All chart classes extend the abstract Chart class and implement:

public function render(): string

Returns the complete chart as a string ready to output.

Direct instantiation:

use Daikazu\CliCharts\BarChart;
use Daikazu\CliCharts\VerticalBarChart;
use Daikazu\CliCharts\LineChart;
use Daikazu\CliCharts\PieChart;
use Daikazu\CliCharts\StackedBarChart;
use Daikazu\CliCharts\PercentageBarChart;

$chart = new BarChart($data, $options);
echo $chart->render();

Testing

composer test

Run the visual demo:

php demo.php

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mike Wall
• All Contributors

License

The MIT License (MIT). Please see License File for more information.