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] [Versions 401 and 402] [Versions 401 and 403]

This file defines the question attempt step 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: 791 lines (29 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 5 classes

question_attempt_step:: (29 methods):
  __construct()
  get_id()
  get_state()
  set_state()
  get_fraction()
  set_fraction()
  get_user_id()
  add_full_user_object()
  get_user()
  get_user_fullname()
  get_timecreated()
  has_qt_var()
  get_qt_var()
  set_qt_var()
  get_qt_files()
  prepare_response_files_draft_itemid()
  prepare_response_files_draft_itemid_with_text()
  rewrite_response_pluginfile_urls()
  get_qt_data()
  has_behaviour_var()
  get_behaviour_var()
  set_behaviour_var()
  get_behaviour_data()
  get_submitted_data()
  get_all_data()
  set_metadata_var()
  has_metadata_var()
  get_metadata_var()
  load_from_records()

question_attempt_pending_step:: (6 methods):
  set_new_response_summary()
  get_new_response_summary()
  response_summary_changed()
  set_new_variant_number()
  get_new_variant_number()
  variant_number_changed()

question_attempt_step_read_only:: (4 methods):
  set_state()
  set_fraction()
  set_qt_var()
  set_behaviour_var()

question_null_step:: (3 methods):
  get_state()
  set_state()
  get_fraction()

question_attempt_step_subquestion_adapter:: (24 methods):
  __construct()
  add_prefix()
  remove_prefix()
  filter_array()
  get_state()
  set_state()
  get_fraction()
  set_fraction()
  get_user_id()
  get_timecreated()
  has_qt_var()
  get_qt_var()
  set_qt_var()
  get_qt_data()
  has_behaviour_var()
  get_behaviour_var()
  set_behaviour_var()
  get_behaviour_data()
  get_submitted_data()
  get_all_data()
  get_qt_files()
  prepare_response_files_draft_itemid()
  prepare_response_files_draft_itemid_with_text()
  rewrite_response_pluginfile_urls()


Class: question_attempt_step  - X-Ref

Stores one step in a {@see question_attempt}.

The most important attributes of a step are the state, which is one of the
{@see question_state} constants, the fraction, which may be null, or a
number bewteen the attempt's minfraction and maxfraction, and the array of submitted
data, about which more later.

A step also tracks the time it was created, and the user responsible for
creating it.

The submitted data is basically just an array of name => value pairs, with
certain conventions about the to divide the variables into five = 2 x 2 + 1 categories.

Variables may either belong to the behaviour, in which case the
name starts with a '-', or they may belong to the question type in which case
they name does not start with a '-'.

Second, variables may either be ones that came form the original request, in
which case the name does not start with an _, or they are cached values that
were created during processing, in which case the name does start with an _.

In addition, we can store 'metadata', typically only in the first step of a
question attempt. These are stored with the initial characters ':_'.

That is, each name will start with one of '', '_', '-', '-_' or ':_'. The remainder
of the name was supposed to match the regex [a-z][a-z0-9]* - but this has never
been enforced. Question types exist which break this rule. E.g. qtype_combined.
Perhpas now, an accurate regex would be [a-z][a-z0-9_:]*.

These variables can be accessed with {@see get_behaviour_var()} and {@see get_qt_var()},
- to be clear, ->get_behaviour_var('x') gets the variable with name '-x' -
and values whose names start with '_' can be set using {@see set_behaviour_var()}
and {@see set_qt_var()}. There are some other methods like {@see has_behaviour_var()}
to check wether a varaible with a particular name is set, and {@see get_behaviour_data()}
to get all the behaviour data as an associative array. There are also
{@see get_metadata_var()}, {@see set_metadata_var()} and {@see has_metadata_var()},

__construct($data = array()   X-Ref
You should not need to call this constructor in your own code. Steps are
normally created by {@see question_attempt} methods like
{@see question_attempt::process_action()}.

param: array $data the submitted data that defines this step.
param: int $timestamp the time to record for the action. (If not given, use now.)
param: int $userid the user to attribute the aciton to. (If not given, use the current user.)
param: int $existingstepid if this step is going to replace an existing step

get_id()   X-Ref

return: int|null The id of this step in the database. null if this step

get_state()   X-Ref
No description

set_state($state)   X-Ref
Set the state. Normally only called by behaviours.

param: question_state $state one of the {@see question_state} constants.

get_fraction()   X-Ref

return: null|number the fraction (grade on a scale of

set_fraction($fraction)   X-Ref
Set the fraction. Normally only called by behaviours.

param: null|number $fraction the fraction to set.

get_user_id()   X-Ref
No description

add_full_user_object(stdClass $user)   X-Ref
Update full user information for step.

param: stdClass $user Full user object.

get_user()   X-Ref
Return the full user object.

return: stdClass Get full user object.

get_user_fullname()   X-Ref
Get full name of user who did action.

return: string full name of user.

get_timecreated()   X-Ref
No description

has_qt_var($name)   X-Ref

param: string $name the name of a question type variable to look for in the submitted data.
return: bool whether a variable with this name exists in the question type data.

get_qt_var($name)   X-Ref

param: string $name the name of a question type variable to look for in the submitted data.
return: string the requested variable, or null if the variable is not set.

set_qt_var($name, $value)   X-Ref
Set a cached question type variable.

param: string $name the name of the variable to set. Must match _[a-z][a-z0-9]*.
param: string $value the value to set.

get_qt_files($name, $contextid)   X-Ref
Get the latest set of files for a particular question type variable of
type question_attempt::PARAM_FILES.

param: string $name the name of the associated variable.
param: int $contextid contextid of the question attempt
return: array of {@see stored_files}.

prepare_response_files_draft_itemid($name, $contextid)   X-Ref
Prepare a draft file are for the files belonging the a response variable
of this step.

param: string $name the variable name the files belong to.
param: int $contextid the id of the context the quba belongs to.
return: int the draft itemid.

prepare_response_files_draft_itemid_with_text($name, $contextid, $text)   X-Ref
Prepare a draft file are for the files belonging the a response variable
of this step, while rewriting the URLs in some text.

param: string $name the variable name the files belong to.
param: int $contextid the id of the context the quba belongs to.
param: string $text the text to update the URLs in.
return: array(int, string) the draft itemid and the text with URLs rewritten.

rewrite_response_pluginfile_urls($text, $contextid, $name, $extras)   X-Ref
Rewrite the @@PLUGINFILE@@ tokens in a response variable from this step
that contains links to file. Normally you should probably call
{@see question_attempt::rewrite_response_pluginfile_urls()} instead of
calling this method directly.

param: string $text the text to update the URLs in.
param: int $contextid the id of the context the quba belongs to.
param: string $name the variable name the files belong to.
param: array $extra extra file path components.
return: string the rewritten text.

get_qt_data()   X-Ref
Get all the question type variables.

param: array name => value pairs.

has_behaviour_var($name)   X-Ref

param: string $name the name of a behaviour variable to look for in the submitted data.
return: bool whether a variable with this name exists in the question type data.

get_behaviour_var($name)   X-Ref

param: string $name the name of a behaviour variable to look for in the submitted data.
return: string the requested variable, or null if the variable is not set.

set_behaviour_var($name, $value)   X-Ref
Set a cached behaviour variable.

param: string $name the name of the variable to set. Must match _[a-z][a-z0-9]*.
param: string $value the value to set.

get_behaviour_data()   X-Ref
Get all the behaviour variables.

return: array name => value pairs. NOTE! the name has the leading - stripped off.

get_submitted_data()   X-Ref
Get all the submitted data, but not the cached data. behaviour
variables have the - at the start of their name. This is only really
intended for use by {@see question_attempt::regrade()}, it should not
be considered part of the public API.

param: array name => value pairs.

get_all_data()   X-Ref
Get all the data. behaviour variables have the - at the start of
their name. This is only intended for internal use, for example by
{@see question_engine_data_mapper::insert_question_attempt_step()},
however, it can occasionally be useful in test code. It should not be
considered part of the public API of this class.

param: array name => value pairs.

set_metadata_var($name, $value)   X-Ref
Set a metadata variable.

Do not call this method directly from  your code. It is for internal
use only. You should call {@see question_usage::set_question_attempt_metadata()}.

param: string $name the name of the variable to set. [a-z][a-z0-9]*.
param: string $value the value to set.

has_metadata_var($name)   X-Ref
Whether this step has a metadata variable.

Do not call this method directly from  your code. It is for internal
use only. You should call {@see question_usage::get_question_attempt_metadata()}.

param: string $name the name of the variable to set. [a-z][a-z0-9]*.
return: bool the value to set previously, or null if this variable was never set.

get_metadata_var($name)   X-Ref
Get a metadata variable.

Do not call this method directly from  your code. It is for internal
use only. You should call {@see question_usage::get_question_attempt_metadata()}.

param: string $name the name of the variable to set. [a-z][a-z0-9]*.
return: string the value to set previously, or null if this variable was never set.

load_from_records($records, $attemptstepid, $qtype = null)   X-Ref
Create a question_attempt_step from records loaded from the database.

param: Iterator $records Raw records loaded from the database.
param: int $stepid The id of the records to extract.
param: string $qtype The question type of which this is an attempt.
return: question_attempt_step The newly constructed question_attempt_step.

Class: question_attempt_pending_step  - X-Ref

A subclass of {@see question_attempt_step} used when processing a new submission.

When we are processing some new submitted data, which may or may not lead to
a new step being added to the {@see question_usage_by_activity} we create an
instance of this class. which is then passed to the question behaviour and question
type for processing. At the end of processing we then may, or may not, keep it.

set_new_response_summary($responsesummary)   X-Ref
If as a result of processing this step, the response summary for the
question attempt should changed, you should call this method to set the
new summary.

param: string $responsesummary the new response summary.

get_new_response_summary()   X-Ref
Get the new response summary, if there is one.

return: string the new response summary, or null if it has not changed.

response_summary_changed()   X-Ref
Whether this processing this step has changed the response summary.

return: bool true if there is a new response summary.

set_new_variant_number($variant)   X-Ref
If as a result of processing this step, you identify that this variant of the
question is actually identical to the another one, you may change the
variant number recorded, in order to give better statistics. For an example
see qbehaviour_opaque.

param: int $variant the new variant number.

get_new_variant_number()   X-Ref
Get the new variant number, if there is one.

return: int the new variant number, or null if it has not changed.

variant_number_changed()   X-Ref
Whether this processing this step has changed the variant number.

return: bool true if there is a new variant number.

Class: question_attempt_step_read_only  - X-Ref

A subclass of {@see question_attempt_step} that cannot be modified.

set_state($state)   X-Ref
No description

set_fraction($fraction)   X-Ref
No description

set_qt_var($name, $value)   X-Ref
No description

set_behaviour_var($name, $value)   X-Ref
No description

Class: question_null_step  - X-Ref

A null {@see question_attempt_step} returned from
{@see question_attempt::get_last_step()} etc. when a an attempt has just been
created and there is no actual step.

get_state()   X-Ref
No description

set_state($state)   X-Ref
No description

get_fraction()   X-Ref
No description

Class: question_attempt_step_subquestion_adapter  - X-Ref

This is an adapter class that wraps a {@see question_attempt_step} and
modifies the get/set_*_data methods so that they operate only on the parts
that belong to a particular subquestion, as indicated by an extra prefix.

__construct($realqas, $extraprefix)   X-Ref
Constructor.

param: question_attempt_step $realqas the step to wrap. (Can be null if you
param: string $extraprefix the extra prefix that is used for date fields.

add_prefix($field)   X-Ref
Add the extra prefix to a field name.

param: string $field the plain field name.
return: string the field name with the extra bit of prefix added.

remove_prefix($field)   X-Ref
Remove the extra prefix from a field name if it is present.

param: string $field the extended field name.
return: string the field name with the extra bit of prefix removed, or

filter_array($data)   X-Ref
Filter some data to keep only those entries where the key contains
extraprefix, and remove the extra prefix from the reutrned arrary.

param: array $data some of the data stored in this step.
return: array the data with the keys ajusted using {@see remove_prefix()}.

get_state()   X-Ref
No description

set_state($state)   X-Ref
No description

get_fraction()   X-Ref
No description

set_fraction($fraction)   X-Ref
No description

get_user_id()   X-Ref
No description

get_timecreated()   X-Ref
No description

has_qt_var($name)   X-Ref
No description

get_qt_var($name)   X-Ref
No description

set_qt_var($name, $value)   X-Ref
No description

get_qt_data()   X-Ref
No description

has_behaviour_var($name)   X-Ref
No description

get_behaviour_var($name)   X-Ref
No description

set_behaviour_var($name, $value)   X-Ref
No description

get_behaviour_data()   X-Ref
No description

get_submitted_data()   X-Ref
No description

get_all_data()   X-Ref
No description

get_qt_files($name, $contextid)   X-Ref
No description

prepare_response_files_draft_itemid($name, $contextid)   X-Ref
No description

prepare_response_files_draft_itemid_with_text($name, $contextid, $text)   X-Ref
No description

rewrite_response_pluginfile_urls($text, $contextid, $name, $extras)   X-Ref
No description