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:

Option	Type	Default	Description
showValues	bool	false	Display values above bars
gridLines	bool	true	Show horizontal grid lines
barWidth	int	1	Width of each bar in characters

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:

Option	Type	Default	Description
lineColor	string	'cyan'	Color for the line
pointColor	string	null	Color for data points (uses lineColor if null)

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:

Option	Type	Default	Description
width	int	60	Total width in characters
height	int	15	Chart height in lines
title	string	''	Title displayed above the chart
colors	bool	true	Enable/disable ANSI colors

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.