Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
question_engine_data_mapper Class Reference

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.
 
 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.
 
 latest_step_for_qa_subquery ($questionattemptid='qa.id')
 
 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.

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$dba 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$stepdataarray of zero or more arrays.
Return values
arraymade 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$questionidquestion 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$qubaidsidentifies 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$contextidthe context these attempts belong to.
string$itemidstesta bit of SQL that can be used in a WHERE itemid $itemidstest clause. Must use named params.
array$paramsany 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$stepidsarray of step ids to delete.
context$contextthe 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$qubaidsidentifies 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
stringSQL 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$summarystateone of inprogress, needsgrading, manuallygraded or autograded
bool$equalif false, do a NOT IN test. Default true.
string$prefixused in the call to $DB->get_in_or_equal().
Return values
arrayas 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$rowsthe 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$qathe question attempt to store.
context$contextthe context of the owning question_usage_by_activity.
Return values
arrayof 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$qathe question attempt to store meta data for.
array$namesthe names of the metadata variables to store.
Return values
arrayof 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$stepthe step to store.
int$questionattemptidthe question attept id this step belongs to.
int$seqthe sequence number of this stop.
context$contextthe context of the owning question_usage_by_activity.
Return values
arrayof 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$qubathe usage to store.

◆ 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$questionidthe question to load all the attempts fors.
qubaid_condition$qubaidsused 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$qubaidsused to restrict which usages are included in the query. See qubaid_condition.
array | null$slotsif null, load info for all quesitions, otherwise only load the averages for the specified questions.
Return values
arrayof 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$questionattemptidthe id of the question attempt to load.
Return values
question_attemptthe 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$stepidthe id of the step to load.
Return values
question_attempt_stepthe 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$qubaidthe id of the usage to load.
Return values
question_usage_by_activitythe 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$qubaidsthe 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$qubaidsused 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
arrayof 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$qubaidsused 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
arrayThe 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$qubaidsused to restrict which usages are included in the query. See qubaid_condition.
int$slotThe slot for the questions you want to know about.
int$questionid(optional) Only return attempts that were of this specific question.
string$summarystatethe summary state of interest, or 'all'.
string$orderbythe column to order by.
array$paramsany params required by any of the SQL fragments.
int$limitfromimplements paging of the results. Ignored if $orderby = random or $limitnum is null.
int$limitnumimplements paging of the results. null = all.
string$extraselectanything passed here will be added to the SELECT list, use this to return extra data.
Return values
arraywith 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$questionidsof question ids.
qubaid_condition$qubaidsids of the usages to consider.
Return values
arrayquestionid => 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$stepthe step to store.
int$questionattemptidthe question attept id this step belongs to.
int$seqthe sequence number of this stop.
Return values
stdClassdata 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$stepthe step to store.
int$stepidthe id of the step.
context$contextthe context of the owning question_usage_by_activity.
Return values
arrayof 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$aliasalias to use for this inline-view.
qubaid_condition$qubaidsrestriction on which question_usages we are interested in. This is important for performance.
Return values
arraywith 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$questionidsof question ids.
qubaid_condition$qubaidsids of the usages to consider.
Return values
boolwhether 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$qubaidsSelects which usages are updated.
int$slotthe number is usage to affect.
number$newmaxmarkthe 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$qubaidSQL 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
stringSQL 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$qathe 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$qubaidthe question usage id.
int$questionidthe question id.
int$qaidthe question_attempt id.
int$slotthe slot number of the question attempt to update.
bool$newstatethe 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$qathe question attempt to store meta data for.
array$namesthe names of the metadata variables to store.
Return values
arrayof 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$stepthe step to store.
int$questionattemptidthe question attept id this step belongs to.
int$seqthe sequence number of this stop.
context$contextthe context of the owning question_usage_by_activity.
Return values
arrayof 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$qubathe usage that has changed.

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