[Summary view]

Differences Between: [Versions 400 and 401] [Versions 400 and 402] [Versions 400 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
 143       *
 144       * @param string $tablename
 145       * @param string $alias
 146       * @return self
 147       * @throws coding_exception
 148       */
 149      final public function set_table_alias(string $tablename, string $alias): self {
 150          if (!array_key_exists($tablename, $this->get_default_table_aliases())) {
 151              throw new coding_exception('Invalid table name', $tablename);
 152          }
 153  
 154          $this->tablealiases[$tablename] = $alias;
 155          return $this;
 156      }
 157  
 158      /**
 159       * Returns an alias used in the queries for a given table
 160       *
 161       * @param string $tablename
 162       * @return string
 163       * @throws coding_exception
 164       */
 165      final public function get_table_alias(string $tablename): string {
 166          $defaulttablealiases = $this->get_default_table_aliases();
 167          if (!array_key_exists($tablename, $defaulttablealiases)) {
 168              throw new coding_exception('Invalid table name', $tablename);
 169          }
 170  
 171          return $this->tablealiases[$tablename] ?? $defaulttablealiases[$tablename];
 172      }
 173  
 174      /**
 175       * Add join clause required for this entity to join to existing tables/entities
 176       *
 177       * @param string $join
 178       * @return self
 179       */
 180      final public function add_join(string $join): self {
 181          $this->joins[trim($join)] = trim($join);
 182          return $this;
 183      }
 184  
 185      /**
 186       * Add multiple join clauses required for this entity {@see add_join}
 187       *
 188       * @param string[] $joins
 189       * @return self
 190       */
 191      final public function add_joins(array $joins): self {
 192          foreach ($joins as $join) {
 193              $this->add_join($join);
 194          }
 195          return $this;
 196      }
 197  
 198      /**
 199       * Return entity joins
 200       *
 201       * @return string[]
 202       */
 203      final protected function get_joins(): array {
 204          return array_values($this->joins);
 205      }
 206  
 207      /**
 208       * Add a column to the entity
 209       *
 210       * @param column $column
 211       * @return self
 212       */
 213      final protected function add_column(column $column): self {
 214          $this->columns[$column->get_name()] = $column;
 215          return $this;
 216      }
 217  
 218      /**
 219       * Returns entity columns
 220       *
 221       * @return column[]
 222       */
 223      final public function get_columns(): array {
 224          return $this->columns;
 225      }
 226  
 227      /**
 228       * Returns an entity column
 229       *
 230       * @param string $name
 231       * @return column
 232       * @throws coding_exception For invalid column name
 233       */
 234      final public function get_column(string $name): column {
 235          if (!array_key_exists($name, $this->columns)) {
 236              throw new coding_exception('Invalid column name', $name);
 237          }
 238  
 239          return $this->columns[$name];
 240      }
 241  
 242      /**
 243       * Add a filter to the entity
 244       *
 245       * @param filter $filter
 246       * @return self
 247       */
 248      final protected function add_filter(filter $filter): self {
 249          $this->filters[$filter->get_name()] = $filter;
 250          return $this;
 251      }
 252  
 253      /**
 254       * Returns entity filters
 255       *
 256       * @return filter[]
 257       */
 258      final public function get_filters(): array {
 259          return $this->filters;
 260      }
 261  
 262      /**
 263       * Returns an entity filter
 264       *
 265       * @param string $name
 266       * @return filter
 267       * @throws coding_exception For invalid filter name
 268       */
 269      final public function get_filter(string $name): filter {
 270          if (!array_key_exists($name, $this->filters)) {
 271              throw new coding_exception('Invalid filter name', $name);
 272          }
 273  
 274          return $this->filters[$name];
 275      }
 276  
 277      /**
 278       * Add a condition to the entity
 279       *
 280       * @param filter $condition
 281       * @return $this
 282       */
 283      final protected function add_condition(filter $condition): self {
 284          $this->conditions[$condition->get_name()] = $condition;
 285          return $this;
 286      }
 287  
 288      /**
 289       * Returns entity conditions
 290       *
 291       * @return filter[]
 292       */
 293      final public function get_conditions(): array {
 294          return $this->conditions;
 295      }
 296  
 297      /**
 298       * Returns an entity condition
 299       *
 300       * @param string $name
 301       * @return filter
 302       * @throws coding_exception For invalid condition name
 303       */
 304      final public function get_condition(string $name): filter {
 305          if (!array_key_exists($name, $this->conditions)) {
 306              throw new coding_exception('Invalid condition name', $name);
 307          }
 308  
 309          return $this->conditions[$name];
 310      }
 311  }