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.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401]

This file defines the question usage class, and a few related classes.

Copyright: 2009 The Open University
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1239 lines (51 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 4 classes

question_usage_by_activity:: (65 methods):
  __construct()
  set_preferred_behaviour()
  get_preferred_behaviour()
  get_owning_context()
  get_owning_component()
  get_id()
  set_id_from_database()
  get_observer()
  set_observer()
  add_question()
  add_question_in_place_of_other()
  next_slot_number()
  get_question()
  get_slots()
  get_first_question_number()
  question_count()
  get_attempt_iterator()
  check_slot()
  get_question_attempt()
  get_question_state()
  get_question_state_string()
  get_question_state_class()
  can_question_finish_during_attempt()
  get_question_action_time()
  get_question_fraction()
  get_question_mark()
  get_question_max_mark()
  get_total_mark()
  get_summary_information()
  get_question_summary()
  get_response_summary()
  get_right_answer_summary()
  get_question_attempt_metadata()
  set_question_attempt_metadata()
  render_question()
  render_question_head_html()
  render_question_at_step()
  check_file_access()
  replace_loaded_question_attempt_info()
  get_field_prefix()
  get_num_variants()
  get_variant()
  start_question()
  start_all_questions()
  start_question_based_on()
  process_all_actions()
  process_all_autosaves()
  get_slots_in_request()
  extract_responses()
  prepare_simulated_post_data()
  process_action()
  process_autosave()
  validate_sequence_number()
  is_autosave_required()
  update_question_flags()
  get_correct_response()
  finish_question()
  finish_all_questions()
  manual_grade()
  validate_can_regrade_with_other_version()
  regrade_question()
  regrade_all_questions()
  set_max_mark()
  load_from_records()
  preload_all_step_users()

question_attempt_iterator:: (10 methods):
  __construct()
  current()
  key()
  next()
  rewind()
  valid()
  offsetExists()
  offsetGet()
  offsetSet()
  offsetUnset()

question_usage_observer:: (9 methods):
  notify_modified()
  notify_attempt_added()
  notify_attempt_modified()
  notify_attempt_moved()
  notify_step_added()
  notify_step_modified()
  notify_step_deleted()
  notify_metadata_added()
  notify_metadata_modified()

question_usage_null_observer:: (9 methods):
  notify_modified()
  notify_attempt_added()
  notify_attempt_modified()
  notify_attempt_moved()
  notify_step_added()
  notify_step_modified()
  notify_step_deleted()
  notify_metadata_added()
  notify_metadata_modified()


Class: question_usage_by_activity  - X-Ref

This class keeps track of a group of questions that are being attempted,
and which state, and so on, each one is currently in.

A quiz attempt or a lesson attempt could use an instance of this class to
keep track of all the questions in the attempt and process student submissions.
It is basically a collection of {@question_attempt} objects.

The questions being attempted as part of this usage are identified by an integer
that is passed into many of the methods as $slot. ($question->id is not
used so that the same question can be used more than once in an attempt.)

Normally, calling code should be able to do everything it needs to be calling
methods of this class. You should not normally need to get individual
{@question_attempt} objects and play around with their inner workind, in code
that it outside the quetsion engine.

Instances of this class correspond to rows in the question_usages table.

__construct($component, $context)   X-Ref
Create a new instance. Normally, calling code should use
{@link question_engine::make_questions_usage_by_activity()} or
{@link question_engine::load_questions_usage_by_activity()} rather than
calling this constructor directly.

param: string $component the plugin creating this attempt. For example mod_quiz.
param: object $context the context this usage belongs to.

set_preferred_behaviour($behaviour)   X-Ref

param: string $behaviour the name of an archetypal behaviour, that should

get_preferred_behaviour()   X-Ref
No description

get_owning_context()   X-Ref
No description

get_owning_component()   X-Ref
No description

get_id()   X-Ref
No description

set_id_from_database($id)   X-Ref
For internal use only. Used by {@link question_engine_data_mapper} to set
the id when a usage is saved to the database.

param: int $id the newly determined id for this usage.

get_observer()   X-Ref
No description

set_observer($observer)   X-Ref
You should almost certainly not call this method from your code. It is for
internal use only.

param: question_usage_observer that should be used to tracking changes made to this usage.

add_question(question_definition $question, $maxmark = null)   X-Ref
Add another question to this usage.

The added question is not started until you call {@link start_question()}
on it.

param: question_definition $question the question to add.
param: number $maxmark the maximum this question will be marked out of in
return: int the number used to identify this question within this usage.

add_question_in_place_of_other($slot, question_definition $question, $maxmark = null)   X-Ref
Add another question to this usage, in the place of an existing slot.
The question_attempt that was in that slot is moved to the end at a new
slot number, which is returned.

The added question is not started until you call {@link start_question()}
on it.

param: int $slot the slot-number of the question to replace.
param: question_definition $question the question to add.
param: number $maxmark the maximum this question will be marked out of in
return: int the new slot number of the question that was displaced.

next_slot_number()   X-Ref
The slot number that will be allotted to the next question added.


get_question($slot, $requirequestioninitialised = true)   X-Ref
Get the question_definition for a question in this attempt.

param: int $slot the number used to identify this question within this usage.
param: bool $requirequestioninitialised set this to false if you don't need
return: question_definition the requested question object.

get_slots()   X-Ref
No description

get_first_question_number()   X-Ref
No description

question_count()   X-Ref
No description

get_attempt_iterator()   X-Ref
Note the part of the {@link question_usage_by_activity} comment that explains
that {@link question_attempt} objects should be considered part of the inner
workings of the question engine, and should not, if possible, be accessed directly.

return: question_attempt_iterator for iterating over all the questions being

check_slot($slot)   X-Ref
Check whether $number actually corresponds to a question attempt that is
part of this usage. Throws an exception if not.

param: int $slot a number allegedly identifying a question within this usage.

get_question_attempt($slot)   X-Ref
Note the part of the {@link question_usage_by_activity} comment that explains
that {@link question_attempt} objects should be considered part of the inner
workings of the question engine, and should not, if possible, be accessed directly.

param: int $slot the number used to identify this question within this usage.
return: question_attempt the corresponding {@link question_attempt} object.

get_question_state($slot)   X-Ref
Get the current state of the attempt at a question.

param: int $slot the number used to identify this question within this usage.
return: question_state.

get_question_state_string($slot, $showcorrectness)   X-Ref

param: int $slot the number used to identify this question within this usage.
param: bool $showcorrectness Whether right/partial/wrong states should
return: string A brief textual description of the current state.

get_question_state_class($slot, $showcorrectness)   X-Ref

param: int $slot the number used to identify this question within this usage.
param: bool $showcorrectness Whether right/partial/wrong states should
return: string a CSS class name for the current state.

can_question_finish_during_attempt($slot)   X-Ref
Whether this attempt at a given question could be completed just by the
student interacting with the question, before {@link finish_question()} is called.

param: int $slot the number used to identify this question within this usage.
return: boolean whether the attempt at the given question can finish naturally.

get_question_action_time($slot)   X-Ref
Get the time of the most recent action performed on a question.

param: int $slot the number used to identify this question within this usage.
return: int timestamp.

get_question_fraction($slot)   X-Ref
Get the current fraction awarded for the attempt at a question.

param: int $slot the number used to identify this question within this usage.
return: number|null The current fraction for this question, or null if one has

get_question_mark($slot)   X-Ref
Get the current mark awarded for the attempt at a question.

param: int $slot the number used to identify this question within this usage.
return: number|null The current mark for this question, or null if one has

get_question_max_mark($slot)   X-Ref
Get the maximum mark possible for the attempt at a question.

param: int $slot the number used to identify this question within this usage.
return: number the available marks for this question.

get_total_mark()   X-Ref
Get the total mark for all questions in this usage.

return: number The sum of marks of all the question_attempts in this usage.

get_summary_information(question_display_options $options)   X-Ref
Get summary information about this usage.

Some behaviours may be able to provide interesting summary information
about the attempt as a whole, and this method provides access to that data.
To see how this works, try setting a quiz to one of the CBM behaviours,
and then look at the extra information displayed at the top of the quiz
review page once you have sumitted an attempt.

In the return value, the array keys are identifiers of the form
qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
The values are arrays with two items, title and content. Each of these
will be either a string, or a renderable.

param: question_display_options $options display options to apply.
return: array as described above.

get_question_summary($slot)   X-Ref
Get a simple textual summary of the question that was asked.

param: int $slot the slot number of the question to summarise.
return: string the question summary.

get_response_summary($slot)   X-Ref
Get a simple textual summary of response given.

param: int $slot the slot number of the question to get the response summary for.
return: string the response summary.

get_right_answer_summary($slot)   X-Ref
Get a simple textual summary of the correct response to a question.

param: int $slot the slot number of the question to get the right answer summary for.
return: string the right answer summary.

get_question_attempt_metadata($slot, $name)   X-Ref
Return one of the bits of metadata for a particular question attempt in
this usage.

param: int $slot the slot number of the question of inereest.
param: string $name the name of the metadata variable to return.
return: string the value of that metadata variable.

set_question_attempt_metadata($slot, $name, $value)   X-Ref
Set some metadata for a particular question attempt in this usage.

param: int $slot the slot number of the question of inerest.
param: string $name the name of the metadata variable to return.
param: string $value the value to set that metadata variable to.

render_question($slot, $options, $number = null)   X-Ref
Get the {@link core_question_renderer}, in collaboration with appropriate
{@link qbehaviour_renderer} and {@link qtype_renderer} subclasses, to generate the
HTML to display this question.

param: int $slot the number used to identify this question within this usage.
param: question_display_options $options controls how the question is rendered.
param: string|null $number The question number to display. 'i' is a special
return: string HTML fragment representing the question.

render_question_head_html($slot)   X-Ref
Generate any bits of HTML that needs to go in the <head> tag when this question
is displayed in the body.

param: int $slot the number used to identify this question within this usage.
return: string HTML fragment.

render_question_at_step($slot, $seq, $options, $number = null)   X-Ref
Like {@link render_question()} but displays the question at the past step
indicated by $seq, rather than showing the latest step.

param: int $slot the number used to identify this question within this usage.
param: int $seq the seq number of the past state to display.
param: question_display_options $options controls how the question is rendered.
param: string|null $number The question number to display. 'i' is a special
return: string HTML fragment representing the question.

check_file_access($slot, $options, $component, $filearea,$args, $forcedownload)   X-Ref
Checks whether the users is allow to be served a particular file.

param: int $slot the number used to identify this question within this usage.
param: question_display_options $options the options that control display of the question.
param: string $component the name of the component we are serving files for.
param: string $filearea the name of the file area.
param: array $args the remaining bits of the file path.
param: bool $forcedownload whether the user must be forced to download the file.
return: bool true if the user can access this file.

replace_loaded_question_attempt_info($slot, $qa)   X-Ref
Replace a particular question_attempt with a different one.

For internal use only. Used when reloading the state of a question from the
database.

param: int $slot the slot number of the question to replace.
param: question_attempt $qa the question attempt to put in that place.

get_field_prefix($slot)   X-Ref
You should probably not use this method in code outside the question engine.
The main reason for exposing it was for the benefit of unit tests.

param: int $slot the number used to identify this question within this usage.
return: string return the prefix that is pre-pended to field names in the HTML

get_num_variants($slot)   X-Ref
Get the number of variants available for the question in this slot.

param: int $slot the number used to identify this question within this usage.
return: int the number of variants available.

get_variant($slot)   X-Ref
Get the variant of the question being used in a given slot.

param: int $slot the number used to identify this question within this usage.
return: int the variant of this question that is being used.

start_question($slot, $variant = null, $timenow = null)   X-Ref
Start the attempt at a question that has been added to this usage.

param: int $slot the number used to identify this question within this usage.
param: int $variant which variant of the question to use. Must be between
param: int|null $timenow optional, the timstamp to record for this action. Defaults to now.

start_all_questions(question_variant_selection_strategy $variantstrategy = null,$timestamp = null, $userid = null)   X-Ref
Start the attempt at all questions that has been added to this usage.

param: question_variant_selection_strategy how to pick which variant of each question to use.
param: int $timestamp optional, the timstamp to record for this action. Defaults to now.
param: int $userid optional, the user to attribute this action to. Defaults to the current user.

start_question_based_on($slot, question_attempt $oldqa)   X-Ref
Start the attempt at a question, starting from the point where the previous
question_attempt $oldqa had reached. This is used by the quiz 'Each attempt
builds on last' mode.

param: int $slot the number used to identify this question within this usage.
param: question_attempt $oldqa a previous attempt at this quetsion that

process_all_actions($timestamp = null, $postdata = null)   X-Ref
Process all the question actions in the current request.

If there is a parameter slots included in the post data, then only
those question numbers will be processed, otherwise all questions in this
useage will be.

This function also does {@link update_question_flags()}.

param: int $timestamp optional, use this timestamp as 'now'.
param: array $postdata optional, only intended for testing. Use this data

process_all_autosaves($timestamp = null, $postdata = null)   X-Ref
Process all the question autosave data in the current request.

If there is a parameter slots included in the post data, then only
those question numbers will be processed, otherwise all questions in this
useage will be.

This function also does {@link update_question_flags()}.

param: int $timestamp optional, use this timestamp as 'now'.
param: array $postdata optional, only intended for testing. Use this data

get_slots_in_request($postdata = null)   X-Ref
Get the list of slot numbers that should be processed as part of processing
the current request.

param: array $postdata optional, only intended for testing. Use this data
return: array of slot numbers.

extract_responses($slot, $postdata = null)   X-Ref
Get the submitted data from the current request that belongs to this
particular question.

param: int $slot the number used to identify this question within this usage.
param: array|null $postdata optional, only intended for testing. Use this data
return: array submitted data specific to this question.

prepare_simulated_post_data($simulatedresponses)   X-Ref
Transform an array of response data for slots to an array of post data as you would get from quiz attempt form.

param: $simulatedresponses array keys are slot nos => contains arrays representing student
return: array simulated post data

process_action($slot, $submitteddata, $timestamp = null)   X-Ref
Process a specific action on a specific question.

param: int $slot the number used to identify this question within this usage.
param: array $submitteddata the submitted data that constitutes the action.
param: int|null $timestamp (optional) the timestamp to consider 'now'.

process_autosave($slot, $submitteddata, $timestamp = null)   X-Ref
Process an autosave action on a specific question.

param: int $slot the number used to identify this question within this usage.
param: array $submitteddata the submitted data that constitutes the action.
param: int|null $timestamp (optional) the timestamp to consider 'now'.

validate_sequence_number($slot, $postdata = null)   X-Ref
Check that the sequence number, that detects weird things like the student clicking back, is OK.

If the sequence check variable is not present, returns
false. If the check variable is present and correct, returns true. If the
variable is present and wrong, throws an exception.

param: int $slot the number used to identify this question within this usage.
param: array|null $postdata (optional) data to use in place of $_POST.
return: bool true if the check variable is present and correct. False if it

is_autosave_required($slot, $postdata = null)   X-Ref
Check, based on the sequence number, whether this auto-save is still required.

param: int $slot the number used to identify this question within this usage.
param: array|null $postdata the submitted data that constitutes the action.
return: bool true if the check variable is present and correct, otherwise false.

update_question_flags($postdata = null)   X-Ref
Update the flagged state for all question_attempts in this usage, if their
flagged state was changed in the request.

param: array|null $postdata optional, only intended for testing. Use this data

get_correct_response($slot)   X-Ref
Get the correct response to a particular question. Passing the results of
this method to {@link process_action()} will probably result in full marks.
If it is not possible to compute a correct response, this method should return null.

param: int $slot the number used to identify this question within this usage.
return: array that constitutes a correct response to this question.

finish_question($slot, $timestamp = null)   X-Ref
Finish the active phase of an attempt at a question.

This is an external act of finishing the attempt. Think, for example, of
the 'Submit all and finish' button in the quiz. Some behaviours,
(for example, immediatefeedback) give a way of finishing the active phase
of a question attempt as part of a {@link process_action()} call.

After the active phase is over, the only changes possible are things like
manual grading, or changing the flag state.

param: int $slot the number used to identify this question within this usage.
param: int|null $timestamp (optional) the timestamp to consider 'now'.

finish_all_questions($timestamp = null)   X-Ref
Finish the active phase of an attempt at a question. See {@link finish_question()}
for a fuller description of what 'finish' means.

param: int|null $timestamp (optional) the timestamp to consider 'now'.

manual_grade($slot, $comment, $mark, $commentformat = null)   X-Ref
Perform a manual grading action on a question attempt.

param: int $slot the number used to identify this question within this usage.
param: string $comment the comment being added to the question attempt.
param: number $mark the mark that is being assigned. Can be null to just
param: int $commentformat one of the FORMAT_... constants. The format of $comment.

validate_can_regrade_with_other_version(int $slot, question_definition $otherversion)   X-Ref
Verify if the question_attempt in the given slot can be regraded with that other question version.

param: int $slot the number used to identify this question within this usage.
param: question_definition $otherversion a different version of the question to use in the regrade.
return: string|null null if the regrade can proceed, else a reason why not.

regrade_question($slot, $finished = false, $newmaxmark = null,question_definition $otherversion = null)   X-Ref
Regrade a question in this usage. This replays the sequence of submitted
actions to recompute the outcomes.

param: int $slot the number used to identify this question within this usage.
param: bool $finished whether the question attempt should be forced to be finished
param: number $newmaxmark (optional) if given, will change the max mark while regrading.
param: question_definition|null $otherversion a different version of the question to use

regrade_all_questions($finished = false)   X-Ref
Regrade all the questions in this usage (without changing their max mark).

param: bool $finished whether each question should be forced to be finished

set_max_mark($slot, $maxmark)   X-Ref
Change the max mark for this question_attempt.

param: int $slot the slot number of the question of inerest.
param: float $maxmark the new max mark.

load_from_records($records, $qubaid)   X-Ref
Create a question_usage_by_activity from records loaded from the database.

For internal use only.

param: Iterator $records Raw records loaded from the database.
param: int $qubaid The id of the question usage we are loading.
return: question_usage_by_activity The newly constructed usage.

preload_all_step_users()   X-Ref
Preload users of all question attempt steps.


Class: question_attempt_iterator  - X-Ref

A class abstracting access to the {@link question_usage_by_activity::$questionattempts} array.

This class snapshots the list of {@link question_attempts} to iterate over
when it is created. If a question is added to the usage mid-iteration, it
will now show up.

To create an instance of this class, use
{@link question_usage_by_activity::get_attempt_iterator()}

__construct(question_usage_by_activity $quba)   X-Ref
To create an instance of this class, use
{@link question_usage_by_activity::get_attempt_iterator()}.

param: question_usage_by_activity $quba the usage to iterate over.

current()   X-Ref
Standard part of the Iterator interface.

return: question_attempt

key()   X-Ref
Standard part of the Iterator interface.

return: int

next()   X-Ref
Standard part of the Iterator interface.


rewind()   X-Ref
Standard part of the Iterator interface.


valid()   X-Ref
Standard part of the Iterator interface.

return: bool

offsetExists($slot)   X-Ref
Standard part of the ArrayAccess interface.

param: int $slot
return: bool

offsetGet($slot)   X-Ref
Standard part of the ArrayAccess interface.

param: int $slot
return: question_attempt

offsetSet($slot, $value)   X-Ref
Standard part of the ArrayAccess interface.

param: int $slot
param: question_attempt $value

offsetUnset($slot)   X-Ref
Standard part of the ArrayAccess interface.

param: int $slot

Interface: question_usage_observer  - X-Ref

Interface for things that want to be notified of signficant changes to a
{@link question_usage_by_activity}.

A question behaviour controls the flow of actions a student can
take as they work through a question, and later, as a teacher manually grades it.

notify_modified()   X-Ref
No description

notify_attempt_added(question_attempt $qa)   X-Ref
Called when a new question attempt is added to this usage.

param: question_attempt $qa the newly added question attempt.

notify_attempt_modified(question_attempt $qa)   X-Ref
Called when the fields of a question attempt in this usage are modified.

param: question_attempt $qa the newly added question attempt.

notify_attempt_moved(question_attempt $qa, $oldslot)   X-Ref
Called when a question_attempt has been moved to a new slot.

param: question_attempt $qa The question attempt that was moved.
param: int $oldslot The previous slot number of that attempt.

notify_step_added(question_attempt_step $step, question_attempt $qa, $seq)   X-Ref
Called when a new step is added to a question attempt in this usage.

param: question_attempt_step $step the new step.
param: question_attempt $qa the usage it is being added to.
param: int $seq the sequence number of the new step.

notify_step_modified(question_attempt_step $step, question_attempt $qa, $seq)   X-Ref
Called when a new step is updated in a question attempt in this usage.

param: question_attempt_step $step the step that was updated.
param: question_attempt $qa the usage it is being added to.
param: int $seq the sequence number of the new step.

notify_step_deleted(question_attempt_step $step, question_attempt $qa)   X-Ref
Called when a new step is updated in a question attempt in this usage.

param: question_attempt_step $step the step to delete.
param: question_attempt $qa the usage it is being added to.

notify_metadata_added(question_attempt $qa, $name)   X-Ref
Called when a new metadata variable is set on a question attempt in this usage.

param: question_attempt $qa the question attempt the metadata is being added to.
param: int $name the name of the metadata variable added.

notify_metadata_modified(question_attempt $qa, $name)   X-Ref
Called when a metadata variable on a question attempt in this usage is updated.

param: question_attempt $qa the question attempt where the metadata is being modified.
param: int $name the name of the metadata variable modified.

Class: question_usage_null_observer  - X-Ref

Null implmentation of the {@link question_usage_watcher} interface.
Does nothing.

notify_modified()   X-Ref
No description

notify_attempt_added(question_attempt $qa)   X-Ref
No description

notify_attempt_modified(question_attempt $qa)   X-Ref
No description

notify_attempt_moved(question_attempt $qa, $oldslot)   X-Ref
No description

notify_step_added(question_attempt_step $step, question_attempt $qa, $seq)   X-Ref
No description

notify_step_modified(question_attempt_step $step, question_attempt $qa, $seq)   X-Ref
No description

notify_step_deleted(question_attempt_step $step, question_attempt $qa)   X-Ref
No description

notify_metadata_added(question_attempt $qa, $name)   X-Ref
No description

notify_metadata_modified(question_attempt $qa, $name)   X-Ref
No description