core_question\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=array())
	Constructor. More...
	count_questions ($categoryid, $includesubcategories, $tagids=[])
	Count the number of available questions for the given criteria. More...
	get_next_question_id ($categoryid, $includesubcategories, $tagids=[])
	Pick a question at random from the given category, from among those with the fewest uses. More...
	get_questions ( $categoryid, $includesubcategories, $tagids=[], $limit=100, $offset=0, $fields=[])
	Get the list of available questions for the given criteria. More...
	is_question_available ($categoryid, $includesubcategories, $questionid, $tagids=[])
	Check whether a given question is available in a given category. More...

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

Protected Attributes
array	$availablequestionscache = array()
	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. More...

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.

Copyright

2015 The Open University

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

__construct()

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

Constructor.

Parameters

qubaid_condition	$qubaids	the usages to consider when counting previous uses of each question.
array	$usedquestions	questionid => 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\bank\random_question_loader::count_questions	(		$categoryid,
			$includesubcategories,
			$tagids = []
	)

Count the number of available questions for the given criteria.

Parameters

int	$categoryid	The id of a category in the question bank.
bool	$includesubcategories	Whether to pick a question from exactly that category, or that category and subcategories.
array	$tagids	An 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 number of questions matching the criteria.

ensure_questions_for_category_loaded()

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

protected

Populate $availablequestionscache for this combination of options.

Parameters

int	$categoryid	The id of a category in the question bank.
bool	$includesubcategories	Whether to pick a question from exactly that category, or that category and subcategories.
array	$tagids	An 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\bank\random_question_loader::get_category_key (   $categoryid,   $includesubcategories,   $tagids = []  )

protected

Get the key into $availablequestionscache for this combination of options.

Parameters

int	$categoryid	the id of a category in the question bank.
bool	$includesubcategories	wether to pick a question from exactly that category, or that category and subcategories.
array	$tagids	an array of tag ids.

Return values

string

the cache key.

get_next_question_id()

core_question\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	$categoryid	the id of a category in the question bank.
bool	$includesubcategories	wether to pick a question from exactly that category, or that category and subcategories.
array	$tagids	An 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|null

the id of the question picked, or null if there aren't any.

get_question_ids()

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

protected

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

Parameters

int	$categoryid	The id of a category in the question bank.
bool	$includesubcategories	Whether to pick a question from exactly that category, or that category and subcategories.
array	$tagids	An 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\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	$categoryid	The id of a category in the question bank.
bool	$includesubcategories	Whether to pick a question from exactly that category, or that category and subcategories.
array	$tagids	An 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	$limit	Maximum number of results to return.
int	$offset	Number of items to skip from the begging of the result set.
string[]	$fields	The fields to return for each question.

Return values

stdClass[]

The list of question records

is_question_available()

core_question\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	$categoryid	the id of a category in the question bank.
bool	$includesubcategories	wether to pick a question from exactly that category, or that category and subcategories.
int	$questionid	the question that is being used.
array	$tagids	An array of tag ids. Only the questions that are tagged with all the provided tagids can be available.

Return values

bool	whether the question is available in the requested category.

use_question()

core_question\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

$questionid

the question that is being used.

Member Data Documentation

$recentlyusedquestions

array core_question\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:

• question/classes/bank/random_question_loader.php