[Summary view]

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  namespace enrol_meta\external;
  18  
  19  use external_api;
  20  use external_function_parameters;
  21  use external_multiple_structure;
  22  use external_single_structure;
  23  use external_value;
  24  use invalid_parameter_exception;
  25  use context_course;
  26  use moodle_exception;
  27  
  28  /**
  29   * Web service function relating to add enrol meta instances
  30   *
  31   * @package    enrol_meta
  32   * @copyright  2021 WKS KV Bildung
  33   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34   */
  35  class add_instances extends external_api {
  36  
  37      /**
  38       * Parameters for adding meta enrolment instances
  39       *
  40       * @return external_function_parameters
  41       */
  42      public static function execute_parameters(): external_function_parameters {
  43          return new external_function_parameters([
  44              'instances' => new external_multiple_structure(
  45                  new external_single_structure(
  46                      [
  47                          'metacourseid' => new external_value(PARAM_INT, 'ID of the course where meta enrolment is added.'),
  48                          'courseid' => new external_value(PARAM_RAW, 'ID of the course where meta enrolment is linked to.'),
  49                          'creategroup' => new external_value(PARAM_BOOL,
  50                              'Creates group in meta course named after linked course and '
  51                              . 'puts all enrolled users in this group', VALUE_DEFAULT, false),
  52                      ]
  53                  ), 'List of course meta enrolment instances to create.', VALUE_DEFAULT, []
  54              ),
  55          ]);
  56      }
  57  
  58      /**
  59       * Adding meta enrolment instances
  60       *
  61       * @param  array $instances
  62       * @return array
  63       */
  64      public static function execute(array $instances): array {
  65          global $DB;
  66          // Parameter validation.
  67          $params = self::validate_parameters(self::execute_parameters(), [
  68              'instances' => $instances,
  69          ]);
  70  
  71          if (!count($params['instances'])) {
  72              throw new invalid_parameter_exception(get_string('wsnoinstancesspecified', 'enrol_meta'));
  73          }
  74  
  75          $result = [];
  76          foreach ($params['instances'] as $instance) {
  77              // Ensure the metacourse exists.
  78              $metacourserecord = $DB->get_record('course', ['id' => $instance['metacourseid']], 'id,visible');
  79              if (!$metacourserecord) {
  80                  throw new invalid_parameter_exception(get_string('wsinvalidmetacourse', 'enrol_meta', $instance['metacourseid']));
  81              }
  82              // Ensure the current user is allowed to access metacourse.
  83              $contextmeta = context_course::instance($instance['metacourseid'], IGNORE_MISSING);
  84              try {
  85                  self::validate_context($contextmeta);
  86                  require_all_capabilities(['moodle/course:enrolconfig', 'enrol/meta:config'], $contextmeta);
  87              } catch (moodle_exception $e) {
  88                  throw new invalid_parameter_exception(get_string('wsinvalidmetacourse', 'enrol_meta', $instance['metacourseid']));
  89              }
  90  
  91              // Ensure the linked course exists.
  92              $courserecord = $DB->get_record('course', ['id' => $instance['courseid']], 'id,visible');
  93              if (!$courserecord) {
  94                  throw new invalid_parameter_exception(get_string('wsinvalidcourse', 'enrol_meta', $instance['courseid']));
  95              }
  96  
  97              // Ensure the current user is allowed to access linked course.
  98              $context = context_course::instance($instance['courseid'], IGNORE_MISSING);
  99              try {
 100                  self::validate_context($context);
 101                  if (!$courserecord->visible) {
 102                      require_capability('moodle/course:viewhiddencourses', $context);
 103                  }
 104                  require_capability('enrol/meta:selectaslinked', $context);
 105              } catch (moodle_exception $e) {
 106                  throw new invalid_parameter_exception(get_string('wsinvalidcourse', 'enrol_meta', $instance['courseid']));
 107              }
 108  
 109              // Check for existing meta course link.
 110              $enrolrecord = $DB->get_record('enrol',
 111                      ['enrol' => 'meta', 'courseid' => $instance['metacourseid'], 'customint1' => $instance['courseid']]);
 112              if ($enrolrecord) {
 113                  // Link exists.
 114                  $result[] = [
 115                      'metacourseid' => $instance['metacourseid'],
 116                      'courseid' => $instance['courseid'],
 117                      'status' => false,
 118                  ];
 119                  continue;
 120              }
 121  
 122              // Check for permission to create group.
 123              if ($instance['creategroup']) {
 124                  try {
 125                      require_capability('moodle/course:managegroups', $context);
 126                  } catch (moodle_exception $e) {
 127                      throw new invalid_parameter_exception(get_string('wscannotcreategroup', 'enrol_meta', $instance['courseid']));
 128                  }
 129              }
 130  
 131              // Create instance.
 132              $enrolplugin = enrol_get_plugin('meta');
 133              $fields = [
 134                  'customint1' => $instance['courseid'],
 135                  'customint2' => $instance['creategroup'] ? ENROL_META_CREATE_GROUP : 0,
 136              ];
 137              $addresult = $enrolplugin->add_instance($metacourserecord, $fields);
 138              $result[] = [
 139                  'metacourseid' => $instance['metacourseid'],
 140                  'courseid' => $instance['courseid'],
 141                  'status' => (bool) $addresult,
 142              ];
 143          }
 144  
 145          return $result;
 146      }
 147  
 148      /**
 149       * Return for adding enrolment instances.
 150       *
 151       * @return external_multiple_structure
 152       */
 153      public static function execute_returns(): external_multiple_structure {
 154          return new external_multiple_structure(
 155              new external_single_structure(
 156                  [
 157                      'metacourseid' => new external_value(PARAM_INT, 'ID of the course where meta enrolment is added.'),
 158                      'courseid' => new external_value(PARAM_RAW, 'ID of the course where meta enrolment is linked to.'),
 159                      'status' => new external_value(PARAM_BOOL, 'True on success, false if link already exists.'),
 160                  ]
 161              ), 'List of course meta enrolment instances that were created.', VALUE_DEFAULT, []
 162          );
 163      }
 164  }