MDL-59366 core: New enrolid param for get_enrolled_* functions

* New optional parameter $enrolid for the following functions:
  - get_enrolled_join()
  - get_enrolled_sql()
  - get_enrolled_with_capabilities_join()
  Setting this parameter to a non-zero value will add a condition
  to the query such that only users that were enrolled with this
  enrolment method will be returned.

Part of MDL-59290.

diff --git a/lib/enrollib.php b/lib/enrollib.php
index 93f67dc..7f81f17 100644 (file)
--- a/lib/enrollib.php
+++ b/lib/enrollib.php
@@ -1209,15 +1209,16 @@ function is_enrolled(context $context, $user = null, $withcapability = '', $only
  * @param int $group optional, 0 indicates no current group, otherwise the group id
  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
  * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
+ * @param int $enrolid The enrolment ID. If not 0, only users enrolled using this enrolment method will be returned.
  * @return \core\dml\sql_join Contains joins, wheres, params
  */
 function get_enrolled_with_capabilities_join(context $context, $prefix = '', $capability = '', $group = 0,
-        $onlyactive = false, $onlysuspended = false) {
+        $onlyactive = false, $onlysuspended = false, $enrolid = 0) {
     $uid = $prefix . 'u.id';
     $joins = array();
     $wheres = array();
 
-    $enrolledjoin = get_enrolled_join($context, $uid, $onlyactive, $onlysuspended);
+    $enrolledjoin = get_enrolled_join($context, $uid, $onlyactive, $onlysuspended, $enrolid);
     $joins[] = $enrolledjoin->joins;
     $wheres[] = $enrolledjoin->wheres;
     $params = $enrolledjoin->params;
@@ -1253,9 +1254,11 @@ function get_enrolled_with_capabilities_join(context $context, $prefix = '', $ca
  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
  * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
+ * @param int $enrolid The enrolment ID. If not 0, only users enrolled using this enrolment method will be returned.
  * @return array list($sql, $params)
  */
-function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false, $onlysuspended = false) {
+function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false, $onlysuspended = false,
+                          $enrolid = 0) {
 
     // Use unique prefix just in case somebody makes some SQL magic with the result.
     static $i = 0;
@@ -1263,7 +1266,7 @@ function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0,
     $prefix = 'eu' . $i . '_';
 
     $capjoin = get_enrolled_with_capabilities_join(
-            $context, $prefix, $withcapability, $groupid, $onlyactive, $onlysuspended);
+            $context, $prefix, $withcapability, $groupid, $onlyactive, $onlysuspended, $enrolid);
 
     $sql = "SELECT DISTINCT {$prefix}u.id
               FROM {user} {$prefix}u
@@ -1285,9 +1288,10 @@ function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0,
  * @param string $useridcolumn User id column used the calling query, e.g. u.id
  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
  * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
+ * @param int $enrolid The enrolment ID. If not 0, only users enrolled using this enrolment method will be returned.
  * @return \core\dml\sql_join Contains joins, wheres, params
  */
-function get_enrolled_join(context $context, $useridcolumn, $onlyactive = false, $onlysuspended = false) {
+function get_enrolled_join(context $context, $useridcolumn, $onlyactive = false, $onlysuspended = false, $enrolid = 0) {
     // Use unique prefix just in case somebody makes some SQL magic with the result.
     static $i = 0;
     $i++;
@@ -1315,7 +1319,18 @@ function get_enrolled_join(context $context, $useridcolumn, $onlyactive = false,
     if (!$isfrontpage) {
         $where1 = "{$prefix}ue.status = :{$prefix}active AND {$prefix}e.status = :{$prefix}enabled";
         $where2 = "{$prefix}ue.timestart < :{$prefix}now1 AND ({$prefix}ue.timeend = 0 OR {$prefix}ue.timeend > :{$prefix}now2)";
-        $ejoin = "JOIN {enrol} {$prefix}e ON ({$prefix}e.id = {$prefix}ue.enrolid AND {$prefix}e.courseid = :{$prefix}courseid)";
+
+        $enrolconditions = array(
+            "{$prefix}e.id = {$prefix}ue.enrolid",
+            "{$prefix}e.courseid = :{$prefix}courseid",
+        );
+        if ($enrolid) {
+            $enrolconditions[] = "{$prefix}e.id = :{$prefix}enrolid";
+            $params[$prefix . 'enrolid'] = $enrolid;
+        }
+        $enrolconditionssql = implode(" AND ", $enrolconditions);
+        $ejoin = "JOIN {enrol} {$prefix}e ON ($enrolconditionssql)";
+
         $params[$prefix.'courseid'] = $coursecontext->instanceid;
 
         if (!$onlysuspended) {
@@ -1329,8 +1344,16 @@ function get_enrolled_join(context $context, $useridcolumn, $onlyactive = false,
             // Consider multiple enrols where one is not suspended or plain role_assign.
             $enrolselect = "SELECT DISTINCT {$prefix}ue.userid FROM {user_enrolments} {$prefix}ue $ejoin WHERE $where1 AND $where2";
             $joins[] = "JOIN {user_enrolments} {$prefix}ue1 ON {$prefix}ue1.userid = $useridcolumn";
-            $joins[] = "JOIN {enrol} {$prefix}e1 ON ({$prefix}e1.id = {$prefix}ue1.enrolid
-                    AND {$prefix}e1.courseid = :{$prefix}_e1_courseid)";
+            $enrolconditions = array(
+                "{$prefix}e1.id = {$prefix}ue1.enrolid",
+                "{$prefix}e1.courseid = :{$prefix}_e1_courseid",
+            );
+            if ($enrolid) {
+                $enrolconditions[] = "{$prefix}e1.id = :{$prefix}e1.enrolid";
+                $params[$prefix . 'e1.enrolid'] = $enrolid;
+            }
+            $enrolconditionssql = implode(" AND ", $enrolconditions);
+            $joins[] = "JOIN {enrol} {$prefix}e1 ON ($enrolconditionssql)";
             $params["{$prefix}_e1_courseid"] = $coursecontext->instanceid;
             $wheres[] = "$useridcolumn NOT IN ($enrolselect)";
         }

diff --git a/lib/upgrade.txt b/lib/upgrade.txt
index ea0eace..ff60008 100644 (file)
--- a/lib/upgrade.txt
+++ b/lib/upgrade.txt
@@ -32,6 +32,12 @@ information provided here is intended especially for developers.
   These attributes enable enrol actions to be rendered via modals. If not added, clicking on the enrolment action buttons will still
   redirect the user to the appropriate enrolment action page. Though optional, it is recommended to add these attributes for a
   better user experience when performing enrol actions.
+* New optional parameter $enrolid for the following functions:
+  - get_enrolled_join()
+  - get_enrolled_sql()
+  - get_enrolled_with_capabilities_join()
+  Setting this parameter to a non-zero value will add a condition to the query such that only users that were enrolled
+  with this enrolment method will be returned.
 
 === 3.3.1 ===