This class controls the loading and saving of question engine data to and from the database. More...

Public Member Functions
	__construct (moodle_database $db=null)

	combine_step_data (array $stepdata)
	Take an array of arrays, and flatten it, even if the outer array is empty.

	delete_previews ($questionid)
	Delete all the previews for a given question.

	delete_questions_usage_by_activities (qubaid_condition $qubaids)
	Delete a question_usage_by_activity and all its associated.

	delete_steps ($stepids, $context)
	Delete some steps of a question attempt.

	in_summary_state_test ($summarystate, $equal=true, $prefix='summarystates')
	Get the SQL needed to test that question_attempt_steps.state is in a state corresponding to $summarystate.

	insert_all_step_data (array $rows)
	Insert a lot of records into question_attempt_step_data in one go.

	insert_question_attempt (question_attempt $qa, $context)
	Store an entire question_attempt in the database, including all the question_attempt_steps that comprise it.

	insert_question_attempt_metadata (question_attempt $qa, array $names)
	Store new metadata for an existing question_attempt in the database.

	insert_question_attempt_step (question_attempt_step $step, $questionattemptid, $seq, $context)
	Store a question_attempt_step in the database.

	insert_questions_usage_by_activity (question_usage_by_activity $quba)
	Store an entire question_usage_by_activity in the database, including all the question_attempts that comprise it.

	latest_step_for_qa_subquery ($questionattemptid='qa.id')
	Get the subquery which selects the latest step for each question_attempt.

	load_attempts_at_question ($questionid, qubaid_condition $qubaids)
	Load all the attempts at a given queston from a set of question_usages.

	load_average_marks (qubaid_condition $qubaids, $slots=null)
	Load the average mark, and number of attempts, for each slot in a set of question usages.

	load_question_attempt ($questionattemptid)
	Load a question_attempt from the database, including all its steps.

	load_question_attempt_step ($stepid)
	Load a question_attempt_step from the database.

	load_questions_usage_by_activity ($qubaid)
	Load a question_usage_by_activity from the database, including all its and all their steps.

	load_questions_usages_by_activity ($qubaids)
	Load all question_usage_by_activity from the database for one qubaid_condition Include all its and all their steps.

	load_questions_usages_latest_steps (qubaid_condition $qubaids, $slots=null, $fields=null)
	Load information about the latest state of each question from the database.

	load_questions_usages_question_state_summary (qubaid_condition $qubaids, $slots=null)
	Load summary information about the state of each question in a group of attempts.

	load_questions_usages_where_question_in_state (qubaid_condition $qubaids, $summarystate, $slot, $questionid=null, $orderby='random', $params=array(), $limitfrom=0, $limitnum=null, $extraselect='')
	Get a list of usage ids where the question with slot $slot, and optionally also with question id $questionid, is in summary state $summarystate.

	load_used_variants (array $questionids, qubaid_condition $qubaids)
	Get the number of times each variant has been used for each question in a list in a set of usages.

	question_attempt_latest_state_view ($alias, qubaid_condition $qubaids)
	Get a subquery that returns the latest step of every qa in some qubas.

	questions_in_use (array $questionids, qubaid_condition $qubaids)
	Are any of these questions are currently in use?

	set_max_mark_in_attempts (qubaid_condition $qubaids, $slot, $newmaxmark)
	Change the maxmark for the question_attempt with number in usage $slot for all the specified question_attempts.

	sum_usage_marks_subquery ($qubaid)
	Return a sub-query that computes the sum of the marks for all the questions in a usage.

	update_question_attempt (question_attempt $qa)
	Update a question_attempts row to refect any changes in a question_attempt (but not any of its steps).

	update_question_attempt_flag ($qubaid, $questionid, $qaid, $slot, $newstate)
	Update the flagged state of a question in the database.

	update_question_attempt_metadata (question_attempt $qa, array $names)
	Updates existing metadata for an existing question_attempt in the database.

	update_question_attempt_step (question_attempt_step $step, $questionattemptid, $seq, $context)
	Update a question_attempt_step in the database.

	update_questions_usage_by_activity (question_usage_by_activity $quba)
	Update a question_usages row to refect any changes in a usage (but not any of its question_attempts.

Protected Member Functions
	delete_response_files ($contextid, $itemidstest, $params)
	Delete all the files belonging to the response variables in the gives question attempt steps.

	delete_usage_records_for_mysql (qubaid_condition $qubaids)
	This function is a work-around for poor MySQL performance with DELETE FROM x WHERE id IN (SELECT ...).

	full_states_to_summary_state_sql ()
	Get all the WHEN 'x' THEN 'y' terms needed to convert the question_attempt_steps.state column to a summary state.

	make_step_record (question_attempt_step $step, $questionattemptid, $seq)
	Helper method used by insert_question_attempt_step and update_question_attempt_step.

	prepare_step_data (question_attempt_step $step, $stepid, $context)
	Helper method used by insert_question_attempt_step and update_question_attempt_step.

Protected Attributes
moodle_database	$db
	normally points to global $DB, but I prefer not to use globals if I can help it.

Detailed Description

This class controls the loading and saving of question engine data to and from the database.

Copyright: 2009 The Open University

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

Constructor & Destructor Documentation

◆ __construct()

question_engine_data_mapper::__construct ( moodle_database $db = null )

Parameters

moodle_database $db a database connectoin. Defaults to global $DB.

Member Function Documentation

◆ combine_step_data()

question_engine_data_mapper::combine_step_data ( array $stepdata )

Take an array of arrays, and flatten it, even if the outer array is empty.

Only public so it can be called from the unit of work. Not part of the public API of this class.

Parameters

array $stepdata array of zero or more arrays.

Return values

array made by concatenating all the separate arrays.

◆ delete_previews()

question_engine_data_mapper::delete_previews ( $questionid )

Delete all the previews for a given question.

Private method, only for use by other parts of the question engine.

Parameters

int $questionid question id.

◆ delete_questions_usage_by_activities()

question_engine_data_mapper::delete_questions_usage_by_activities ( qubaid_condition $qubaids )

Delete a question_usage_by_activity and all its associated.

You should not call this method directly. You should use @externalurl question_engine\delete_questions_usage_by_activities()}.

question_attempts and question_attempt_steps from the database.

Parameters

qubaid_condition $qubaids identifies which question useages to delete.

◆ delete_response_files()

question_engine_data_mapper::delete_response_files	(	$contextid,
		$itemidstest,
		$params )

protected

Delete all the files belonging to the response variables in the gives question attempt steps.

Parameters

int	$contextid	the context these attempts belong to.
string	$itemidstest	a bit of SQL that can be used in a WHERE itemid $itemidstest clause. Must use named params.
array	$params	any query parameters used in $itemidstest.

◆ delete_steps()

question_engine_data_mapper::delete_steps	(		$stepids,
			$context )

Delete some steps of a question attempt.

Private method, only for use by other parts of the question engine.

Parameters

array	$stepids	array of step ids to delete.
context	$context	the context that the $quba belongs to.

◆ delete_usage_records_for_mysql()

question_engine_data_mapper::delete_usage_records_for_mysql ( qubaid_condition $qubaids )

protected

This function is a work-around for poor MySQL performance with DELETE FROM x WHERE id IN (SELECT ...).

We have to use a non-standard syntax to get good performance. See MDL-29520.

Parameters

qubaid_condition $qubaids identifies which question useages to delete.

◆ full_states_to_summary_state_sql()

question_engine_data_mapper::full_states_to_summary_state_sql ( )

protected

Get all the WHEN 'x' THEN 'y' terms needed to convert the question_attempt_steps.state column to a summary state.

Use this like CASE qas.state {$this->full_states_to_summary_state_sql()} END AS summarystate,

Return values

string SQL fragment.

◆ in_summary_state_test()

question_engine_data_mapper::in_summary_state_test	(	$summarystate,
		$equal = true,
		$prefix = 'summarystates' )

Get the SQL needed to test that question_attempt_steps.state is in a state corresponding to $summarystate.

This method may be called publicly.

Parameters

string	$summarystate	one of inprogress, needsgrading, manuallygraded or autograded
bool	$equal	if false, do a NOT IN test. Default true.
string	$prefix	used in the call to $DB->get_in_or_equal().

Return values

array as returned by $DB->get_in_or_equal().

◆ insert_all_step_data()

question_engine_data_mapper::insert_all_step_data ( array $rows )

Insert a lot of records into question_attempt_step_data in one go.

Private method, only for use by other parts of the question engine.

Parameters

array $rows the rows to insert.

◆ insert_question_attempt()

question_engine_data_mapper::insert_question_attempt	(	question_attempt	$qa,
			$context )

Store an entire question_attempt in the database, including all the question_attempt_steps that comprise it.

You should not call this method directly. You should use @externalurl question_engine\save_questions_usage_by_activity()}.

Parameters

question_attempt	$qa	the question attempt to store.
context	$context	the context of the owning question_usage_by_activity.

Return values

array of question_attempt_step_data rows, that still need to be inserted.

◆ insert_question_attempt_metadata()

question_engine_data_mapper::insert_question_attempt_metadata	(	question_attempt	$qa,
		array	$names )

Store new metadata for an existing question_attempt in the database.

Private method, only for use by other parts of the question engine.

Parameters

question_attempt	$qa	the question attempt to store meta data for.
array	$names	the names of the metadata variables to store.

Return values

array of question_attempt_step_data rows, that still need to be inserted.

◆ insert_question_attempt_step()

question_engine_data_mapper::insert_question_attempt_step	(	question_attempt_step	$step,
			$questionattemptid,
			$seq,
			$context )

Store a question_attempt_step in the database.

Private method, only for use by other parts of the question engine.

Parameters

question_attempt_step	$step	the step to store.
int	$questionattemptid	the question attept id this step belongs to.
int	$seq	the sequence number of this stop.
context	$context	the context of the owning question_usage_by_activity.

Return values

array of question_attempt_step_data rows, that still need to be inserted.

◆ insert_questions_usage_by_activity()

question_engine_data_mapper::insert_questions_usage_by_activity ( question_usage_by_activity $quba )

Store an entire question_usage_by_activity in the database, including all the question_attempts that comprise it.

You should not call this method directly. You should use @externalurl question_engine\save_questions_usage_by_activity()}.

Parameters

question_usage_by_activity $quba the usage to store.

◆ latest_step_for_qa_subquery()

question_engine_data_mapper::latest_step_for_qa_subquery ( $questionattemptid = 'qa.id' )

Get the subquery which selects the latest step for each question_attempt.

Parameters

string $questionattemptid column alias for the column to join on which is question_attempt.id.

Return values

string SQL fragment to include in the query. Has not placeholders.

◆ load_attempts_at_question()

question_engine_data_mapper::load_attempts_at_question	(		$questionid,
		qubaid_condition	$qubaids )

Load all the attempts at a given queston from a set of question_usages.

steps.

This method may be called publicly.

Parameters

int	$questionid	the question to load all the attempts fors.
qubaid_condition	$qubaids	used to restrict which usages are included in the query. See qubaid_condition.

Return values

question_attempt[] array of question_attempts that were loaded.

◆ load_average_marks()

question_engine_data_mapper::load_average_marks	(	qubaid_condition	$qubaids,
			$slots = null )

Load the average mark, and number of attempts, for each slot in a set of question usages.

This method may be called publicly.

Parameters

qubaid_condition	$qubaids	used to restrict which usages are included in the query. See qubaid_condition.
array \| null	$slots	if null, load info for all quesitions, otherwise only load the averages for the specified questions.

Return values

array of objects with fields ->slot, ->averagefraction and ->numaveraged.

◆ load_question_attempt()

question_engine_data_mapper::load_question_attempt ( $questionattemptid )

Load a question_attempt from the database, including all its steps.

Normally, you should use question_engine::load_questions_usage_by_activity() but there may be rare occasions where for performance reasons, you only wish to load one qa, in which case you may call this method.

Parameters

int $questionattemptid the id of the question attempt to load.

Return values

question_attempt the question attempt that was loaded.

◆ load_question_attempt_step()

question_engine_data_mapper::load_question_attempt_step ( $stepid )

Load a question_attempt_step from the database.

Private method, only for use by other parts of the question engine.

Parameters

int $stepid the id of the step to load.

Return values

question_attempt_step the step that was loaded.

◆ load_questions_usage_by_activity()

question_engine_data_mapper::load_questions_usage_by_activity ( $qubaid )

Load a question_usage_by_activity from the database, including all its and all their steps.

You should call question_engine::load_questions_usage_by_activity() rather than calling this method directly.

Parameters

int $qubaid the id of the usage to load.

Return values

question_usage_by_activity the usage that was loaded.

◆ load_questions_usages_by_activity()

question_engine_data_mapper::load_questions_usages_by_activity ( $qubaids )

Load all question_usage_by_activity from the database for one qubaid_condition Include all its and all their steps.

This method may be called publicly.

Parameters

qubaid_condition $qubaids the condition that tells us which usages to load.

Return values

question_usage_by_activity[] the usages that were loaded.

◆ load_questions_usages_latest_steps()

question_engine_data_mapper::load_questions_usages_latest_steps	(	qubaid_condition	$qubaids,
			$slots = null,
			$fields = null )

Load information about the latest state of each question from the database.

This method may be called publicly.

Parameters

qubaid_condition	$qubaids	used to restrict which usages are included in the query. See qubaid_condition.
array \| null	$slots	(optional) list of slots for which to return information. Default all slots.
string \| null	$fields

Return values

array of records. See the SQL in this function to see the fields available.

◆ load_questions_usages_question_state_summary()

question_engine_data_mapper::load_questions_usages_question_state_summary	(	qubaid_condition	$qubaids,
			$slots = null )

Load summary information about the state of each question in a group of attempts.

This is used, for example, by the quiz manual grading report, to show how many attempts at each question need to be graded.

This method may be called publicly.

Parameters

qubaid_condition	$qubaids	used to restrict which usages are included in the query. See qubaid_condition.
array \| null	$slots	(optional) list of slots for which to return information. Default all slots.

Return values

array The array keys are 'slot,questionid'. The values are objects with fields $slot, $questionid, $inprogress, $name, $needsgrading, $autograded, $manuallygraded and $all.

◆ load_questions_usages_where_question_in_state()

question_engine_data_mapper::load_questions_usages_where_question_in_state	(	qubaid_condition	$qubaids,
			$summarystate,
			$slot,
			$questionid = null,
			$orderby = 'random',
			$params = array(),
			$limitfrom = 0,
			$limitnum = null,
			$extraselect = '' )

Get a list of usage ids where the question with slot $slot, and optionally also with question id $questionid, is in summary state $summarystate.

Also return the total count of such states.

Only a subset of the ids can be returned by using $orderby, $limitfrom and $limitnum. A special value 'random' can be passed as $orderby, in which case $limitfrom is ignored.

This method may be called publicly.

Parameters

qubaid_condition	$qubaids	used to restrict which usages are included in the query. See qubaid_condition.
int	$slot	The slot for the questions you want to know about.
int	$questionid	(optional) Only return attempts that were of this specific question.
string	$summarystate	the summary state of interest, or 'all'.
string	$orderby	the column to order by.
array	$params	any params required by any of the SQL fragments.
int	$limitfrom	implements paging of the results. Ignored if $orderby = random or $limitnum is null.
int	$limitnum	implements paging of the results. null = all.
string	$extraselect	anything passed here will be added to the SELECT list, use this to return extra data.

Return values

array with two elements, an array of usage ids, and a count of the total number.

◆ load_used_variants()

question_engine_data_mapper::load_used_variants	(	array	$questionids,
		qubaid_condition	$qubaids )

Get the number of times each variant has been used for each question in a list in a set of usages.

Parameters

array	$questionids	of question ids.
qubaid_condition	$qubaids	ids of the usages to consider.

Return values

array questionid => variant number => num uses.

◆ make_step_record()

question_engine_data_mapper::make_step_record	(	question_attempt_step	$step,
			$questionattemptid,
			$seq )

protected

Helper method used by insert_question_attempt_step and update_question_attempt_step.

Parameters

question_attempt_step	$step	the step to store.
int	$questionattemptid	the question attept id this step belongs to.
int	$seq	the sequence number of this stop.

Return values

stdClass data to insert into the database.

◆ prepare_step_data()

question_engine_data_mapper::prepare_step_data	(	question_attempt_step	$step,
			$stepid,
			$context )

protected

Helper method used by insert_question_attempt_step and update_question_attempt_step.

Parameters

question_attempt_step	$step	the step to store.
int	$stepid	the id of the step.
context	$context	the context of the owning question_usage_by_activity.

Return values

array of question_attempt_step_data rows, that still need to be inserted.

◆ question_attempt_latest_state_view()

question_engine_data_mapper::question_attempt_latest_state_view	(		$alias,
		qubaid_condition	$qubaids )

Get a subquery that returns the latest step of every qa in some qubas.

Currently, this is only used by the quiz reports. See {

See also: mod_quiz\local\reports\attempts_report_table\add_latest_state_join()}.

This method may be called publicly.

Parameters

string	$alias	alias to use for this inline-view.
qubaid_condition	$qubaids	restriction on which question_usages we are interested in. This is important for performance.

Return values

array with two elements, the SQL fragment and any params requried.

◆ questions_in_use()

question_engine_data_mapper::questions_in_use	(	array	$questionids,
		qubaid_condition	$qubaids )

Are any of these questions are currently in use?

You should call question_engine::questions_in_use() rather than calling this method directly.

Parameters

array	$questionids	of question ids.
qubaid_condition	$qubaids	ids of the usages to consider.

Return values

bool	whether any of these questions are being used by any of those usages.

◆ set_max_mark_in_attempts()

question_engine_data_mapper::set_max_mark_in_attempts	(	qubaid_condition	$qubaids,
			$slot,
			$newmaxmark )

Change the maxmark for the question_attempt with number in usage $slot for all the specified question_attempts.

You should call question_engine::set_max_mark_in_attempts() rather than calling this method directly.

Parameters

qubaid_condition	$qubaids	Selects which usages are updated.
int	$slot	the number is usage to affect.
number	$newmaxmark	the new max mark to set.

◆ sum_usage_marks_subquery()

question_engine_data_mapper::sum_usage_marks_subquery ( $qubaid )

Return a sub-query that computes the sum of the marks for all the questions in a usage.

Which usage to compute the sum for is controlled by the $qubaid parameter.

See {

See also: mod_quiz\grade_calculator\recompute_all_attempt_sumgrades()} for an example of the usage of this method.

This method may be called publicly.

Parameters

string $qubaid SQL fragment that controls which usage is summed. This will normally be the name of a column in the outer query. Not that this SQL fragment must not contain any placeholders.

Return values

string SQL code for the subquery.

◆ update_question_attempt()

question_engine_data_mapper::update_question_attempt ( question_attempt $qa )

Update a question_attempts row to refect any changes in a question_attempt (but not any of its steps).

You should not call this method directly. You should use @externalurl question_engine\save_questions_usage_by_activity()}.

Parameters

question_attempt $qa the question attempt that has changed.

◆ update_question_attempt_flag()

question_engine_data_mapper::update_question_attempt_flag	(	$qubaid,
		$questionid,
		$qaid,
		$slot,
		$newstate )

Update the flagged state of a question in the database.

You should call question_engine::update_flag()() rather than calling this method directly.

Parameters

int	$qubaid	the question usage id.
int	$questionid	the question id.
int	$qaid	the question_attempt id.
int	$slot	the slot number of the question attempt to update.
bool	$newstate	the new state of the flag. true = flagged.

◆ update_question_attempt_metadata()

question_engine_data_mapper::update_question_attempt_metadata	(	question_attempt	$qa,
		array	$names )

Updates existing metadata for an existing question_attempt in the database.

Private method, only for use by other parts of the question engine.

Parameters

question_attempt	$qa	the question attempt to store meta data for.
array	$names	the names of the metadata variables to store.

Return values

array of question_attempt_step_data rows, that still need to be inserted.

◆ update_question_attempt_step()

question_engine_data_mapper::update_question_attempt_step	(	question_attempt_step	$step,
			$questionattemptid,
			$seq,
			$context )

Update a question_attempt_step in the database.

Private method, only for use by other parts of the question engine.

Parameters

question_attempt_step	$step	the step to store.
int	$questionattemptid	the question attept id this step belongs to.
int	$seq	the sequence number of this stop.
context	$context	the context of the owning question_usage_by_activity.

Return values

array of question_attempt_step_data rows, that still need to be inserted.

◆ update_questions_usage_by_activity()

question_engine_data_mapper::update_questions_usage_by_activity ( question_usage_by_activity $quba )

Update a question_usages row to refect any changes in a usage (but not any of its question_attempts.

You should not call this method directly. You should use @externalurl question_engine\save_questions_usage_by_activity()}.

Parameters

question_usage_by_activity $quba the usage that has changed.

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

question/engine/datalib.php

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ combine_step_data()

◆ delete_previews()

◆ delete_questions_usage_by_activities()

◆ delete_response_files()

◆ delete_steps()

◆ delete_usage_records_for_mysql()

◆ full_states_to_summary_state_sql()

◆ in_summary_state_test()

◆ insert_all_step_data()

◆ insert_question_attempt()

◆ insert_question_attempt_metadata()

◆ insert_question_attempt_step()

◆ insert_questions_usage_by_activity()

◆ latest_step_for_qa_subquery()

◆ load_attempts_at_question()

◆ load_average_marks()

◆ load_question_attempt()

◆ load_question_attempt_step()

◆ load_questions_usage_by_activity()

◆ load_questions_usages_by_activity()

◆ load_questions_usages_latest_steps()

◆ load_questions_usages_question_state_summary()

◆ load_questions_usages_where_question_in_state()

◆ load_used_variants()

◆ make_step_record()

◆ prepare_step_data()

◆ question_attempt_latest_state_view()

◆ questions_in_use()

◆ set_max_mark_in_attempts()

◆ sum_usage_marks_subquery()

◆ update_question_attempt()

◆ update_question_attempt_flag()

◆ update_question_attempt_metadata()

◆ update_question_attempt_step()

◆ update_questions_usage_by_activity()