Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Class core_tag_index_builder

Copyright: 2016 Marina Glancy
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 373 lines (14 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

core_tag_index_builder:: (14 methods):
  __construct()
  prepare_sql_courses()
  prepare_sql_items()
  retrieve_items()
  get_items()
  has_item_that_needs_access_check()
  walk()
  set_accessible()
  get_course()
  init_course_access()
  init_items_access()
  can_access_course()
  save_caches()
  reset_caches()


Class: core_tag_index_builder  - X-Ref

Helper to build tag index

This can be used by components to implement tag area callbacks. This is especially
useful for in-course content when we need to check and cache user's access to
multiple courses. Course access and accessible items are stored in session cache
with 15 minutes expiry time.

Example of usage:

$builder = new core_tag_index_builder($component, $itemtype, $sql, $params, $from, $limit);
while ($item = $builder->has_item_that_needs_access_check()) {
if (!$builder->can_access_course($item->courseid)) {
$builder->set_accessible($item, false);
} else {
$accessible = true; // Check access and set $accessible respectively.
$builder->set_accessible($item, $accessible);
}
}
$items = $builder->get_items();

__construct($component, $itemtype, $sql, $params, $from, $limit)   X-Ref
Constructor.

Specify the SQL query for retrieving the tagged items, SQL query must:
- return the item id as the first field and make sure that it is unique in the result
- provide ORDER BY that exclude any possibility of random results, if $fromctx was specified when searching
for tagged items it is the best practice to make sure that items from this context are returned first.

This query may also contain placeholders %COURSEFILTER% or %ITEMFILTER% that will be substituted with
expressions excluding courses and/or filters that are already known as inaccessible.

Example: "WHERE c.id %COURSEFILTER% AND cm.id %ITEMFILTER%"

This query may contain fields to preload context if context is needed for formatting values.

It is recommended to sort by course sortorder first, this way the items from the same course will be next to
each other and the sequence of courses will the same in different tag areas.

param: string $component component responsible for tagging
param: string $itemtype type of item that is being tagged
param: string $sql SQL query that would retrieve all relevant items without permission check
param: array $params parameters for the query (must be named)
param: int $from return a subset of records, starting at this point
param: int $limit return a subset comprising this many records in total (this field is NOT optional)

prepare_sql_courses()   X-Ref
Substitute %COURSEFILTER% with an expression filtering out courses where current user does not have access


prepare_sql_items()   X-Ref
Substitute %ITEMFILTER% with an expression filtering out items where current user does not have access


retrieve_items()   X-Ref
Ensures that SQL query was executed and $this->items is filled


get_items()   X-Ref
Returns the filtered records from SQL query result.

This function can only be executed after $builder->has_item_that_needs_access_check() returns null


return: array

has_item_that_needs_access_check()   X-Ref
Returns the first row from the SQL result that we don't know whether it is accessible by user or not.

This will return null when we have necessary number of accessible items to return in {@link get_items()}

After analyzing you may decide to mark not only this record but all similar as accessible or not accessible.
For example, if you already call get_fast_modinfo() to check this item's accessibility, why not mark all
items in the same course as accessible or not accessible.

Helpful methods: {@link set_accessible()} and {@link walk()}

return: null|object

walk($callable)   X-Ref
Walk through the array of items and call $callable for each of them

param: callable $callable

set_accessible($identifier, $accessible = true)   X-Ref
Marks record or group of records as accessible (or not accessible)

param: int|std_Class $identifier either record id of the item that needs to be set accessible
param: bool $accessible whether to mark as accessible or not accessible (default true)

get_course($courseid)   X-Ref
Retrieves a course record (only fields id,visible,fullname,shortname,cacherev).

This method is useful because it also caches results and preloads course context.

param: int $courseid

init_course_access()   X-Ref
Ensures that we read the course access from the cache.


init_items_access()   X-Ref
Ensures that we read the items access from the cache.


can_access_course($courseid)   X-Ref
Checks if current user has access to the course

This method calls global function {@link can_access_course} and caches results

param: int $courseid
return: bool

save_caches()   X-Ref
Saves course/items caches if needed


reset_caches()   X-Ref
Resets all course/items session caches - useful in unittests when we change users and enrolments.