reportbuilder/classes/datasource.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 declare(strict_types=1);
  18
  19 namespace core_reportbuilder;
  20
  21 use coding_exception;
  22 use core_reportbuilder\local\helpers\report;
  23 use core_reportbuilder\local\models\column as column_model;
  24 use core_reportbuilder\local\models\filter as filter_model;
  25 use core_reportbuilder\local\report\base;
  26 use core_reportbuilder\local\report\column;
  27 use core_reportbuilder\local\report\filter;
  28
  29 /**
  30  * Class datasource
  31  *
  32  * @package   core_reportbuilder
  33  * @copyright 2021 David Matamoros <davidmc@moodle.com>
  34  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  35  */
  36 abstract class datasource extends base {
  37
  38     /**
  39      * Return user friendly name of the datasource
  40      *
  41      * @return string
  42      */
  43     abstract public static function get_name(): string;
  44
  45     /**
  46      * Add columns from the given entity name to be available to use in a custom report
  47      *
  48      * @param string $entityname
  49      * @param array $include Include only these columns, if omitted then include all
  50      * @param array $exclude Exclude these columns, if omitted then exclude none
  51      * @throws coding_exception If both $include and $exclude are non-empty
  52      */
  53     final protected function add_columns_from_entity(string $entityname, array $include = [], array $exclude = []): void {
  54         if (!empty($include) && !empty($exclude)) {
  55             throw new coding_exception('Cannot specify columns to include and exclude simultaneously');
  56         }
  57
  58         $entity = $this->get_entity($entityname);
  59
  60         // Retrieve filtered columns from entity, respecting given $include/$exclude parameters.
  61         $columns = array_filter($entity->get_columns(), static function(column $column) use ($include, $exclude): bool {
  62             if (!empty($include)) {
  63                 return in_array($column->get_name(), $include);
  64             }
  65
  66             if (!empty($exclude)) {
  67                 return !in_array($column->get_name(), $exclude);
  68             }
  69
  70             return true;
  71         });
  72
  73         foreach ($columns as $column) {
  74             $this->add_column($column);
  75         }
  76     }
  77
  78     /**
  79      * Add default datasource columns to the report
  80      *
  81      * This method is optional and can be called when the report is created to add the default columns defined in the
  82      * selected datasource.
  83      */
  84     public function add_default_columns(): void {
  85         $reportid = $this->get_report_persistent()->get('id');
  86
  87         // Retrieve default column sorting, and track index of both sorted/non-sorted columns.
  88         $columnidentifiers = $this->get_default_columns();
  89         $defaultcolumnsorting = array_intersect_key($this->get_default_column_sorting(),
  90             array_fill_keys($columnidentifiers, 1));
  91         $columnnonsortingindex = count($defaultcolumnsorting) + 1;
  92
  93         foreach ($columnidentifiers as $uniqueidentifier) {
  94             $column = report::add_report_column($reportid, $uniqueidentifier);
  95
  96             // After adding the column, toggle sorting according to defaults provided by the datasource.
  97             $sortorder = array_search($uniqueidentifier, array_keys($defaultcolumnsorting));
  98             if ($sortorder !== false) {
  99                 $column->set_many([
 100                     'sortenabled' => true,
 101                     'sortdirection' => $defaultcolumnsorting[$uniqueidentifier],
 102                     'sortorder' => $sortorder + 1,
 103                 ])->update();
 104             } else if (!empty($defaultcolumnsorting)) {
 105                 $column->set('sortorder', $columnnonsortingindex++)->update();
 106             }
 107         }
 108     }
 109
 110     /**
 111      * Return the columns that will be added to the report once is created
 112      *
 113      * @return string[]
 114      */
 115     abstract public function get_default_columns(): array;
 116
 117     /**
 118      * Return the default sorting that will be added to the report once it is created
 119      *
 120      * @return int[] array [column identifier => SORT_ASC/SORT_DESC]
 121      */
 122     public function get_default_column_sorting(): array {
 123         return [];
 124     }
 125
 126     /**
 127      * Return all configured report columns
 128      *
 129      * @return column[]
 130      */
 131     public function get_active_columns(): array {
 132         $columns = [];
 133
 134         $activecolumns = column_model::get_records(['reportid' => $this->get_report_persistent()->get('id')], 'columnorder');
 135         foreach ($activecolumns as $index => $column) {
 136             $instance = $this->get_column($column->get('uniqueidentifier'));
 137             if ($instance !== null && $instance->get_is_available()) {
 138                 $instance->set_persistent($column);
 139
 140                 // We should clone the report column to ensure if it's added twice to a report, each operates independently.
 141                 $columns[] = clone $instance
 142                     ->set_index($index)
 143                     ->set_aggregation($column->get('aggregation'));
 144             }
 145         }
 146
 147         return $columns;
 148     }
 149
 150     /**
 151      * Add filters from the given entity name to be available to use in a custom report
 152      *
 153      * @param string $entityname
 154      * @param array $include Include only these filters, if omitted then include all
 155      * @param array $exclude Exclude these filters, if omitted then exclude none
 156      * @throws coding_exception If both $include and $exclude are non-empty
 157      */
 158     final protected function add_filters_from_entity(string $entityname, array $include = [], array $exclude = []): void {
 159         if (!empty($include) && !empty($exclude)) {
 160             throw new coding_exception('Cannot specify filters to include and exclude simultaneously');
 161         }
 162
 163         $entity = $this->get_entity($entityname);
 164
 165         // Retrieve filtered filters from entity, respecting given $include/$exclude parameters.
 166         $filters = array_filter($entity->get_filters(), static function(filter $filter) use ($include, $exclude): bool {
 167             if (!empty($include)) {
 168                 return in_array($filter->get_name(), $include);
 169             }
 170
 171             if (!empty($exclude)) {
 172                 return !in_array($filter->get_name(), $exclude);
 173             }
 174
 175             return true;
 176         });
 177
 178         foreach ($filters as $filter) {
 179             $this->add_filter($filter);
 180         }
 181     }
 182
 183     /**
 184      * Add default datasource filters to the report
 185      *
 186      * This method is optional and can be called when the report is created to add the default filters defined in the
 187      * selected datasource.
 188      */
 189     public function add_default_filters(): void {
 190         $reportid = $this->get_report_persistent()->get('id');
 191         $filteridentifiers = $this->get_default_filters();
 192         foreach ($filteridentifiers as $uniqueidentifier) {
 193             report::add_report_filter($reportid, $uniqueidentifier);
 194         }
 195     }
 196
 197     /**
 198      * Return the filters that will be added to the report once is created
 199      *
 200      * @return string[]
 201      */
 202     abstract public function get_default_filters(): array;
 203
 204     /**
 205      * Return all configured report filters
 206      *
 207      * @return filter[]
 208      */
 209     public function get_active_filters(): array {
 210         $filters = [];
 211
 212         $activefilters = filter_model::get_filter_records($this->get_report_persistent()->get('id'), 'filterorder');
 213         foreach ($activefilters as $filter) {
 214             $instance = $this->get_filter($filter->get('uniqueidentifier'));
 215             if ($instance !== null && $instance->get_is_available()) {
 216                 $filters[$instance->get_unique_identifier()] = $instance
 217                     ->set_persistent($filter);
 218             }
 219         }
 220
 221         return $filters;
 222     }
 223
 224     /**
 225      * Add conditions from the given entity name to be available to use in a custom report
 226      *
 227      * @param string $entityname
 228      * @param array $include Include only these conditions, if omitted then include all
 229      * @param array $exclude Exclude these conditions, if omitted then exclude none
 230      * @throws coding_exception If both $include and $exclude are non-empty
 231      */
 232     final protected function add_conditions_from_entity(string $entityname, array $include = [], array $exclude = []): void {
 233         if (!empty($include) && !empty($exclude)) {
 234             throw new coding_exception('Cannot specify conditions to include and exclude simultaneously');
 235         }
 236
 237         $entity = $this->get_entity($entityname);
 238
 239         // Retrieve filtered conditions from entity, respecting given $include/$exclude parameters.
 240         $conditions = array_filter($entity->get_conditions(), static function(filter $condition) use ($include, $exclude): bool {
 241             if (!empty($include)) {
 242                 return in_array($condition->get_name(), $include);
 243             }
 244
 245             if (!empty($exclude)) {
 246                 return !in_array($condition->get_name(), $exclude);
 247             }
 248
 249             return true;
 250         });
 251
 252         foreach ($conditions as $condition) {
 253             $this->add_condition($condition);
 254         }
 255     }
 256
 257     /**
 258      * Add default datasource conditions to the report
 259      *
 260      * This method is optional and can be called when the report is created to add the default conditions defined in the
 261      * selected datasource.
 262      */
 263     public function add_default_conditions(): void {
 264         $reportid = $this->get_report_persistent()->get('id');
 265         $conditionidentifiers = $this->get_default_conditions();
 266         foreach ($conditionidentifiers as $uniqueidentifier) {
 267             report::add_report_condition($reportid, $uniqueidentifier);
 268         }
 269
 270         // Set the default condition values if they have been set in the datasource.
 271         $this->set_condition_values($this->get_default_condition_values());
 272     }
 273
 274     /**
 275      * Return the conditions that will be added to the report once is created
 276      *
 277      * @return string[]
 278      */
 279     abstract public function get_default_conditions(): array;
 280
 281     /**
 282      * Return the default condition values that will be added to the report once is created
 283      *
 284      * For any of the default conditions returned by the method {@see get_default_conditions} is
 285      * possible to set the initial values.
 286      *
 287      * @return array
 288      */
 289     public function get_default_condition_values(): array {
 290         return [];
 291     }
 292
 293     /**
 294      * Return all configured report conditions
 295      *
 296      * @return filter[]
 297      */
 298     public function get_active_conditions(): array {
 299         $conditions = [];
 300
 301         $activeconditions = filter_model::get_condition_records($this->get_report_persistent()->get('id'), 'filterorder');
 302         foreach ($activeconditions as $condition) {
 303             $instance = $this->get_condition($condition->get('uniqueidentifier'));
 304             if ($instance !== null && $instance->get_is_available()) {
 305                 $conditions[$instance->get_unique_identifier()] = $instance->set_persistent($condition);
 306             }
 307         }
 308
 309         return $conditions;
 310     }
 311
 312     /**
 313      * Adds all columns/filters/conditions from the given entity to the report at once
 314      *
 315      * @param string $entityname
 316      */
 317     final protected function add_all_from_entity(string $entityname): void {
 318         $this->add_columns_from_entity($entityname);
 319         $this->add_filters_from_entity($entityname);
 320         $this->add_conditions_from_entity($entityname);
 321     }
 322
 323     /**
 324      * Adds all columns/filters/conditions from all the entities added to the report at once
 325      */
 326     final protected function add_all_from_entities(): void {
 327         foreach ($this->get_entities() as $entity) {
 328             $this->add_all_from_entity($entity->get_entity_name());
 329         }
 330     }
 331 }