Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
core_question\local\bank\random_question_loader Class Reference

This class efficiently finds questions at random from the question bank. More...

Public Member Functions

 __construct (\qubaid_condition $qubaids, array $usedquestions=[])
 Constructor.
 
 count_questions ($categoryid, $includesubcategories, $tagids=[])
 Count the number of available questions for the given criteria.
 
 get_next_question_id ($categoryid, $includesubcategories, $tagids=[])
 Pick a question at random from the given category, from among those with the fewest uses.
 
 get_questions ($categoryid, $includesubcategories, $tagids=[], $limit=100, $offset=0, $fields=[])
 Get the list of available questions for the given criteria.
 
 is_question_available ($categoryid, $includesubcategories, $questionid, $tagids=[])
 Check whether a given question is available in a given category.
 

Protected Member Functions

 ensure_questions_for_category_loaded ($categoryid, $includesubcategories, $tagids=[])
 Populate {.
 
 get_category_key ($categoryid, $includesubcategories, $tagids=[])
 Get the key into {.
 
 get_question_ids ($categoryid, $includesubcategories, $tagids=[])
 Get the list of available question ids for the given criteria.
 
 use_question ($questionid)
 Update the internal data structures to indicate that a given question has been used one more time.
 

Protected Attributes

array $availablequestionscache = []
 categoryid & include subcategories => num previous uses => questionid => 1.
 
array $excludedqtypes
 qtypes that cannot be used by random questions.
 
qubaid_condition $qubaids
 which usages to consider previous attempts from.
 
array $recentlyusedquestions
 questionid => num recent uses.
 

Detailed Description

This class efficiently finds questions at random from the question bank.

You can ask for questions at random one at a time. Each time you ask, you pass a category id, and whether to pick from that category and all subcategories or just that category.

The number of teams each question has been used is tracked, and we will always return a question from among those elegible that has been used the fewest times. So, if there are questions that have not been used yet in the category asked for, one of those will be returned. However, within one instantiation of this class, we will never return a given question more than once, and we will never return questions passed into the constructor as $usedquestions.

Author
2021 Safat Shahin safat.nosp@m.shah.nosp@m.in@ca.nosp@m.taly.nosp@m.st-au.nosp@m..net
License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

core_question\local\bank\random_question_loader::__construct ( \qubaid_condition $qubaids,
array $usedquestions = [] )

Constructor.

Parameters
qubaid_condition$qubaidsthe usages to consider when counting previous uses of each question.
array$usedquestionsquestionid => number of times used count. If we should allow for further existing uses of a question in addition to the ones in $qubaids.

Member Function Documentation

◆ count_questions()

core_question\local\bank\random_question_loader::count_questions ( $categoryid,
$includesubcategories,
$tagids = [] )

Count the number of available questions for the given criteria.

Parameters
int$categoryidThe id of a category in the question bank.
bool$includesubcategoriesWhether to pick a question from exactly that category, or that category and subcategories.
array$tagidsAn array of tag ids. If an array is provided, then only the questions that are tagged with ALL the provided tagids will be loaded.
Return values
intThe number of questions matching the criteria.

◆ ensure_questions_for_category_loaded()

core_question\local\bank\random_question_loader::ensure_questions_for_category_loaded ( $categoryid,
$includesubcategories,
$tagids = [] )
protected

Populate {.

See also
$availablequestionscache} for this combination of options.
Parameters
int$categoryidThe id of a category in the question bank.
bool$includesubcategoriesWhether to pick a question from exactly that category, or that category and subcategories.
array$tagidsAn array of tag ids. If an array is provided, then only the questions that are tagged with ALL the provided tagids will be loaded.

◆ get_category_key()

core_question\local\bank\random_question_loader::get_category_key ( $categoryid,
$includesubcategories,
$tagids = [] )
protected

Get the key into {.

See also
$availablequestionscache} for this combination of options.
Parameters
int$categoryidthe id of a category in the question bank.
bool$includesubcategorieswether to pick a question from exactly that category, or that category and subcategories.
array$tagidsan array of tag ids.
Return values
stringthe cache key.

◆ get_next_question_id()

core_question\local\bank\random_question_loader::get_next_question_id ( $categoryid,
$includesubcategories,
$tagids = [] )

Pick a question at random from the given category, from among those with the fewest uses.

If an array of tag ids are specified, then only the questions that are tagged with ALL those tags will be selected.

It is up the the caller to verify that the cateogry exists. An unknown category behaves like an empty one.

Parameters
int$categoryidthe id of a category in the question bank.
bool$includesubcategorieswether to pick a question from exactly that category, or that category and subcategories.
array$tagidsAn array of tag ids. A question has to be tagged with all the provided tagids (if any) in order to be eligible for being picked.
Return values
int|nullthe id of the question picked, or null if there aren't any.

◆ get_question_ids()

core_question\local\bank\random_question_loader::get_question_ids ( $categoryid,
$includesubcategories,
$tagids = [] )
protected

Get the list of available question ids for the given criteria.

Parameters
int$categoryidThe id of a category in the question bank.
bool$includesubcategoriesWhether to pick a question from exactly that category, or that category and subcategories.
array$tagidsAn array of tag ids. If an array is provided, then only the questions that are tagged with ALL the provided tagids will be loaded.
Return values
int[]The list of question ids

◆ get_questions()

core_question\local\bank\random_question_loader::get_questions ( $categoryid,
$includesubcategories,
$tagids = [],
$limit = 100,
$offset = 0,
$fields = [] )

Get the list of available questions for the given criteria.

Parameters
int$categoryidThe id of a category in the question bank.
bool$includesubcategoriesWhether to pick a question from exactly that category, or that category and subcategories.
array$tagidsAn array of tag ids. If an array is provided, then only the questions that are tagged with ALL the provided tagids will be loaded.
int$limitMaximum number of results to return.
int$offsetNumber of items to skip from the begging of the result set.
string[]$fieldsThe fields to return for each question.
Return values
stdClass[]The list of question records

◆ is_question_available()

core_question\local\bank\random_question_loader::is_question_available ( $categoryid,
$includesubcategories,
$questionid,
$tagids = [] )

Check whether a given question is available in a given category.

If so, mark it used. If an optional list of tag ids are provided, then the question must be tagged with ALL of the provided tags to be considered as available.

Parameters
int$categoryidthe id of a category in the question bank.
bool$includesubcategorieswether to pick a question from exactly that category, or that category and subcategories.
int$questionidthe question that is being used.
array$tagidsAn array of tag ids. Only the questions that are tagged with all the provided tagids can be available.
Return values
boolwhether the question is available in the requested category.

◆ use_question()

core_question\local\bank\random_question_loader::use_question ( $questionid)
protected

Update the internal data structures to indicate that a given question has been used one more time.

Parameters
int$questionidthe question that is being used.

Member Data Documentation

◆ $recentlyusedquestions

array core_question\local\bank\random_question_loader::$recentlyusedquestions
protected

questionid => num recent uses.

Questions that have been used, but that is not yet recorded in the DB.


The documentation for this class was generated from the following file: