From bf7ff76bcda81ee20e7341d214dae08515445b95 Mon Sep 17 00:00:00 2001
From: Ilya Tregubov <ilya@moodle.com>
Date: Tue, 1 Aug 2023 11:35:45 +0800
Subject: [PATCH] MDL-43820 enrol: Add method to find plugin enrol instance

When upload courses we need to match instance with provided data.
---
 admin/tool/uploadcourse/classes/course.php | 10 ++--------
 enrol/upgrade.txt                          | 10 ++++++++++
 lib/enrollib.php                           | 13 +++++++++++++
 3 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/admin/tool/uploadcourse/classes/course.php b/admin/tool/uploadcourse/classes/course.php
index 4a785114232..655d75b87e1 100644
--- a/admin/tool/uploadcourse/classes/course.php
+++ b/admin/tool/uploadcourse/classes/course.php
@@ -1022,16 +1022,10 @@ class tool_uploadcourse_course {
         }
 
         $enrolmentplugins = tool_uploadcourse_helper::get_enrolment_plugins();
-        $instances = enrol_get_instances($course->id, false);
         foreach ($enrolmentdata as $enrolmethod => $method) {
 
-            $instance = null;
-            foreach ($instances as $i) {
-                if ($i->enrol == $enrolmethod) {
-                    $instance = $i;
-                    break;
-                }
-            }
+            $plugin = $enrolmentplugins[$enrolmethod];
+            $instance = $plugin->find_instance($method, $course->id);
 
             $todelete = isset($method['delete']) && $method['delete'];
             $todisable = isset($method['disable']) && $method['disable'];
diff --git a/enrol/upgrade.txt b/enrol/upgrade.txt
index 8d193cc614e..801e224bbd2 100644
--- a/enrol/upgrade.txt
+++ b/enrol/upgrade.txt
@@ -1,6 +1,16 @@
 This files describes API changes in /enrol/* - plugins,
 information provided here is intended especially for developers.
 
+=== 4.4 ===
+
+* New find_instance() function has been created. It finds a matching enrolment instance in a given course using provided
+ enrolment data (for example cohort idnumber for cohort enrolment). Defaults to null. Override this function in your
+ enrolment plugin if you want it to be supported in CSV course upload. Please be aware that sometimes it is not possible
+ to uniquely find an instance based on given data. For example lti entolment records do not have any unique data except
+ id in mod_lti_enrol table. Such plugins should not be supported in CSV course upload. The exception is self enrolment
+ plugin since it is already supported in CSV course upload. For self enrolment plugin, find_instance() returns first
+ available instance in the course.
+
 === 4.3 ===
 
 * New is_csv_upload_supported() function has been created. It checks whether enrolment plugin is supported
diff --git a/lib/enrollib.php b/lib/enrollib.php
index 124c424e295..f078b292463 100644
--- a/lib/enrollib.php
+++ b/lib/enrollib.php
@@ -3509,4 +3509,17 @@ abstract class enrol_plugin {
         return null;
     }
 
+    /**
+     * Finds matching instances for a given course.
+     *
+     * @param array $enrolmentdata enrolment data.
+     * @param int $courseid Course ID.
+     * @return stdClass|null Matching instance
+     */
+    public function find_instance(array $enrolmentdata, int $courseid) : ?stdClass {
+
+        // By default, we assume we can't uniquely identify an instance so better not update any.
+        // Plugins can override this if they can uniquely identify an instance.
+        return null;
+    }
 }