MDL-51568 self_enrol: New Web Service enrol_self_enrol_user
[moodle.git] / enrol / self / externallib.php
index 4451087..ad61b0c 100644 (file)
@@ -97,4 +97,158 @@ class enrol_self_external extends external_api {
             )
         );
     }
             )
         );
     }
+
+    /**
+     * Returns description of method parameters
+     *
+     * @return external_function_parameters
+     * @since Moodle 3.0
+     */
+    public static function enrol_user_parameters() {
+        return new external_function_parameters(
+            array(
+                'courseid' => new external_value(PARAM_INT, 'Id of the course'),
+                'password' => new external_value(PARAM_RAW, 'Enrolment key', VALUE_DEFAULT, ''),
+                'instanceid' => new external_value(PARAM_INT, 'Instance id of self enrolment plugin.', VALUE_DEFAULT, 0)
+            )
+        );
+    }
+
+    /**
+     * Self enrol the current user in the given course.
+     *
+     * @param int $courseid id of course
+     * @param string $password enrolment key
+     * @param int $instanceid instance id of self enrolment plugin
+     * @return array of warnings and status result
+     * @since Moodle 3.0
+     * @throws moodle_exception
+     */
+    public static function enrol_user($courseid, $password = '', $instanceid = 0) {
+        global $CFG;
+
+        require_once($CFG->libdir . '/enrollib.php');
+
+        $params = self::validate_parameters(self::enrol_user_parameters(),
+                                            array(
+                                                'courseid' => $courseid,
+                                                'password' => $password,
+                                                'instanceid' => $instanceid
+                                            ));
+
+        $warnings = array();
+
+        $course = get_course($params['courseid']);
+        $context = context_course::instance($course->id);
+        // Note that we can't use validate_context because the user is not enrolled in the course.
+        require_login(null, false, null, false, true);
+
+        if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $context)) {
+            throw new moodle_exception('coursehidden');
+        }
+
+        // Retrieve the self enrolment plugin.
+        $enrol = enrol_get_plugin('self');
+        if (empty($enrol)) {
+            throw new moodle_exception('canntenrol', 'enrol_self');
+        }
+
+        // We can expect multiple self-enrolment instances.
+        $instances = array();
+        $enrolinstances = enrol_get_instances($course->id, true);
+        foreach ($enrolinstances as $courseenrolinstance) {
+            if ($courseenrolinstance->enrol == "self") {
+                // Instance specified.
+                if (!empty($params['instanceid'])) {
+                    if ($courseenrolinstance->id == $params['instanceid']) {
+                        $instances[] = $courseenrolinstance;
+                        break;
+                    }
+                } else {
+                    $instances[] = $courseenrolinstance;
+                }
+
+            }
+        }
+        if (empty($instances)) {
+            throw new moodle_exception('canntenrol', 'enrol_self');
+        }
+
+        // Try to enrol the user in the instance/s.
+        $enrolled = false;
+        foreach ($instances as $instance) {
+            $enrolstatus = $enrol->can_self_enrol($instance);
+            if ($enrolstatus === true) {
+                if ($instance->password and $params['password'] !== $instance->password) {
+
+                    // Check if we are using group enrolment keys.
+                    if ($instance->customint1) {
+                        require_once($CFG->dirroot . "/enrol/self/locallib.php");
+
+                        if (!enrol_self_check_group_enrolment_key($course->id, $params['password'])) {
+                            $warnings[] = array(
+                                'item' => 'instance',
+                                'itemid' => $instance->id,
+                                'warningcode' => '2',
+                                'message' => get_string('passwordinvalid', 'enrol_self')
+                            );
+                            continue;
+                        }
+                    } else {
+                        if ($enrol->get_config('showhint')) {
+                            $hint = core_text::substr($instance->password, 0, 1);
+                            $warnings[] = array(
+                                'item' => 'instance',
+                                'itemid' => $instance->id,
+                                'warningcode' => '3',
+                                'message' => s(get_string('passwordinvalidhint', 'enrol_self', $hint)) // message is PARAM_TEXT.
+                            );
+                            continue;
+                        } else {
+                            $warnings[] = array(
+                                'item' => 'instance',
+                                'itemid' => $instance->id,
+                                'warningcode' => '4',
+                                'message' => get_string('passwordinvalid', 'enrol_self')
+                            );
+                            continue;
+                        }
+                    }
+                }
+
+                // Do the enrolment.
+                $data = array('enrolpassword' => $params['password']);
+                $enrol->enrol_self($instance, (object) $data);
+                $enrolled = true;
+                break;
+            } else {
+                $warnings[] = array(
+                    'item' => 'instance',
+                    'itemid' => $instance->id,
+                    'warningcode' => '1',
+                    'message' => $enrolstatus
+                );
+            }
+        }
+
+        $result = array();
+        $result['status'] = $enrolled;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Returns description of method result value
+     *
+     * @return external_description
+     * @since Moodle 3.0
+     */
+    public static function enrol_user_returns() {
+        return new external_single_structure(
+            array(
+                'status' => new external_value(PARAM_BOOL, 'status: true if the user is enrolled, false otherwise'),
+                'warnings' => new external_warnings()
+            )
+        );
+    }
 }
 }