MDL-49231 mod_glossary: Minor coding style improvements
[moodle.git] / mod / glossary / classes / entry_query_builder.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/>.
17 /**
18  * Entry query builder.
19  *
20  * @package    mod_glossary
21  * @copyright  2015 Frédéric Massart - FMCorz.net
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 defined('MOODLE_INTERNAL') || die();
27 /**
28  * Entry query builder class.
29  *
30  * The purpose of this class is to avoid duplicating SQL statements to fetch entries
31  * which are very similar with each other. This builder is not meant to be smart, it
32  * will not out rule any previously set condition, or join, etc...
33  *
34  * You should be using this builder just like you would be creating your SQL query. Only
35  * some methods are shorthands to avoid logic duplication and common mistakes.
36  *
37  * @package    mod_glossary
38  * @copyright  2015 Frédéric Massart - FMCorz.net
39  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40  * @since      Moodle 3.1
41  */
42 class mod_glossary_entry_query_builder {
44     /** Alias for table glossary_alias. */
45     const ALIAS_ALIAS = 'ga';
46     /** Alias for table glossary_categories. */
47     const ALIAS_CATEGORIES = 'gc';
48     /** Alias for table glossary_entries_categories. */
49     const ALIAS_ENTRIES_CATEGORIES = 'gec';
50     /** Alias for table glossary_entries. */
51     const ALIAS_ENTRIES = 'ge';
52     /** Alias for table user. */
53     const ALIAS_USER = 'u';
55     /** Include none of the entries to approve. */
56     const NON_APPROVED_NONE = 'na_none';
57     /** Including all the entries. */
58     const NON_APPROVED_ALL = 'na_all';
59     /** Including only the entries to be approved. */
60     const NON_APPROVED_ONLY = 'na_only';
61     /** Including my entries to be approved. */
62     const NON_APPROVED_SELF = 'na_self';
64     /** @var array Raw SQL statements representing the fields to select. */
65     protected $fields = array();
66     /** @var array Raw SQL statements representing the JOINs to make. */
67     protected $joins = array();
68     /** @var string Raw SQL statement representing the FROM clause. */
69     protected $from;
70     /** @var object The glossary we are fetching from. */
71     protected $glossary;
72     /** @var int The number of records to fetch from. */
73     protected $limitfrom = 0;
74     /** @var int The number of records to fetch. */
75     protected $limitnum = 0;
76     /** @var array List of SQL parameters. */
77     protected $params = array();
78     /** @var array Raw SQL statements representing the ORDER clause. */
79     protected $order = array();
80     /** @var array Raw SQL statements representing the WHERE clause. */
81     protected $where = array();
83     /**
84      * Constructor.
85      *
86      * @param object $glossary The glossary.
87      */
88     public function __construct($glossary = null) {
89         $this->from = sprintf('FROM {glossary_entries} %s', self::ALIAS_ENTRIES);
90         if (!empty($glossary)) {
91             $this->glossary = $glossary;
92             $this->where[] = sprintf('(%s.glossaryid = :gid OR %s.sourceglossaryid = :gid2)',
93                 self::ALIAS_ENTRIES, self::ALIAS_ENTRIES);
94             $this->params['gid'] = $glossary->id;
95             $this->params['gid2'] = $glossary->id;
96         }
97     }
99     /**
100      * Add a field to select.
101      *
102      * @param string $field The field, or *.
103      * @param string $table The table name, without the prefix 'glossary_'.
104      * @param string $alias An alias for the field.
105      */
106     public function add_field($field, $table, $alias = null) {
107         $field = self::resolve_field($field, $table);
108         if (!empty($alias)) {
109             $field .= ' AS ' . $alias;
110         }
111         $this->fields[] = $field;
112     }
114     /**
115      * Adds the user fields.
116      *
117      * @return void
118      */
119     public function add_user_fields() {
120         $this->fields[] = user_picture::fields('u', null, 'userdataid', 'userdata');
121     }
123     /**
124      * Internal method to build the query.
125      *
126      * @param bool $count Query to count?
127      * @return string The SQL statement.
128      */
129     protected function build_query($count = false) {
130         $sql = 'SELECT ';
132         if ($count) {
133             $sql .= 'COUNT(\'x\') ';
134         } else {
135             $sql .= implode(', ', $this->fields) . ' ';
136         }
138         $sql .= $this->from . ' ';
139         $sql .= implode(' ', $this->joins) . ' ';
141         if (!empty($this->where)) {
142             $sql .= 'WHERE (' . implode(') AND (', $this->where) . ') ';
143         }
145         if (!$count && !empty($this->order)) {
146             $sql .= 'ORDER BY ' . implode(', ', $this->order);
147         }
149         return $sql;
150     }
152     /**
153      * Count the records.
154      *
155      * @return int The number of records.
156      */
157     public function count_records() {
158         global $DB;
159         return $DB->count_records_sql($this->build_query(true), $this->params);
160     }
162     /**
163      * Distinct a field.
164      *
165      * @param string $field The field.
166      * @param string $table The table name, without the prefix 'glossary_'.
167      */
168     public function distinct($field, $table) {
169         $field = self::resolve_field($field, $table);
170         array_unshift($this->fields, 'DISTINCT(' . $field . ')');
171     }
173     /**
174      * Filter a field using a letter.
175      *
176      * @param string $letter     The letter.
177      * @param string $finalfield The SQL statement representing the field.
178      */
179     protected function filter_by_letter($letter, $finalfield) {
180         global $DB;
182         $letter = core_text::strtoupper($letter);
183         $len = core_text::strlen($letter);
184         $sql = $DB->sql_substr(sprintf('upper(%s)', $finalfield), 1, $len);
186         $this->where[] = "$sql = :letter";
187         $this->params['letter'] = $letter;
188     }
190     /**
191      * Filter a field by special characters.
192      *
193      * @param string $finalfield The SQL statement representing the field.
194      */
195     protected function filter_by_non_letter($finalfield) {
196         global $DB;
198         $alphabet = explode(',', get_string('alphabet', 'langconfig'));
199         list($nia, $aparams) = $DB->get_in_or_equal($alphabet, SQL_PARAMS_NAMED, 'nonletter', false);
201         $sql = $DB->sql_substr(sprintf('upper(%s)', $finalfield), 1, 1);
203         $this->where[] = "$sql $nia";
204         $this->params = array_merge($this->params, $aparams);
205     }
207     /**
208      * Filter the author by letter.
209      *
210      * @param string  $letter         The letter.
211      * @param bool    $firstnamefirst Whether or not the firstname is first in the author's name.
212      */
213     public function filter_by_author_letter($letter, $firstnamefirst = false) {
214         $field = self::get_fullname_field($firstnamefirst);
215         $this->filter_by_letter($letter, $field);
216     }
218     /**
219      * Filter the author by special characters.
220      *
221      * @param bool $firstnamefirst Whether or not the firstname is first in the author's name.
222      */
223     public function filter_by_author_non_letter($firstnamefirst = false) {
224         $field = self::get_fullname_field($firstnamefirst);
225         $this->filter_by_non_letter($field);
226     }
228     /**
229      * Filter the concept by letter.
230      *
231      * @param string  $letter         The letter.
232      */
233     public function filter_by_concept_letter($letter) {
234         $this->filter_by_letter($letter, self::resolve_field('concept', 'entries'));
235     }
237     /**
238      * Filter the concept by special characters.
239      *
240      * @return void
241      */
242     public function filter_by_concept_non_letter() {
243         $this->filter_by_non_letter(self::resolve_field('concept', 'entries'));
244     }
246     /**
247      * Filter non approved entries.
248      *
249      * @param string $constant One of the NON_APPROVED_* constants.
250      * @param int    $userid   The user ID when relevant, otherwise current user.
251      */
252     public function filter_by_non_approved($constant, $userid = null) {
253         global $USER;
254         if (!$userid) {
255             $userid = $USER->id;
256         }
258         if ($constant === self::NON_APPROVED_ALL) {
259             // Nothing to do.
261         } else if ($constant === self::NON_APPROVED_SELF) {
262             $this->where[] = sprintf('%s != 0 OR %s = :toapproveuserid',
263                 self::resolve_field('approved', 'entries'), self::resolve_field('userid', 'entries'));
264             $this->params['toapproveuserid'] = $USER->id;
266         } else if ($constant === self::NON_APPROVED_NONE) {
267             $this->where[] = sprintf('%s != 0', self::resolve_field('approved', 'entries'));
269         } else if ($constant === self::NON_APPROVED_ONLY) {
270             $this->where[] = sprintf('%s = 0', self::resolve_field('approved', 'entries'));
272         } else {
273             throw new coding_exception('Invalid constant');
274         }
275     }
277     /**
278      * Filter by concept or alias.
279      *
280      * This requires the alias table to be joined in the query. See {@link self::join_alias()}.
281      *
282      * @param string $term What the concept or aliases should be.
283      */
284     public function filter_by_term($term) {
285         $this->where[] = sprintf("(%s = :filterterma OR %s = :filtertermb)",
286             self::resolve_field('concept', 'entries'),
287             self::resolve_field('alias', 'alias'));
288         $this->params['filterterma'] = $term;
289         $this->params['filtertermb'] = $term;
290     }
292     /**
293      * Filter by search terms.
294      *
295      * Note that this does not handle invalid or too short terms. This requires the alias
296      * table to be joined in the query. See {@link self::join_alias()}.
297      *
298      * @param array   $terms      Array of terms.
299      * @param bool    $fullsearch Whether or not full search should be enabled.
300      */
301     public function filter_by_search_terms(array $terms, $fullsearch = true) {
302         global $DB;
303         static $i = 0;
305         if ($DB->sql_regex_supported()) {
306             $regexp = $DB->sql_regex(true);
307             $notregexp = $DB->sql_regex(false);
308         }
310         $params = array();
311         $conceptfield = self::resolve_field('concept', 'entries');
312         $aliasfield = self::resolve_field('alias', 'alias');
313         $definitionfield = self::resolve_field('definition', 'entries');
314         $conditions = array();
316         foreach ($terms as $searchterm) {
317             $i++;
319             $not = false; // Initially we aren't going to perform NOT LIKE searches, only MSSQL and Oracle
320                           // will use it to simulate the "-" operator with LIKE clause.
322             if (empty($fullsearch)) {
323                 // With fullsearch disabled, look only within concepts and aliases.
324                 $concat = $DB->sql_concat($conceptfield, "' '", "COALESCE($aliasfield, :emptychar{$i})");
325             } else {
326                 // With fullsearch enabled, look also within definitions.
327                 $concat = $DB->sql_concat($conceptfield, "' '", $definitionfield, "' '", "COALESCE($aliasfield, :emptychar{$i})");
328             }
329             $params['emptychar' . $i] = '';
331             // Under Oracle and MSSQL, trim the + and - operators and perform simpler LIKE (or NOT LIKE) queries.
332             if (!$DB->sql_regex_supported()) {
333                 if (substr($searchterm, 0, 1) === '-') {
334                     $not = true;
335                 }
336                 $searchterm = trim($searchterm, '+-');
337             }
339             if (substr($searchterm, 0, 1) === '+') {
340                 $searchterm = trim($searchterm, '+-');
341                 $conditions[] = "$concat $regexp :searchterm{$i}";
342                 $params['searchterm' . $i] = '(^|[^a-zA-Z0-9])' . preg_quote($searchterm, '|') . '([^a-zA-Z0-9]|$)';
344             } else if (substr($searchterm, 0, 1) === "-") {
345                 $searchterm = trim($searchterm, '+-');
346                 $conditions[] = "$concat $notregexp :searchterm{$i}";
347                 $params['searchterm' . $i] = '(^|[^a-zA-Z0-9])' . preg_quote($searchterm, '|') . '([^a-zA-Z0-9]|$)';
349             } else {
350                 $conditions[] = $DB->sql_like($concat, ":searchterm{$i}", false, true, $not);
351                 $params['searchterm' . $i] = '%' . $DB->sql_like_escape($searchterm) . '%';
352             }
353         }
355         // When there are no conditions we add a negative one to ensure that we don't return anything.
356         if (empty($conditions)) {
357             $conditions[] = '1 = 2';
358         }
360         $this->where[] = implode(' AND ', $conditions);
361         $this->params = array_merge($this->params, $params);
362     }
364     /**
365      * Convenience method to get get the SQL statement for the full name.
366      *
367      * @param bool $firstnamefirst Whether or not the firstname is first in the author's name.
368      * @return string The SQL statement.
369      */
370     public static function get_fullname_field($firstnamefirst = false) {
371         global $DB;
372         if ($firstnamefirst) {
373             return $DB->sql_fullname(self::resolve_field('firstname', 'user'), self::resolve_field('lastname', 'user'));
374         }
375         return $DB->sql_fullname(self::resolve_field('lastname', 'user'), self::resolve_field('firstname', 'user'));
376     }
378     /**
379      * Get the records.
380      *
381      * @return array
382      */
383     public function get_records() {
384         global $DB;
385         return $DB->get_records_sql($this->build_query(), $this->params, $this->limitfrom, $this->limitnum);
386     }
388     /**
389      * Get the recordset.
390      *
391      * @return moodle_recordset
392      */
393     public function get_recordset() {
394         global $DB;
395         return $DB->get_recordset_sql($this->build_query(), $this->params, $this->limitfrom, $this->limitnum);
396     }
398     /**
399      * Retrieve a user object from a record.
400      *
401      * This comes handy when {@link self::add_user_fields} was used.
402      *
403      * @param stdClass $record The record.
404      * @return stdClass A user object.
405      */
406     public static function get_user_from_record($record) {
407         return user_picture::unalias($record, null, 'userdataid', 'userdata');
408     }
410     /**
411      * Join the alias table.
412      *
413      * Note that this may cause the same entry to be returned more than once. You might want
414      * to add a distinct on the entry id. See {@link self::distinct()}.
415      *
416      * @return void
417      */
418     public function join_alias() {
419         $this->joins[] = sprintf('LEFT JOIN {glossary_alias} %s ON %s = %s',
420             self::ALIAS_ALIAS, self::resolve_field('id', 'entries'), self::resolve_field('entryid', 'alias'));
421     }
423     /**
424      * Join on the category tables.
425      *
426      * Depending on the category passed the joins will be different. This is due to the display
427      * logic that assumes that when displaying all categories the non categorised entries should
428      * not be returned, etc...
429      *
430      * @param int $categoryid The category ID, or GLOSSARY_SHOW_* constant.
431      */
432     public function join_category($categoryid) {
434         if ($categoryid === GLOSSARY_SHOW_ALL_CATEGORIES) {
435             $this->joins[] = sprintf('JOIN {glossary_entries_categories} %s ON %s = %s',
436                 self::ALIAS_ENTRIES_CATEGORIES, self::resolve_field('id', 'entries'),
437                 self::resolve_field('entryid', 'entries_categories'));
439             $this->joins[] = sprintf('JOIN {glossary_categories} %s ON %s = %s',
440                 self::ALIAS_CATEGORIES, self::resolve_field('id', 'categories'),
441                 self::resolve_field('categoryid', 'entries_categories'));
443         } else if ($categoryid === GLOSSARY_SHOW_NOT_CATEGORISED) {
444             $this->joins[] = sprintf('LEFT JOIN {glossary_entries_categories} %s ON %s = %s',
445                 self::ALIAS_ENTRIES_CATEGORIES, self::resolve_field('id', 'entries'),
446                 self::resolve_field('entryid', 'entries_categories'));
448         } else {
449             $this->joins[] = sprintf('JOIN {glossary_entries_categories} %s ON %s = %s AND %s = :joincategoryid',
450                 self::ALIAS_ENTRIES_CATEGORIES, self::resolve_field('id', 'entries'),
451                 self::resolve_field('entryid', 'entries_categories'),
452                 self::resolve_field('categoryid', 'entries_categories'));
453             $this->params['joincategoryid'] = $categoryid;
455         }
456     }
458     /**
459      * Join the user table.
460      *
461      * @param bool $strict When strict uses a JOIN rather than a LEFT JOIN.
462      */
463     public function join_user($strict = false) {
464         $join = $strict ? 'JOIN' : 'LEFT JOIN';
465         $this->joins[] = sprintf("$join {user} %s ON %s = %s",
466             self::ALIAS_USER, self::resolve_field('id', 'user'), self::resolve_field('userid', 'entries'));
467     }
469     /**
470      * Limit the number of records to fetch.
471      * @param int $from Fetch from.
472      * @param int $num  Number to fetch.
473      */
474     public function limit($from, $num) {
475         $this->limitfrom = $from;
476         $this->limitnum = $num;
477     }
479     /**
480      * Normalise a direction.
481      *
482      * This ensures that the value is either ASC or DESC.
483      *
484      * @param string $direction The desired direction.
485      * @return string ASC or DESC.
486      */
487     protected function normalize_direction($direction) {
488         $direction = core_text::strtoupper($direction);
489         if ($direction == 'DESC') {
490             return 'DESC';
491         }
492         return 'ASC';
493     }
495     /**
496      * Order by a field.
497      *
498      * @param string $field The field, or *.
499      * @param string $table The table name, without the prefix 'glossary_'.
500      * @param string $direction ASC, or DESC.
501      */
502     public function order_by($field, $table, $direction = '') {
503         $direction = self::normalize_direction($direction);
504         $this->order[] = self::resolve_field($field, $table) . ' ' . $direction;
505     }
507     /**
508      * Order by author name.
509      *
510      * @param bool   $firstnamefirst Whether or not the firstname is first in the author's name.
511      * @param string $direction ASC, or DESC.
512      */
513     public function order_by_author($firstnamefirst = false, $direction = '') {
514         $field = self::get_fullname_field($firstnamefirst);
515         $direction = self::normalize_direction($direction);
516         $this->order[] = $field . ' ' . $direction;
517     }
519     /**
520      * Convenience method to transform a field into SQL statement.
521      *
522      * @param string $field The field, or *.
523      * @param string $table The table name, without the prefix 'glossary_'.
524      * @return string SQL statement.
525      */
526     protected static function resolve_field($field, $table) {
527         $prefix = constant(__CLASS__ . '::ALIAS_' . core_text::strtoupper($table));
528         return sprintf('%s.%s', $prefix, $field);
529     }
531     /**
532      * Simple where conditions.
533      *
534      * @param string $field The field, or *.
535      * @param string $table The table name, without the prefix 'glossary_'.
536      * @param mixed $value The value to be equal to.
537      */
538     public function where($field, $table, $value) {
539         static $i = 0;
540         $sql = self::resolve_field($field, $table) . ' ';
542         if ($value === null) {
543             $sql .= 'IS NULL';
545         } else {
546             $param = 'where' . $i++;
547             $sql .= " = :$param";
548             $this->params[$param] = $value;
549         }
551         $this->where[] = $sql;
552     }