Documentation

Last updated: Sep 4th, 2016

How does this work?

This is a PHP library that enables you to produce chart-like images. You simple create a new object of the chart class, set the dimensions and the chart dataset (and all the other available configurations, if needed) and a chart image is created. You can then display the image on the page or store it on a file.

Behind the curtain, the library calculates the dimensions of all the components (graph, axis, title, labels, columns / bars, lines / pie slices, etc) and assembles the final image.

Installation

To use this package on your project, you need to use Composer.

Once you have Composer, just add the package as a dependency, as follows:

"require": {
    "luismarto/libchart": "2.*"
}

Create chart

To create a chart you need to use one of the following classes, based on the chart you want to produce. The class names are faily expressive.

<?php
use Libchart\Chart\Column;
use Libchart\Chart\Bar;
use Libchart\Chart\Line;
use Libchart\Chart\Pie;

Then, you just need to create the chart with you options and render it, as such, which produces a chart like the image below

<?php
use Libchart\Chart\Column;

$chart = new Column([
    'dataset' => [
        'labels' => ['Jan', 'Feb', 'Mar'],
        'data'   => [3296, 1546, 5015]
    ]
]);
$chart->render();

Sample column chart

Dataset

The dataset parameter is required and represents the information you want to display on the chart. There are two formats for dataset, based on the information you want to display

Beware

Failing to set a dataset key will result in a Libchart\Exception\DatasetNotDefinedException exception.

Single serie

If you want to display a single serie, you should set the 'dataset' key to an array of 'labels' and 'data'. Each element in 'data' can be either an integer (the value) or an array (the value and the color).

Make sure you use the same number of elements in labels and data.

The format for this dataset is as follows.

'dataset' => [
    'labels' => ['Jan', 'Feb', 'Mar'],
    'data' => [
        3296,
        [1546, '#F88C30'],
        5015,
    ]
]

The result of such dataset is similar to the example above.

Multiple series

Whenever you need to display multiple series in the same chart, you need to use another format for the dataset. Specifically, you should add a 'series' key, that must be an array with the series names.

As for the 'data' key, when using multiple series, you need to set it to an array of arrays.

'dataset' => [
    'series' => ['First series', 'Second Series'],
    'labels' => ['Jan', 'Feb', 'Mar'],
    'data'   => [
        [
            3296, 154, 5015
        ],
        [
            [564, '#cccccc'], 1564, 3215
        ],
    ],
]

Similar to the single series data points can either be an integer or an array, with the first element as the value and the second as the color.

Dataset multiple series

A note on Pie charts

For obvious reasons, Pie charts don't support multiple series. So, when creating a Pie chart, be sure to set a single serie.

It's also a good time to tell you that, any negative point value on Pie charts will be treated as 0.

Options

All the options are defined in config/config.php file. You can change the settings through the file but passing the settings when creating the chart is the preferred way.

The options are divided by components and are as follows

Parent key Option key Description Default value Type
chart width Sets the width for the output area 600 int
chart height Sets the height for the output area 300 int
chart logo Defines the file path for the logo if you intend to use one. Otherwise leave it as false.
If you specify a path that's not valid, the logo won't be rendered.
false string|bool
chart use-multiple-color Allows the points of a single series to have different colors false bool
chart sort-data-point Used for Pie charts only. Allows you to display the discs in the order they are placed on the dataset (false).
By default, the discs will be sorted by the point value.
true bool
chart bar-padding Array with four positions at most, with integer values, that represent the top-padding, right-padding, bottom-padding and left-padding used for the chart.
Use the key that matches the chart type you're creating.
If you pass an array with less then four values, the remaining paddings will be 0.
[5, 30, 30, 50] array
chart column-padding [5, 30, 50, 50] array
chart line-padding [5, 30, 50, 50] array
chart pie-padding [15, 10, 30, 30] array
title text The description of the chart. You probably want to set this for each chart Chart default title string
title font Path for the font (odt or ttf) to be used on the title.
You can either set this as the full path of the font file or simply set the font file name, if you want to use one of the SourceSans fonts (that are available on the fonts directory.
SourceSansPro-Semibold.otf string
title size Sets the font size to be used for the title text 12 int
title color Sets the color in which the title should be printed. Make sure you pass a valid hexadecimal color (with #) #999999 string
title height Sets the height of the title component. The greater the value, the greater the distance between the title and the chart area.
Note that the dimensions of the chart remain, so this results in the chart area to be smaller.
26 int
title padding Besides the height, you can set the padding for the title component, just as you do with the chart.
Like the chart padding, this accepts an array with four integer values for the top-padding, right-padding, bottom-padding and left-padding.
[15, 0, 15, 0] array
axis-label font Path for the font (odt or ttf) to be used on the axis text.
You can either set this as the full path of the font file or simply set the font file name, if you want to use one of the SourceSans fonts (that are available on the fonts directory.
SourceSansPro-Regular.otf string
axis-label size Determines the font size for the text 10 int
axis-label color Hexadecimal color for the axis labels #666666 string
axis-label angle The angle for the text rotation. Set this to the number of degrees you want to rotate the text. Accepts both positive and negative values. 0 int
axis-label margin Array with 'top' and 'left' key. Both keys should be set to an integer value that represents the top and left padding. [ 'top' => 15, 'left' => 0] array
axis-label generator A full qualified class name responsible for formatting the value axis.
If you want to display the value in a different format, use one of the available label generators or create your custom class that implements \Libchart\Label\LabelInterface.
\Libchart\Label\Short string
point-label show Boolean value that indicates if the point label should be displayed. If set to false, all the remaining settings are discarded. true bool
point-label font Path for the font (odt or ttf) to be used on the point label.
You can either set this as the full path of the font file or simply set the font file name, if you want to use one of the SourceSans fonts (that are available on the fonts directory.
SourceSansPro-Semibold.otf string
point-label size The size for the label 10 int
point-label color Hexadecimal color used when printing the point label #333333 string
point-label angle The angle for the label. Set this to an integer value to display the point label rotated. 0 int
point-label generator A full qualified class name responsible for formatting the point value.
If you want to display the value in a different format, use one of the available label generators or create your custom class that implements \Libchart\Label\LabelInterface
\Libchart\Label\NumberFormatter string

Label generators

The axis or point values are always formatted according to a given Label generator. This enables you to display the value in a custom format, based on the information you want to print. Libchart has a set of pre-defined formatters you can use (see the list below), but you can also create your own Label formatter and use it.

Libchart formatters

FQ Class Name Description Example
\Libchart\Label\DefaultLabel The more basic formatter. Just recieve the value and print it as it is, without any formatting. 100 => 100
30000 => 30000
\Libchart\Label\Short This formatter shortens the number. Instead of displaying the full number, displays a number and a letter for the power of the number.
This is the default label formatter for the value axis.
100 => 100
30000 => 30k
7000000 => 7M
\Libchart\Label\NumberFormatter Similar to the DefaultLabel formatter, this one prints the numbers in a specific format. Specifically, a separator is added for the thousands and millions. 100 => 100
30000 => 30 000
7000000 => 7 000 000
\Libchart\Label\PercentageFormatter Enables you to display percentage values, with decimals and the % symbol. 2.54 => 2,54 %
26 => 26,00 %
100 => 100,00 %
\Libchart\Label\EurCurrencyFormatter Uses the NumberFormatter and appends a symbol at the end of the number. 100 => 100 €
30000 => 30 000 €
7000000 => 7 000 000 €

Craft your own formatter

If you need a validator that doesn't yet exist, you can create your own Label Formatter class and use it on your chart.

Make sure your class implements \Libchart\Label\LabelInterface and then specify the full qualified class name on the chart settings (look for point-label.generator and axis-label.generator on the options section).

<?php

class ThousandLabelGenerator implements \Libchart\Label\LabelInterface
{
    public function generateLabel($value)
    {
        return ((int)($value / 1000)) . "k";
    }
}
(new Line([
    'axis-label' => [
     'generator' => 'ThousandLabelGenerator'
    ],
    'point-label' => [
      'generator' => 'ThousandLabelGenerator'
    ],
    'dataset' => [
        'labels' => ['Jan', 'Feb', 'Mar'],
        'data' => [
            3296,
            [1546, '#F88C30'],
            -256,
        ]
    ]
]))->render();

Methods

The only available public method is render(); which renders the chart. The method accepts an optional argument for the file path.

If no argument is specified, the image is created and displayed on the browser. Otherwise, an image is created on the specified file path.

Exceptions

Along the process some exceptions might be throwed if the data ins't on the expected format. Below you can check the list of existing exceptions and why they are throwed

Exception Description
\Libchart\Exception\DatasetNotDefinedException This exception is throwed when you fail to set a 'dataset' key array that's passed to the chart constructor. Make sure you take a look at the dataset option.
\Libchart\Exception\LogoFileNotFoundException If you setted a logo on the configuration and the logo cannot be found, this exception is throwed.
\Libchart\Exception\PointsInSeriesDontMatchException This exception might occur when you're creating a multiple series chart.
Make sure each array in 'dataset.data' has the exact same number of points. If you have a series that has 5 points and another with 3 points, this exception will be throwed.