[Summary view]

Differences Between: [Versions 400 and 402] [Versions 402 and 403]

   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\local\entities;
  20  
  21  use coding_exception;
  22  use lang_string;
  23  use core_reportbuilder\local\report\column;
  24  use core_reportbuilder\local\report\filter;
  25  
  26  /**
  27   * Base class for all report entities
  28   *
  29   * @package     core_reportbuilder
  30   * @copyright   2019 Marina Glancy <marina@moodle.com>
  31   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  32   */
  33  abstract class base {
  34  
  35      /** @var string $entityname Internal reference to name of entity */
  36      private $entityname = '';
  37  
  38      /** @var lang_string $entitytitle Used as a title for the entity in reports */
  39      private $entitytitle = null;
  40  
  41      /** @var array $tablealiases Database tables that this entity uses and their default aliases */
  42      private $tablealiases = [];
  43  
  44      /** @var string[] $joins List of SQL joins for the entity */
  45      private $joins = [];
  46  
  47      /** @var column[] $columns List of columns for the entity */
  48      private $columns = [];
  49  
  50      /** @var filter[] $filters List of filters for the entity */
  51      private $filters = [];
  52  
  53      /** @var filter[] $conditions List of conditions for the entity */
  54      private $conditions = [];
  55  
  56      /**
  57       * Database tables that this entity uses and their default aliases
  58       *
  59       * Must be overridden by the entity to list all database tables that it expects to be present in the main
  60       * SQL or in JOINs added to this entity
  61       *
  62       * @return string[] Array of $tablename => $alias
  63       */
  64      abstract protected function get_default_table_aliases(): array;
  65  
  66      /**
  67       * The default title for this entity
  68       *
  69       * @return lang_string
  70       */
  71      abstract protected function get_default_entity_title(): lang_string;
  72  
  73      /**
  74       * Initialise the entity, called automatically when it is added to a report
  75       *
  76       * This is where entity defines all its columns and filters by calling:
  77       * - {@see add_column}
  78       * - {@see add_filter}
  79       * - etc
  80       *
  81       * @return self
  82       */
  83      abstract public function initialise(): self;
  84  
  85      /**
  86       * The default machine-readable name for this entity that will be used in the internal names of the columns/filters
  87       *
  88       * @return string
  89       */
  90      protected function get_default_entity_name(): string {
  91          $namespace = explode('\\', get_called_class());
  92  
  93          return end($namespace);
  94      }
  95  
  96      /**
  97       * Set entity name
  98       *
  99       * @param string $entityname
 100       * @return self
 101       * @throws coding_exception
 102       */
 103      final public function set_entity_name(string $entityname): self {
 104          if ($entityname === '' || $entityname !== clean_param($entityname, PARAM_ALPHANUMEXT)) {
 105              throw new coding_exception('Entity name must be comprised of alphanumeric character, underscore or dash');
 106          }
 107  
 108          $this->entityname = $entityname;
 109          return $this;
 110      }
 111  
 112      /**
 113       * Return entity name
 114       *
 115       * @return string
 116       */
 117      final public function get_entity_name(): string {
 118          return $this->entityname ?: $this->get_default_entity_name();
 119      }
 120  
 121      /**
 122       * Set entity title
 123       *
 124       * @param lang_string $title
 125       * @return self
 126       */
 127      final public function set_entity_title(lang_string $title): self {
 128          $this->entitytitle = $title;
 129          return $this;
 130      }
 131  
 132      /**
 133       * Get entity title
 134       *
 135       * @return lang_string
 136       */
 137      final public function get_entity_title(): lang_string {
 138          return $this->entitytitle ?? $this->get_default_entity_title();
 139      }
 140  
 141      /**
 142       * Override the default alias for given database table used in entity queries, to avoid table alias clashes that may occur
 143       * if multiple entities of a report each define the same default alias for one of their tables
 144       *
 145       * @param string $tablename
 146       * @param string $alias
 147       * @return self
 148       * @throws coding_exception
 149       */
 150      final public function set_table_alias(string $tablename, string $alias): self {
 151          if (!array_key_exists($tablename, $this->get_default_table_aliases())) {
 152              throw new coding_exception('Invalid table name', $tablename);
 153          }
 154  
 155          $this->tablealiases[$tablename] = $alias;
 156          return $this;
 157      }
 158  
 159      /**
 160       * Override multiple default database table aliases used in entity queries as per {@see set_table_alias}, typically when
 161       * you're adding an entity multiple times to a report you'd want to override the table aliases in the second instance to
 162       * avoid clashes with the first
 163       *
 164       * @param array $aliases Array of tablename => alias values
 165       * @return self
 166       */
 167      final public function set_table_aliases(array $aliases): self {
 168          foreach ($aliases as $tablename => $alias) {
 169              $this->set_table_alias($tablename, $alias);
 170          }
 171          return $this;
 172      }
 173  
 174      /**
 175       * Returns an alias used in the queries for a given table
 176       *
 177       * @param string $tablename
 178       * @return string
 179       * @throws coding_exception
 180       */
 181      final public function get_table_alias(string $tablename): string {
 182          $defaulttablealiases = $this->get_default_table_aliases();
 183          if (!array_key_exists($tablename, $defaulttablealiases)) {
 184              throw new coding_exception('Invalid table name', $tablename);
 185          }
 186  
 187          return $this->tablealiases[$tablename] ?? $defaulttablealiases[$tablename];
 188      }
 189  
 190      /**
 191       * Add join clause required for this entity to join to existing tables/entities
 192       *
 193       * @param string $join
 194       * @return self
 195       */
 196      final public function add_join(string $join): self {
 197          $this->joins[trim($join)] = trim($join);
 198          return $this;
 199      }
 200  
 201      /**
 202       * Add multiple join clauses required for this entity {@see add_join}
 203       *
 204       * @param string[] $joins
 205       * @return self
 206       */
 207      final public function add_joins(array $joins): self {
 208          foreach ($joins as $join) {
 209              $this->add_join($join);
 210          }
 211          return $this;
 212      }
 213  
 214      /**
 215       * Return entity joins
 216       *
 217       * @return string[]
 218       */
 219      final public function get_joins(): array {
 220          return array_values($this->joins);
 221      }
 222  
 223      /**
 224       * Add a column to the entity
 225       *
 226       * @param column $column
 227       * @return self
 228       */
 229      final protected function add_column(column $column): self {
 230          $this->columns[$column->get_name()] = $column;
 231          return $this;
 232      }
 233  
 234      /**
 235       * Returns entity columns
 236       *
 237       * @return column[]
 238       */
 239      final public function get_columns(): array {
 240          return $this->columns;
 241      }
 242  
 243      /**
 244       * Returns an entity column
 245       *
 246       * @param string $name
 247       * @return column
 248       * @throws coding_exception For invalid column name
 249       */
 250      final public function get_column(string $name): column {
 251          if (!array_key_exists($name, $this->columns)) {
 252              throw new coding_exception('Invalid column name', $name);
 253          }
 254  
 255          return $this->columns[$name];
 256      }
 257  
 258      /**
 259       * Add a filter to the entity
 260       *
 261       * @param filter $filter
 262       * @return self
 263       */
 264      final protected function add_filter(filter $filter): self {
 265          $this->filters[$filter->get_name()] = $filter;
 266          return $this;
 267      }
 268  
 269      /**
 270       * Returns entity filters
 271       *
 272       * @return filter[]
 273       */
 274      final public function get_filters(): array {
 275          return $this->filters;
 276      }
 277  
 278      /**
 279       * Returns an entity filter
 280       *
 281       * @param string $name
 282       * @return filter
 283       * @throws coding_exception For invalid filter name
 284       */
 285      final public function get_filter(string $name): filter {
 286          if (!array_key_exists($name, $this->filters)) {
 287              throw new coding_exception('Invalid filter name', $name);
 288          }
 289  
 290          return $this->filters[$name];
 291      }
 292  
 293      /**
 294       * Add a condition to the entity
 295       *
 296       * @param filter $condition
 297       * @return $this
 298       */
 299      final protected function add_condition(filter $condition): self {
 300          $this->conditions[$condition->get_name()] = $condition;
 301          return $this;
 302      }
 303  
 304      /**
 305       * Returns entity conditions
 306       *
 307       * @return filter[]
 308       */
 309      final public function get_conditions(): array {
 310          return $this->conditions;
 311      }
 312  
 313      /**
 314       * Returns an entity condition
 315       *
 316       * @param string $name
 317       * @return filter
 318       * @throws coding_exception For invalid condition name
 319       */
 320      final public function get_condition(string $name): filter {
 321          if (!array_key_exists($name, $this->conditions)) {
 322              throw new coding_exception('Invalid condition name', $name);
 323          }
 324  
 325          return $this->conditions[$name];
 326      }
 327  }