mirror of
https://github.com/moodle/moodle.git
synced 2025-08-04 16:36:37 +02:00
1a7049af22
The previous API included a facility to filter a list of users to include only those who are allowed to access an activity, i.e. only people who belong to the required groups etc. This change adds a new API function to return SQL that obtains this list of users, so that it can be combined with other queries.
218 lines
9.5 KiB
PHP
218 lines
9.5 KiB
PHP
<?php
|
|
// This file is part of Moodle - http://moodle.org/
|
|
//
|
|
// Moodle is free software: you can redistribute it and/or modify
|
|
// it under the terms of the GNU General Public License as published by
|
|
// the Free Software Foundation, either version 3 of the License, or
|
|
// (at your option) any later version.
|
|
//
|
|
// Moodle is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
// GNU General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU General Public License
|
|
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
/**
|
|
* Node (base class) used to construct a tree of availability conditions.
|
|
*
|
|
* @package core_availability
|
|
* @copyright 2014 The Open University
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
*/
|
|
|
|
namespace core_availability;
|
|
|
|
defined('MOODLE_INTERNAL') || die();
|
|
|
|
/**
|
|
* Node (base class) used to construct a tree of availability conditions.
|
|
*
|
|
* @package core_availability
|
|
* @copyright 2014 The Open University
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
*/
|
|
abstract class tree_node {
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param bool $not Set true if we are inverting the condition
|
|
* @param \core_availability\info $info Item we're checking
|
|
* @param bool $grabthelot Performance 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)
|
|
* @param int $userid User ID to check availability for
|
|
* @return result Availability check result
|
|
*/
|
|
public abstract function check_available($not,
|
|
\core_availability\info $info, $grabthelot, $userid);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param bool $not Set true if we are inverting the condition
|
|
* @return bool True if condition will return available for everyone
|
|
*/
|
|
public abstract function is_available_for_all($not = false);
|
|
|
|
/**
|
|
* Saves tree data back to a structure object.
|
|
*
|
|
* @return \stdClass Structure object (ready to be made into JSON format)
|
|
*/
|
|
public abstract function save();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param string $restoreid Restore ID
|
|
* @param int $courseid ID of target course
|
|
* @param \base_logger $logger Logger for any warnings
|
|
* @param string $name Name of this item (for use in warning messages)
|
|
* @return bool True if there was any change
|
|
*/
|
|
public function update_after_restore($restoreid, $courseid, \base_logger $logger, $name) {
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Updates this node if it contains any references (dependencies) to the
|
|
* given table and id.
|
|
*
|
|
* @param string $table Table name e.g. 'course_modules'
|
|
* @param int $oldid Previous ID
|
|
* @param int $newid New ID
|
|
* @return bool True if it changed, otherwise false
|
|
*/
|
|
public abstract function update_dependency_id($table, $oldid, $newid);
|
|
|
|
/**
|
|
* 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 bool True if this condition applies to user lists
|
|
*/
|
|
public function is_applied_to_user_lists() {
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Tests this condition against a user list. Users who do not meet the
|
|
* condition will be removed from the list.
|
|
*
|
|
* 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.
|
|
*
|
|
* @param array $users Array of userid => object
|
|
* @param bool $not True if this condition is applying in negative mode
|
|
* @param \core_availability\info $info Item we're checking
|
|
* @param capability_checker $checker
|
|
* @return array Filtered version of input array
|
|
* @throws \coding_exception If called on a condition that doesn't apply to user lists
|
|
*/
|
|
public function filter_user_list(array $users, $not,
|
|
\core_availability\info $info, capability_checker $checker) {
|
|
throw new \coding_exception('Not implemented (do not call unless '.
|
|
'is_applied_to_user_lists is true)');
|
|
}
|
|
|
|
/**
|
|
* 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 filteres 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()).
|
|
*
|
|
* @param bool $not True if this condition is applying in negative mode
|
|
* @param \core_availability\info $info Item we're checking
|
|
* @param bool $onlyactive If true, only returns active enrolments
|
|
* @return array Array with two elements: SQL subquery and parameters array
|
|
* @throws \coding_exception If called on a condition that doesn't apply to user lists
|
|
*/
|
|
public function get_user_list_sql($not, \core_availability\info $info, $onlyactive) {
|
|
if (!$this->is_applied_to_user_lists()) {
|
|
throw new \coding_exception('Not implemented (do not call unless '.
|
|
'is_applied_to_user_lists is true)');
|
|
}
|
|
|
|
// Handle situation where plugin does not implement this, by returning a
|
|
// default (all enrolled users). This ensures compatibility with 2.7
|
|
// plugins and behaviour. Plugins should be updated to support this
|
|
// new function (if they return true to is_applied_to_user_lists).
|
|
debugging('Availability plugins that return true to is_applied_to_user_lists ' .
|
|
'should also now implement get_user_list_sql: ' . get_class($this),
|
|
DEBUG_DEVELOPER);
|
|
return get_enrolled_sql($info->get_context(), '', 0, $onlyactive);
|
|
}
|
|
|
|
/**
|
|
* Utility function for generating SQL parameters (because we can't use ?
|
|
* parameters because get_enrolled_sql has infected us with horrible named
|
|
* parameters).
|
|
*
|
|
* @param array $params Params array (value will be added to this array)
|
|
* @param string|int $value Value
|
|
* @return SQL code for the parameter, e.g. ':pr1234'
|
|
*/
|
|
protected static function unique_sql_parameter(array &$params, $value) {
|
|
static $count = 1;
|
|
$unique = 'usp' . $count;
|
|
$params[$unique] = $value;
|
|
$count++;
|
|
return ':' . $unique;
|
|
}
|
|
}
|