MDL-44725 Availability: Add SQL feature for user lists (11)

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.
2014-09-02 13:03:29 +01:00
parent c13ac85db8
commit 1a7049af22
13 changed files with 549 additions and 20 deletions
@@ -159,4 +159,60 @@ abstract class tree_node {
        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;
+    }
 }