See Release Notes
Long Term Support Release
Differences Between: [Versions 400 and 401] [Versions 401 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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body