beastbytes/yii-chartist

Chartist JavaScript charting library integration for Yii3

dev-master 2025-10-09 12:49 UTC

Requires

• php: >=8.1
• yiisoft/assets: dev-master
• yiisoft/html: ^3.0
• yiisoft/widget: ^2.0

Requires (Dev)

• phpunit/phpunit: ^10.0
• roave/security-advisories: dev-latest
• vimeo/psalm: ^6.0
• yiisoft/aliases: ^3.0
• yiisoft/cache: ^3.0
• yiisoft/event-dispatcher: ^1.0
• yiisoft/test-support: ^3.0
• yiisoft/view: ^12.0

BSD-3-Clause

• Chris Yates

• chart
• charts
• charting
• chartist
• yii3

README

Yii Chartist

Yii Chartist is a widget that integrates the Chartist JavaScript charting library with Yii3.

For license information see the LICENSE file.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist beastbytes/yii-chartist

or add

"beastbytes/yii-chartist": "<version-constraint>"

to the require section of your composer.json.

Chartist Package

Install Leaflet using your chosen package manager, e.g.

pnpm add chartist

yarn add chartist

or add Chartist to the dependencies of your package.json.

"chartist": "<version-constraint>"

Usage

The Yii Chartist widget is used in a view or in another widget; usage is the same in both cases; the example below shows how to use the widget in a view.

The widget registers ChartistAsset with the asset manager and the Chartist JavaScript in the view, and renders the Chartist div.

<?php

use Loytyi\Chartist\Chartist;
use Loytyi\Chartist\ChartType;
use Yiisoft\Assets\AssetManager;
use Yiisoft\View\WebView;

/**
 * @var AssetManager $assetManager
 * @var array $data
 * @var array $options
 * @var array $responsiveOptions
 * @var WebView $this
 */
 
echo Chartist::widget($assetManager, $this)
    ->id('my-chart')
    ->type(ChartType::Line)
    ->data($data)
    ->options($options)
    ->responsiveOptions($responsiveOptions)
    ->render()
;

The chart type is specified by the ChartType enum; Chartist supports Bar, Line, and Pie charts.

See the Chartist documentation and source code for details on $data, $options, and $responsiveOptions; the widget values are PHP arrays that are encoded when the widget is rendered.

Tip:

The widget has a convenience function, Chartist::JsExpression(), to allow JavaScript expressions to be correctly encoded; example:

'options' => [
    'labelInterpolationFnc' => Chartist::jsExpression('value => String(value)[0]')
],

is encoded as {"labelInterpolationFnc":value => String(value)[0]}

Chartist does one thing; draws charts. Additional functionality. e.g. event handlers, animation, etc. can be added by JavaScript,

To help with this the Yii Chartist widget sets a JavaScript constant whose name is the chart's id in snake_case, and value is the chart instance; the getId() method provides this value; example: an id of my-chart results in a JavaScript constant named my_chart.

Tip:

If the application does not set the widget id, the widget will generate a unique id of the form chart_\d{15}. The generated id will change on each HTTP request.

Styling

Chartist provides default styles for charts. To change styles simply add the appropriate rules to your CSS; note that it is SVG that is being styled.

API

id(string $id): self

Optional

Sets the widget id. If not set, the widget generates a unique id of the form chart_\d{15}.

data(array $data): self

Required

Chart data and labels.

getId(): string

Returns the widget id. If the id is not set it is generated.

options(array $options): self

Optional

Chart options.

responsiveOptions(array $responsiveOptions): self

Optional

Options for responsive designs.

type(ChartType $type): self

Required

The chart type.

static jsExpression(string $value): string

Marks the value as a JavaScript expression to ensure correct encoding.