Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Chart base.
 *
 * @package    core
 * @copyright  2016 Frédéric Massart - FMCorz.net
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core;
defined('MOODLE_INTERNAL') || die();

use coding_exception;
use JsonSerializable;
use renderable;

/**
 * Chart base class.
 *
 * @package    core
 * @copyright  2016 Frédéric Massart - FMCorz.net
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class chart_base implements JsonSerializable, renderable {

    /** @var chart_series[] The series constituting this chart. */
    protected $series = [];
    /** @var string[] The labels for the X axis when categorised. */
    protected $labels = [];
    /** @var string The title of the chart. */
    protected $title = null;
    /** @var chart_axis[] The X axes. */
    protected $xaxes = [];
    /** @var chart_axis[] The Y axes. */
    protected $yaxes = [];
    /** @var array Options for the chart legend. */
    protected $legendoptions = [];

    /**
     * Constructor.
     *
     * Must not take any argument.
     *
     * Most of the time you do not want to extend this, rather extend the
     * method {@link self::set_defaults} to set the defaults on instantiation.
     */
    public function __construct() {
        $this->set_defaults();
    }

    /**
     * Add a series to the chart.
     *
     * @param chart_series $serie The serie.
     */
    public function add_series(chart_series $serie) {
        $this->series[] = $serie;
    }

    /**
     * Serialize the object.
     *
     * @return array
     */
< public function jsonSerialize() { // @codingStandardsIgnoreLine (CONTRIB-6469).
> public function jsonSerialize(): array {
global $CFG; return [ 'type' => $this->get_type(), 'series' => $this->series, 'labels' => $this->labels, 'title' => $this->title, 'axes' => [ 'x' => $this->xaxes, 'y' => $this->yaxes, ], 'legend_options' => !empty($this->legendoptions) ? $this->legendoptions : null, 'config_colorset' => !empty($CFG->chart_colorset) ? $CFG->chart_colorset : null ]; } /** * Get an axis. * * @param string $type Accepts values 'x' or 'y'. * @param int $index The index of this axis. * @param bool $createifnotexists Whether to create the axis if not found. * @return chart_axis */ private function get_axis($type, $index, $createifnotexists) { $isx = $type === 'x'; if ($isx) { $axis = isset($this->xaxes[$index]) ? $this->xaxes[$index] : null; } else { $axis = isset($this->yaxes[$index]) ? $this->yaxes[$index] : null; } if ($axis === null) { if (!$createifnotexists) { throw new coding_exception('Unknown axis.'); } $axis = new chart_axis(); if ($isx) { $this->set_xaxis($axis, $index); } else { $this->set_yaxis($axis, $index); } } return $axis; } /** * Get the labels of the X axis. * * @return string[] */ public function get_labels() { return $this->labels; } /** * Get an array of options for the chart legend. * * @return array */ public function get_legend_options() { return $this->legendoptions; } /** * Get the series. * * @return chart_series[] */ public function get_series() { return $this->series; } /** * Get the title. * * @return string */ public function get_title() { return $this->title; } /** * Get the chart type. * * @return string */ public function get_type() { $classname = get_class($this); return substr($classname, strpos($classname, '_') + 1); } /** * Get the X axes. * * @return chart_axis[] */ public function get_xaxes() { return $this->xaxes; } /** * Get an X axis. * * @param int $index The index of the axis. * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet. * @return chart_axis */ public function get_xaxis($index = 0, $createifnotexists = false) { return $this->get_axis('x', $index, $createifnotexists); } /** * Get the Y axes. * * @return chart_axis[] */ public function get_yaxes() { return $this->yaxes; } /** * Get a Y axis. * * @param int $index The index of the axis. * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet. * @return chart_axis */ public function get_yaxis($index = 0, $createifnotexists = false) { return $this->get_axis('y', $index, $createifnotexists); } /** * Set the defaults for this chart type. * * Child classes can extend this to set default values on instantiation. * * In general the constructor could be used, but this method is here to * emphasize and self-document the default values set by the chart type. * * @return void */ protected function set_defaults() { } /** * Set the chart labels. * * @param string[] $labels The labels. */ public function set_labels(array $labels) { $this->labels = $labels; } /** * Set options for the chart legend. * See https://www.chartjs.org/docs/2.7.0/configuration/legend.html for options. * * Note: Setting onClick and onHover events is not directly supported through * this method. These config options must be set directly within Javascript * on the page. * * @param array $legendoptions Whether or not to display the chart's legend. */ public function set_legend_options(array $legendoptions) { $this->legendoptions = $legendoptions; } /** * Set the title. * * @param string $title The title. */ public function set_title($title) { $this->title = $title; } /** * Set an X axis. * * Note that this will override any predefined axis without warning. * * @param chart_axis $axis The axis. * @param int $index The index of the axis. */ public function set_xaxis(chart_axis $axis, $index = 0) { $this->validate_axis('x', $axis, $index); return $this->xaxes[$index] = $axis; } /** * Set an Y axis. * * Note that this will override any predefined axis without warning. * * @param chart_axis $axis The axis. * @param int $index The index of the axis. */ public function set_yaxis(chart_axis $axis, $index = 0) { $this->validate_axis('y', $axis, $index); return $this->yaxes[$index] = $axis; } /** * Validate an axis. * * We validate this from PHP because not doing it here could result in errors being * hard to trace down. For instance, if we were to add axis at keys without another * axis preceding, we would effectively contain the axes in an associative array * rather than a simple array, and that would have consequences on serialisation. * * @param string $xy Accepts x or y. * @param chart_axis $axis The axis to validate. * @param index $index The index of the axis. */ protected function validate_axis($xy, chart_axis $axis, $index = 0) { if ($index > 0) { $axes = $xy == 'x' ? $this->xaxes : $this->yaxes; if (!isset($axes[$index - 1])) { throw new coding_exception('Missing ' . $xy . ' axis at index lower than ' . $index); } } } }