Merge branch 'MDL-62899-search-icons-master' of https://github.com/dmitriim/moodle
[moodle.git] / search / classes / base_block.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  * Search area base class for blocks.
19  *
20  * Note: Only blocks within courses are supported.
21  *
22  * @package core_search
23  * @copyright 2017 The Open University
24  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 namespace core_search;
29 defined('MOODLE_INTERNAL') || die();
31 /**
32  * Search area base class for blocks.
33  *
34  * Note: Only blocks within courses are supported.
35  *
36  * @package core_search
37  * @copyright 2017 The Open University
38  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  */
40 abstract class base_block extends base {
41     /** @var string Cache name used for block instances */
42     const CACHE_INSTANCES = 'base_block_instances';
44     /**
45      * The context levels the search area is working on.
46      *
47      * This can be overwriten by the search area if it works at multiple
48      * levels.
49      *
50      * @var array
51      */
52     protected static $levels = [CONTEXT_BLOCK];
54     /**
55      * Gets the block name only.
56      *
57      * @return string Block name e.g. 'html'
58      */
59     public function get_block_name() {
60         // Remove 'block_' text.
61         return substr($this->get_component_name(), 6);
62     }
64     /**
65      * Returns restrictions on which block_instances rows to return. By default, excludes rows
66      * that have empty configdata.
67      *
68      * If no restriction is required, you could return ['', []].
69      *
70      * @return array 2-element array of SQL restriction and params for it
71      */
72     protected function get_indexing_restrictions() {
73         global $DB;
75         // This includes completely empty configdata, and also three other values that are
76         // equivalent to empty:
77         // - A serialized completely empty object.
78         // - A serialized object with one field called '0' (string not int) set to boolean false
79         //   (this can happen after backup and restore, at least historically).
80         // - A serialized null.
81         $stupidobject = (object)[];
82         $zero = '0';
83         $stupidobject->{$zero} = false;
84         return [$DB->sql_compare_text('bi.configdata') . " != ? AND " .
85                 $DB->sql_compare_text('bi.configdata') . " != ? AND " .
86                 $DB->sql_compare_text('bi.configdata') . " != ? AND " .
87                 $DB->sql_compare_text('bi.configdata') . " != ?",
88                 ['', base64_encode(serialize((object)[])), base64_encode(serialize($stupidobject)),
89                 base64_encode(serialize(null))]];
90     }
92     /**
93      * Gets recordset of all blocks of this type modified since given time within the given context.
94      *
95      * See base class for detailed requirements. This implementation includes the key fields
96      * from block_instances.
97      *
98      * This can be overridden to do something totally different if the block's data is stored in
99      * other tables.
100      *
101      * If there are certain instances of the block which should not be included in the search index
102      * then you can override get_indexing_restrictions; by default this excludes rows with empty
103      * configdata.
104      *
105      * @param int $modifiedfrom Return only records modified after this date
106      * @param \context|null $context Context to find blocks within
107      * @return false|\moodle_recordset|null
108      */
109     public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
110         global $DB;
112         // Get context restrictions.
113         list ($contextjoin, $contextparams) = $this->get_context_restriction_sql($context, 'bi');
115         // Get custom restrictions for block type.
116         list ($restrictions, $restrictionparams) = $this->get_indexing_restrictions();
117         if ($restrictions) {
118             $restrictions = 'AND ' . $restrictions;
119         }
121         // Query for all entries in block_instances for this type of block, within the specified
122         // context. The query is based on the one from get_recordset_by_timestamp and applies the
123         // same restrictions.
124         return $DB->get_recordset_sql("
125                 SELECT bi.id, bi.timemodified, bi.timecreated, bi.configdata,
126                        c.id AS courseid, x.id AS contextid
127                   FROM {block_instances} bi
128                        $contextjoin
129                   JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
130                   JOIN {context} parent ON parent.id = bi.parentcontextid
131              LEFT JOIN {course_modules} cm ON cm.id = parent.instanceid AND parent.contextlevel = ?
132                   JOIN {course} c ON c.id = cm.course
133                        OR (c.id = parent.instanceid AND parent.contextlevel = ?)
134                  WHERE bi.timemodified >= ?
135                        AND bi.blockname = ?
136                        AND (parent.contextlevel = ? AND (" . $DB->sql_like('bi.pagetypepattern', '?') . "
137                            OR bi.pagetypepattern IN ('site-index', 'course-*', '*')))
138                        $restrictions
139               ORDER BY bi.timemodified ASC",
140                 array_merge($contextparams, [CONTEXT_BLOCK, CONTEXT_MODULE, CONTEXT_COURSE,
141                     $modifiedfrom, $this->get_block_name(), CONTEXT_COURSE, 'course-view-%'],
142                 $restrictionparams));
143     }
145     public function get_doc_url(\core_search\document $doc) {
146         // Load block instance and find cmid if there is one.
147         $blockinstanceid = preg_replace('~^.*-~', '', $doc->get('id'));
148         $instance = $this->get_block_instance($blockinstanceid);
149         $courseid = $doc->get('courseid');
150         $anchor = 'inst' . $blockinstanceid;
152         // Check if the block is at course or module level.
153         if ($instance->cmid) {
154             // No module-level page types are supported at present so the search system won't return
155             // them. But let's put some example code here to indicate how it could work.
156             debugging('Unexpected module-level page type for block ' . $blockinstanceid . ': ' .
157                     $instance->pagetypepattern, DEBUG_DEVELOPER);
158             $modinfo = get_fast_modinfo($courseid);
159             $cm = $modinfo->get_cm($instance->cmid);
160             return new \moodle_url($cm->url, null, $anchor);
161         } else {
162             // The block is at course level. Let's check the page type, although in practice we
163             // currently only support the course main page.
164             if ($instance->pagetypepattern === '*' || $instance->pagetypepattern === 'course-*' ||
165                     preg_match('~^course-view-(.*)$~', $instance->pagetypepattern)) {
166                 return new \moodle_url('/course/view.php', ['id' => $courseid], $anchor);
167             } else if ($instance->pagetypepattern === 'site-index') {
168                 return new \moodle_url('/', ['redirect' => 0], $anchor);
169             } else {
170                 debugging('Unexpected page type for block ' . $blockinstanceid . ': ' .
171                         $instance->pagetypepattern, DEBUG_DEVELOPER);
172                 return new \moodle_url('/course/view.php', ['id' => $courseid], $anchor);
173             }
174         }
175     }
177     public function get_context_url(\core_search\document $doc) {
178         return $this->get_doc_url($doc);
179     }
181     /**
182      * Checks access for a document in this search area.
183      *
184      * If you override this function for a block, you should call this base class version first
185      * as it will check that the block is still visible to users in a supported location.
186      *
187      * @param int $id Document id
188      * @return int manager:ACCESS_xx constant
189      */
190     public function check_access($id) {
191         $instance = $this->get_block_instance($id, IGNORE_MISSING);
192         if (!$instance) {
193             // This generally won't happen because if the block has been deleted then we won't have
194             // included its context in the search area list, but just in case.
195             return manager::ACCESS_DELETED;
196         }
198         // Check block has not been moved to an unsupported area since it was indexed. (At the
199         // moment, only blocks within site and course context are supported, also only certain
200         // page types.)
201         if (!$instance->courseid ||
202                 !self::is_supported_page_type_at_course_context($instance->pagetypepattern)) {
203             return manager::ACCESS_DELETED;
204         }
206         // Note we do not need to check if the block was hidden or if the user has access to the
207         // context, because those checks are included in the list of search contexts user can access
208         // that is calculated in manager.php every time they do a query.
209         return manager::ACCESS_GRANTED;
210     }
212     /**
213      * Checks if a page type is supported for blocks when at course (or also site) context. This
214      * function should be consistent with the SQL in get_recordset_by_timestamp.
215      *
216      * @param string $pagetype Page type
217      * @return bool True if supported
218      */
219     protected static function is_supported_page_type_at_course_context($pagetype) {
220         if (in_array($pagetype, ['site-index', 'course-*', '*'])) {
221             return true;
222         }
223         if (preg_match('~^course-view-~', $pagetype)) {
224             return true;
225         }
226         return false;
227     }
229     /**
230      * Gets a block instance with given id.
231      *
232      * Returns the fields id, pagetypepattern, subpagepattern from block_instances and also the
233      * cmid (if parent context is an activity module).
234      *
235      * @param int $id ID of block instance
236      * @param int $strictness MUST_EXIST or IGNORE_MISSING
237      * @return false|mixed Block instance data (may be false if strictness is IGNORE_MISSING)
238      */
239     protected function get_block_instance($id, $strictness = MUST_EXIST) {
240         global $DB;
242         $cache = \cache::make_from_params(\cache_store::MODE_REQUEST, 'core_search',
243                 self::CACHE_INSTANCES, [], ['simplekeys' => true]);
244         $id = (int)$id;
245         $instance = $cache->get($id);
246         if (!$instance) {
247             $instance = $DB->get_record_sql("
248                     SELECT bi.id, bi.pagetypepattern, bi.subpagepattern,
249                            c.id AS courseid, cm.id AS cmid
250                       FROM {block_instances} bi
251                       JOIN {context} parent ON parent.id = bi.parentcontextid
252                  LEFT JOIN {course} c ON c.id = parent.instanceid AND parent.contextlevel = ?
253                  LEFT JOIN {course_modules} cm ON cm.id = parent.instanceid AND parent.contextlevel = ?
254                      WHERE bi.id = ?",
255                     [CONTEXT_COURSE, CONTEXT_MODULE, $id], $strictness);
256             $cache->set($id, $instance);
257         }
258         return $instance;
259     }
261     /**
262      * Clears static cache. This function can be removed (with calls to it in the test script
263      * replaced with cache_helper::purge_all) if MDL-59427 is fixed.
264      */
265     public static function clear_static() {
266         \cache::make_from_params(\cache_store::MODE_REQUEST, 'core_search',
267                 self::CACHE_INSTANCES, [], ['simplekeys' => true])->purge();
268     }
270     /**
271      * Helper function that gets SQL useful for restricting a search query given a passed-in
272      * context.
273      *
274      * The SQL returned will be one or more JOIN statements, surrounded by whitespace, which act
275      * as restrictions on the query based on the rows in the block_instances table.
276      *
277      * We assume the block instances have already been restricted by blockname.
278      *
279      * Returns null if there can be no results for this block within this context.
280      *
281      * If named parameters are used, these will be named gcrs0, gcrs1, etc. The table aliases used
282      * in SQL also all begin with gcrs, to avoid conflicts.
283      *
284      * @param \context|null $context Context to restrict the query
285      * @param string $blocktable Alias of block_instances table
286      * @param int $paramtype Type of SQL parameters to use (default question mark)
287      * @return array Array with SQL and parameters
288      * @throws \coding_exception If called with invalid params
289      */
290     protected function get_context_restriction_sql(\context $context = null, $blocktable = 'bi',
291             $paramtype = SQL_PARAMS_QM) {
292         global $DB;
294         if (!$context) {
295             return ['', []];
296         }
298         switch ($paramtype) {
299             case SQL_PARAMS_QM:
300                 $param1 = '?';
301                 $param2 = '?';
302                 $key1 = 0;
303                 $key2 = 1;
304                 break;
305             case SQL_PARAMS_NAMED:
306                 $param1 = ':gcrs0';
307                 $param2 = ':gcrs1';
308                 $key1 = 'gcrs0';
309                 $key2 = 'gcrs1';
310                 break;
311             default:
312                 throw new \coding_exception('Unexpected $paramtype: ' . $paramtype);
313         }
315         $params = [];
316         switch ($context->contextlevel) {
317             case CONTEXT_SYSTEM:
318                 $sql = '';
319                 break;
321             case CONTEXT_COURSECAT:
322             case CONTEXT_COURSE:
323             case CONTEXT_MODULE:
324             case CONTEXT_USER:
325                 // Find all blocks whose parent is within the specified context.
326                 $sql = " JOIN {context} gcrsx ON gcrsx.id = $blocktable.parentcontextid
327                               AND (gcrsx.id = $param1 OR " . $DB->sql_like('gcrsx.path', $param2) . ") ";
328                 $params[$key1] = $context->id;
329                 $params[$key2] = $context->path . '/%';
330                 break;
332             case CONTEXT_BLOCK:
333                 // Find only the specified block of this type. Since we are generating JOINs
334                 // here, we do this by joining again to the block_instances table with the same ID.
335                 $sql = " JOIN {block_instances} gcrsbi ON gcrsbi.id = $blocktable.id
336                               AND gcrsbi.id = $param1 ";
337                 $params[$key1] = $context->instanceid;
338                 break;
340             default:
341                 throw new \coding_exception('Unexpected contextlevel: ' . $context->contextlevel);
342         }
344         return [$sql, $params];
345     }
347     /**
348      * This can be used in subclasses to change ordering within the get_contexts_to_reindex
349      * function.
350      *
351      * It returns 2 values:
352      * - Extra SQL joins (tables block_instances 'bi' and context 'x' already exist).
353      * - An ORDER BY value which must use aggregate functions, by default 'MAX(bi.timemodified) DESC'.
354      *
355      * Note the query already includes a GROUP BY on the context fields, so if your joins result
356      * in multiple rows, you can use aggregate functions in the ORDER BY. See forum for an example.
357      *
358      * @return string[] Array with 2 elements; extra joins for the query, and ORDER BY value
359      */
360     protected function get_contexts_to_reindex_extra_sql() {
361         return ['', 'MAX(bi.timemodified) DESC'];
362     }
364     /**
365      * Gets a list of all contexts to reindex when reindexing this search area.
366      *
367      * For blocks, the default is to return all contexts for blocks of that type, that are on a
368      * course page, in order of time added (most recent first).
369      *
370      * @return \Iterator Iterator of contexts to reindex
371      * @throws \moodle_exception If any DB error
372      */
373     public function get_contexts_to_reindex() {
374         global $DB;
376         list ($extrajoins, $dborder) = $this->get_contexts_to_reindex_extra_sql();
377         $contexts = [];
378         $selectcolumns = \context_helper::get_preload_record_columns_sql('x');
379         $groupbycolumns = '';
380         foreach (\context_helper::get_preload_record_columns('x') as $column => $thing) {
381             if ($groupbycolumns !== '') {
382                 $groupbycolumns .= ',';
383             }
384             $groupbycolumns .= $column;
385         }
386         $rs = $DB->get_recordset_sql("
387                 SELECT $selectcolumns
388                   FROM {block_instances} bi
389                   JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
390                   JOIN {context} parent ON parent.id = bi.parentcontextid
391                        $extrajoins
392                  WHERE bi.blockname = ? AND parent.contextlevel = ?
393               GROUP BY $groupbycolumns
394               ORDER BY $dborder", [CONTEXT_BLOCK, $this->get_block_name(), CONTEXT_COURSE]);
395         return new \core\dml\recordset_walk($rs, function($rec) {
396             $id = $rec->ctxid;
397             \context_helper::preload_from_record($rec);
398             return \context::instance_by_id($id);
399         });
400     }
402     /**
403      * Returns an icon instance for the document.
404      *
405      * @param \core_search\document $doc
406      * @return \core_search\document_icon
407      */
408     public function get_doc_icon(document $doc) : document_icon {
409         return new document_icon('e/anchor');
410     }