Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
availability_profile\condition Class Reference

User profile field condition. More...

Inheritance diagram for availability_profile\condition:
core_availability\condition core_availability\tree_node

Public Member Functions

 __construct ($structure)
 Constructor. More...
 
 __toString ()
 Display a representation of this condition (used for debugging). More...
 
 check_available ($not, core_availability\info $info, $grabthelot, $userid)
 Determines whether this particular item is currently available according to the availability criteria. More...
 
 check_available ($not, info $info, $grabthelot, $userid)
 
 filter_user_list (array $users, $not, core_availability\info $info, capability_checker $checker)
 Tests this condition against a user list. More...
 
 filter_user_list (array $users, $not, core_availability\info $info, core_availability\capability_checker $checker)
 
 get_description ($full, $not, core_availability\info $info)
 Obtains a string describing this restriction (whether or not it actually applies). More...
 
 get_standalone_description ($full, $not, info $info)
 Obtains a string describing this restriction, used when there is only a single restriction to display. More...
 
 get_user_list_sql ($not, core_availability\info $info, $onlyactive)
 Obtains SQL that returns a list of enrolled users that has been filtered by the conditions applied in the availability API, similar to calling get_enrolled_users and then filter_user_list. More...
 
 get_user_list_sql ($not, core_availability\info $info, $onlyactive)
 
 include_after_restore ($restoreid, $courseid, base_logger $logger, $name, base_task $task)
 Checks whether this node should be included after restore or not. More...
 
 is_applied_to_user_lists ()
 Checks whether this condition applies to user lists. More...
 
 is_available ($not, core_availability\info $info, $grabthelot, $userid)
 Determines whether a particular item is currently available according to this availability condition. More...
 
 is_available_for_all ($not=false)
 Checks whether this condition is actually going to be available for all users under normal circumstances. More...
 
 save ()
 Saves tree data back to a structure object. More...
 
 update_after_restore ($restoreid, $courseid, base_logger $logger, $name)
 Updates this node after restore, returning true if anything changed. More...
 
 update_dependency_id ($table, $oldid, $newid)
 Updates this node if it contains any references (dependencies) to the given table and id. More...
 

Static Public Member Functions

static completion_value_used ($course, $cmid)
 If the plugin has been configured to rely on a particular activity's completion value, it should return true here. More...
 
static get_custom_profile_fields ()
 Gets data about custom profile fields. More...
 
static get_json ($customfield, $fieldname, $operator, $value=null)
 Returns a JSON object which corresponds to a condition of this type. More...
 
static wipe_static_cache ()
 Wipes the static cache (for use in unit tests).
 

Public Attributes

string const OP_CONTAINS = 'contains'
 Operator: field contains value.
 
string const OP_DOES_NOT_CONTAIN = 'doesnotcontain'
 Operator: field does not contain value.
 
string const OP_ENDS_WITH = 'endswith'
 Operator: field ends with value.
 
string const OP_IS_EMPTY = 'isempty'
 Operator: field is empty.
 
string const OP_IS_EQUAL_TO = 'isequalto'
 Operator: field equals value.
 
string const OP_IS_NOT_EMPTY = 'isnotempty'
 Operator: field is not empty.
 
string const OP_STARTS_WITH = 'startswith'
 Operator: field starts with value.
 

Protected Member Functions

 get_cached_user_profile_field ($userid)
 Return the value for a user's profile field. More...
 
 get_debug_string ()
 Obtains a representation of the options of this condition as a string, for debugging. More...
 
 get_type ()
 Gets the type name (e.g. More...
 

Static Protected Member Functions

static is_field_condition_met ($operator, $uservalue, $value)
 Returns true if a field meets the required conditions, false otherwise. More...
 
static unique_sql_parameter (array &$params, $value)
 Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters). More...
 

Protected Attributes

int $customfield = ''
 Field name (for custom fields) or '' if standard field.
 
string $operator
 Operator type (OP_xx constant)
 
string $standardfield = ''
 Field name (for standard fields) or '' if custom field.
 
string $value = ''
 Expected value for field.
 

Static Protected Attributes

static array null $customprofilefields = null
 Array of custom profile fields (static cache within request)
 
static int $uniquesqlparametercounter = 1
 Counter to be used in tree_node::unique_sql_parameter().
 

Detailed Description

User profile field condition.

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

Constructor & Destructor Documentation

◆ __construct()

availability_profile\condition::__construct (   $structure)

Constructor.

Parameters
stdClass$structureData structure from JSON decode
Exceptions
coding_exceptionIf invalid data structure.

Member Function Documentation

◆ __toString()

core_availability\condition::__toString ( )
inherited

Display a representation of this condition (used for debugging).

Return values
stringText representation of condition

◆ check_available()

core_availability\tree_node::check_available (   $not,
core_availability\info  $info,
  $grabthelot,
  $userid 
)
abstractinherited

Determines whether this particular item is currently available according to the availability criteria.

  • This does not include the 'visible' setting (i.e. this might return true even if visible is false); visible is handled independently.
  • This does not take account of the viewhiddenactivities capability. That should apply later.

The $not option is potentially confusing. This option always indicates the 'real' value of NOT. For example, a condition inside a 'NOT AND' group will get this called with $not = true, but if you put another 'NOT OR' group inside the first group, then a condition inside that will be called with $not = false. We need to use the real values, rather than the more natural use of the current value at this point inside the tree, so that the information displayed to users makes sense.

Parameters
bool$notSet true if we are inverting the condition
core_availability::info$infoItem we're checking
bool$grabthelotPerformance hint: if true, caches information required for all course-modules, to make the front page and similar pages work more quickly (works only for current user)
int$useridUser ID to check availability for
Return values
resultAvailability check result

◆ completion_value_used()

static core_availability\condition::completion_value_used (   $course,
  $cmid 
)
staticinherited

If the plugin has been configured to rely on a particular activity's completion value, it should return true here.

(This is necessary so that we know the course page needs to update when that activity becomes complete.)

Default implementation returns false.

Parameters
stdClass$courseMoodle course object
int$cmidID of activity whose completion value is considered
Return values
booleanTrue if the availability of something else may rely on it

Reimplemented in availability_completion\condition.

◆ filter_user_list()

core_availability\tree_node::filter_user_list ( array  $users,
  $not,
core_availability\info  $info,
capability_checker  $checker 
)
inherited

Tests this condition against a user list.

Users who do not meet the condition will be removed from the list, unless they have the ability to view hidden activities/sections.

This function must be implemented if is_applied_to_user_lists returns true. Otherwise it will not be called.

The function must operate efficiently, e.g. by using a fixed number of database queries regardless of how many users are in the list.

Within this function, if you need to check capabilities, please use the provided checker which caches results where possible.

Conditions do not need to check the viewhiddenactivities or viewhiddensections capabilities. These are handled by core_availability::info::filter_user_list.

Parameters
array$usersArray of userid => object
bool$notTrue if this condition is applying in negative mode
core_availability::info$infoItem we're checking
capability_checker$checker
Return values
arrayFiltered version of input array
Exceptions
coding_exceptionIf called on a condition that doesn't apply to user lists

◆ get_cached_user_profile_field()

availability_profile\condition::get_cached_user_profile_field (   $userid)
protected

Return the value for a user's profile field.

Parameters
int$useridUser ID
Return values
string|boolValue, or false if user does not have a value for this field

◆ get_custom_profile_fields()

static availability_profile\condition::get_custom_profile_fields ( )
static

Gets data about custom profile fields.

Cached statically in current request.

This only includes fields which can be tested by the system (those whose data is cached in $USER object) - basically doesn't include textarea type fields.

Return values
arrayArray of records indexed by shortname

◆ get_debug_string()

availability_profile\condition::get_debug_string ( )
protected

Obtains a representation of the options of this condition as a string, for debugging.

Return values
stringText representation of parameters

Reimplemented from core_availability\condition.

◆ get_description()

availability_profile\condition::get_description (   $full,
  $not,
core_availability\info  $info 
)

Obtains a string describing this restriction (whether or not it actually applies).

Used to obtain information that is displayed to students if the activity is not available to them, and for staff to see what conditions are.

The $full parameter can be used to distinguish between 'staff' cases (when displaying all information about the activity) and 'student' cases (when displaying only conditions they don't meet).

If implementations require a course or modinfo, they should use the get methods in $info.

The special string <AVAILABILITY_CMNAME_123> can be returned, where 123 is any number. It will be replaced with the correctly-formatted name for that activity.

Parameters
bool$fullSet true if this is the 'full information' view
bool$notSet true if we are inverting the condition
info$infoItem we're checking
Return values
stringInformation string (for admin) about all restrictions on this item

Reimplemented from core_availability\condition.

◆ get_json()

static availability_profile\condition::get_json (   $customfield,
  $fieldname,
  $operator,
  $value = null 
)
static

Returns a JSON object which corresponds to a condition of this type.

Intended for unit testing, as normally the JSON values are constructed by JavaScript code.

Parameters
bool$customfieldTrue if this is a custom field
string$fieldnameField name
string$operatorOperator name (OP_xx constant)
string | null$valueValue (not required for some operator types)
Return values
stdClassObject representing condition

◆ get_standalone_description()

core_availability\condition::get_standalone_description (   $full,
  $not,
info  $info 
)
inherited

Obtains a string describing this restriction, used when there is only a single restriction to display.

(I.e. this provides a 'short form' rather than showing in a list.)

Default behaviour sticks the prefix text, normally displayed above the list, in front of the standard get_description call.

If implementations require a course or modinfo, they should use the get methods in $info.

The special string <AVAILABILITY_CMNAME_123> can be returned, where 123 is any number. It will be replaced with the correctly-formatted name for that activity.

Parameters
bool$fullSet true if this is the 'full information' view
bool$notSet true if we are inverting the condition
info$infoItem we're checking
Return values
stringInformation string (for admin) about all restrictions on this item

Reimplemented in availability_date\condition.

◆ get_type()

core_availability\condition::get_type ( )
protectedinherited

Gets the type name (e.g.

'date' for availability_date) of plugin.

Return values
stringThe type name for this plugin

◆ get_user_list_sql()

core_availability\tree_node::get_user_list_sql (   $not,
core_availability\info  $info,
  $onlyactive 
)
inherited

Obtains SQL that returns a list of enrolled users that has been filtered by the conditions applied in the availability API, similar to calling get_enrolled_users and then filter_user_list.

As for filter_user_list, this ONLY filters out users with conditions that are marked as applying to user lists. For example, group conditions are included but date conditions are not included.

The returned SQL is a query that returns a list of user IDs. It does not include brackets, so you neeed to add these to make it into a subquery. You would normally use it in an SQL phrase like "WHERE u.id IN ($sql)".

The SQL will be complex and may be slow. It uses named parameters (sorry, I know they are annoying, but it was unavoidable here).

If there are no conditions, the returned result is array('', array()).

Conditions do not need to check the viewhiddenactivities or viewhiddensections capabilities. These are handled by core_availability::info::get_user_list_sql.

Parameters
bool$notTrue if this condition is applying in negative mode
core_availability::info$infoItem we're checking
bool$onlyactiveIf true, only returns active enrolments
Return values
arrayArray with two elements: SQL subquery and parameters array
Exceptions
coding_exceptionIf called on a condition that doesn't apply to user lists

◆ include_after_restore()

core_availability\tree_node::include_after_restore (   $restoreid,
  $courseid,
base_logger  $logger,
  $name,
base_task  $task 
)
inherited

Checks whether this node should be included after restore or not.

The node may be removed depending on restore settings, which you can get from the $task object.

By default nodes are still included after restore.

Parameters
string$restoreidRestore ID
int$courseidID of target course
base_logger$loggerLogger for any warnings
string$nameName of this item (for use in warning messages)
base_task$taskCurrent restore task
Return values
boolTrue if there was any change

Reimplemented in availability_group\condition, and availability_grouping\condition.

◆ is_applied_to_user_lists()

availability_profile\condition::is_applied_to_user_lists ( )

Checks whether this condition applies to user lists.

The default is false (the condition is used to control access, but does not prevent the student from appearing in lists).

For example, group conditions apply to user lists: we do not want to include a student in a list of users if they are prohibited from accessing the activity because they don't belong to a relevant group. However, date conditions do not apply - we still want to show users in a list of people who might have submitted an assignment, even if they are no longer able to access the assignment in question because there is a date restriction.

The general idea is that conditions which are likely to be permanent (group membership, user profile) apply to user lists. Conditions which are likely to be temporary (date, grade requirement) do not.

Conditions which do apply to user lists must implement the filter_user_list function.

Return values
boolTrue if this condition applies to user lists

Reimplemented from core_availability\tree_node.

◆ is_available()

availability_profile\condition::is_available (   $not,
core_availability\info  $info,
  $grabthelot,
  $userid 
)

Determines whether a particular item is currently available according to this availability condition.

If implementations require a course or modinfo, they should use the get methods in $info.

The $not option is potentially confusing. This option always indicates the 'real' value of NOT. For example, a condition inside a 'NOT AND' group will get this called with $not = true, but if you put another 'NOT OR' group inside the first group, then a condition inside that will be called with $not = false. We need to use the real values, rather than the more natural use of the current value at this point inside the tree, so that the information displayed to users makes sense.

Parameters
bool$notSet true if we are inverting the condition
info$infoItem we're checking
bool$grabthelotPerformance hint: if true, caches information required for all course-modules, to make the front page and similar pages work more quickly (works only for current user)
int$useridUser ID to check availability for
Return values
boolTrue if available

Reimplemented from core_availability\condition.

◆ is_available_for_all()

core_availability\condition::is_available_for_all (   $not = false)
inherited

Checks whether this condition is actually going to be available for all users under normal circumstances.

Normally, if there are any conditions, then it may be hidden. However in the case of date conditions there are some conditions which will definitely not result in it being hidden for anyone.

Parameters
bool$notSet true if we are inverting the condition
Return values
boolTrue if condition will return available for everyone

Reimplemented from core_availability\tree_node.

Reimplemented in availability_date\condition.

◆ is_field_condition_met()

static availability_profile\condition::is_field_condition_met (   $operator,
  $uservalue,
  $value 
)
staticprotected

Returns true if a field meets the required conditions, false otherwise.

Parameters
string$operatorthe requirement/condition
string$uservaluethe user's value
string$valuethe value required
Return values
booleanTrue if conditions are met

◆ save()

availability_profile\condition::save ( )

Saves tree data back to a structure object.

Return values
stdClassStructure object (ready to be made into JSON format)

Reimplemented from core_availability\tree_node.

◆ unique_sql_parameter()

static core_availability\tree_node::unique_sql_parameter ( array &  $params,
  $value 
)
staticprotectedinherited

Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters).

Parameters
array$paramsParams array (value will be added to this array)
string | int$valueValue
Return values
SQLcode for the parameter, e.g. ':pr1234'

◆ update_after_restore()

core_availability\tree_node::update_after_restore (   $restoreid,
  $courseid,
base_logger  $logger,
  $name 
)
inherited

Updates this node after restore, returning true if anything changed.

The default behaviour is simply to return false. If there is a problem with the update, $logger can be used to output a warning.

Note: If you need information about the date offset, call core_availability::info::get_restore_date_offset($restoreid). For information on the restoring task and its settings, call core_availability::info::get_restore_task($restoreid).

Parameters
string$restoreidRestore ID
int$courseidID of target course
base_logger$loggerLogger for any warnings
string$nameName of this item (for use in warning messages)
Return values
boolTrue if there was any change

Reimplemented in availability_date\condition, core_availability\tree, availability_completion\condition, availability_grade\condition, availability_group\condition, and availability_grouping\condition.

◆ update_dependency_id()

core_availability\condition::update_dependency_id (   $table,
  $oldid,
  $newid 
)
inherited

Updates this node if it contains any references (dependencies) to the given table and id.

Parameters
string$tableTable name e.g. 'course_modules'
int$oldidPrevious ID
int$newidNew ID
Return values
boolTrue if it changed, otherwise false

Reimplemented from core_availability\tree_node.

Reimplemented in availability_completion\condition, availability_grade\condition, availability_group\condition, and availability_grouping\condition.


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