[Summary view]

Differences Between: [Versions 39 and 402] [Versions 39 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  /**
  18   * External cohort API
  19   *
  20   * @package    core_cohort
  21   * @category   external
  22   * @copyright  MediaTouch 2000 srl
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  require_once("$CFG->libdir/externallib.php");
  29  
  30  class core_cohort_external extends external_api {
  31  
  32      /**
  33       * Returns description of method parameters
  34       *
  35       * @return external_function_parameters
  36       * @since Moodle 2.5
  37       */
  38      public static function create_cohorts_parameters() {
  39          return new external_function_parameters(
  40              array(
  41                  'cohorts' => new external_multiple_structure(
  42                      new external_single_structure(
  43                          array(
  44                              'categorytype' => new external_single_structure(
  45                                  array(
  46                                      'type' => new external_value(PARAM_TEXT, 'the name of the field: id (numeric value
  47                                          of course category id) or idnumber (alphanumeric value of idnumber course category)
  48                                          or system (value ignored)'),
  49                                      'value' => new external_value(PARAM_RAW, 'the value of the categorytype')
  50                                  )
  51                              ),
  52                              'name' => new external_value(PARAM_RAW, 'cohort name'),
  53                              'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
  54                              'description' => new external_value(PARAM_RAW, 'cohort description', VALUE_OPTIONAL),
  55                              'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
  56                              'visible' => new external_value(PARAM_BOOL, 'cohort visible', VALUE_OPTIONAL, true),
  57                              'theme' => new external_value(PARAM_THEME,
  58                                  'the cohort theme. The allowcohortthemes setting must be enabled on Moodle',
  59                                  VALUE_OPTIONAL
  60                              ),
  61                          )
  62                      )
  63                  )
  64              )
  65          );
  66      }
  67  
  68      /**
  69       * Create one or more cohorts
  70       *
  71       * @param array $cohorts An array of cohorts to create.
  72       * @return array An array of arrays
  73       * @since Moodle 2.5
  74       */
  75      public static function create_cohorts($cohorts) {
  76          global $CFG, $DB;
  77          require_once("$CFG->dirroot/cohort/lib.php");
  78  
  79          $params = self::validate_parameters(self::create_cohorts_parameters(), array('cohorts' => $cohorts));
  80  
  81          $availablethemes = cohort_get_list_of_themes();
  82  
  83          $transaction = $DB->start_delegated_transaction();
  84  
  85          $syscontext = context_system::instance();
  86          $cohortids = array();
  87  
  88          foreach ($params['cohorts'] as $cohort) {
  89              $cohort = (object)$cohort;
  90  
  91              // Category type (context id).
  92              $categorytype = $cohort->categorytype;
  93              if (!in_array($categorytype['type'], array('idnumber', 'id', 'system'))) {
  94                  throw new invalid_parameter_exception('category type must be id, idnumber or system:' . $categorytype['type']);
  95              }
  96              if ($categorytype['type'] === 'system') {
  97                  $cohort->contextid = $syscontext->id;
  98              } else if ($catid = $DB->get_field('course_categories', 'id', array($categorytype['type'] => $categorytype['value']))) {
  99                  $catcontext = context_coursecat::instance($catid);
 100                  $cohort->contextid = $catcontext->id;
 101              } else {
 102                  throw new invalid_parameter_exception('category not exists: category '
 103                      .$categorytype['type'].' = '.$categorytype['value']);
 104              }
 105              // Make sure that the idnumber doesn't already exist.
 106              if ($DB->record_exists('cohort', array('idnumber' => $cohort->idnumber))) {
 107                  throw new invalid_parameter_exception('record already exists: idnumber='.$cohort->idnumber);
 108              }
 109              $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 110              if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 111                  throw new invalid_parameter_exception('Invalid context');
 112              }
 113              self::validate_context($context);
 114              require_capability('moodle/cohort:manage', $context);
 115  
 116              // Make sure theme is valid.
 117              if (isset($cohort->theme)) {
 118                  if (!empty($CFG->allowcohortthemes)) {
 119                      if (empty($availablethemes[$cohort->theme])) {
 120                          throw new moodle_exception('errorinvalidparam', 'webservice', '', 'theme');
 121                      }
 122                  }
 123              }
 124  
 125              // Validate format.
 126              $cohort->descriptionformat = external_validate_format($cohort->descriptionformat);
 127              $cohort->id = cohort_add_cohort($cohort);
 128  
 129              list($cohort->description, $cohort->descriptionformat) =
 130                  external_format_text($cohort->description, $cohort->descriptionformat,
 131                          $context->id, 'cohort', 'description', $cohort->id);
 132              $cohortids[] = (array)$cohort;
 133          }
 134          $transaction->allow_commit();
 135  
 136          return $cohortids;
 137      }
 138  
 139      /**
 140       * Returns description of method result value
 141       *
 142       * @return external_description
 143       * @since Moodle 2.5
 144       */
 145      public static function create_cohorts_returns() {
 146          return new external_multiple_structure(
 147              new external_single_structure(
 148                  array(
 149                      'id' => new external_value(PARAM_INT, 'cohort id'),
 150                      'name' => new external_value(PARAM_RAW, 'cohort name'),
 151                      'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
 152                      'description' => new external_value(PARAM_RAW, 'cohort description'),
 153                      'descriptionformat' => new external_format_value('description'),
 154                      'visible' => new external_value(PARAM_BOOL, 'cohort visible'),
 155                      'theme' => new external_value(PARAM_THEME, 'cohort theme', VALUE_OPTIONAL),
 156                  )
 157              )
 158          );
 159      }
 160  
 161      /**
 162       * Returns description of method parameters
 163       *
 164       * @return external_function_parameters
 165       * @since Moodle 2.5
 166       */
 167      public static function delete_cohorts_parameters() {
 168          return new external_function_parameters(
 169              array(
 170                  'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'cohort ID')),
 171              )
 172          );
 173      }
 174  
 175      /**
 176       * Delete cohorts
 177       *
 178       * @param array $cohortids
 179       * @return null
 180       * @since Moodle 2.5
 181       */
 182      public static function delete_cohorts($cohortids) {
 183          global $CFG, $DB;
 184          require_once("$CFG->dirroot/cohort/lib.php");
 185  
 186          $params = self::validate_parameters(self::delete_cohorts_parameters(), array('cohortids' => $cohortids));
 187  
 188          $transaction = $DB->start_delegated_transaction();
 189  
 190          foreach ($params['cohortids'] as $cohortid) {
 191              // Validate params.
 192              $cohortid = validate_param($cohortid, PARAM_INT);
 193              $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
 194  
 195              // Now security checks.
 196              $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 197              if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 198                  throw new invalid_parameter_exception('Invalid context');
 199              }
 200              self::validate_context($context);
 201              require_capability('moodle/cohort:manage', $context);
 202              cohort_delete_cohort($cohort);
 203          }
 204          $transaction->allow_commit();
 205  
 206          return null;
 207      }
 208  
 209      /**
 210       * Returns description of method result value
 211       *
 212       * @return null
 213       * @since Moodle 2.5
 214       */
 215      public static function delete_cohorts_returns() {
 216          return null;
 217      }
 218  
 219      /**
 220       * Returns description of method parameters
 221       *
 222       * @return external_function_parameters
 223       * @since Moodle 2.5
 224       */
 225      public static function get_cohorts_parameters() {
 226          return new external_function_parameters(
 227              array(
 228                  'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'Cohort ID')
 229                      , 'List of cohort id. A cohort id is an integer.', VALUE_DEFAULT, array()),
 230              )
 231          );
 232      }
 233  
 234      /**
 235       * Get cohorts definition specified by ids
 236       *
 237       * @param array $cohortids array of cohort ids
 238       * @return array of cohort objects (id, courseid, name)
 239       * @since Moodle 2.5
 240       */
 241      public static function get_cohorts($cohortids = array()) {
 242          global $DB, $CFG;
 243  
 244          $params = self::validate_parameters(self::get_cohorts_parameters(), array('cohortids' => $cohortids));
 245  
 246          if (empty($cohortids)) {
 247              $cohorts = $DB->get_records('cohort');
 248          } else {
 249              $cohorts = $DB->get_records_list('cohort', 'id', $params['cohortids']);
 250          }
 251  
 252          $cohortsinfo = array();
 253          foreach ($cohorts as $cohort) {
 254              // Now security checks.
 255              $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 256              if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 257                  throw new invalid_parameter_exception('Invalid context');
 258              }
 259              self::validate_context($context);
 260              if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) {
 261                  throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', '');
 262              }
 263  
 264              // Only return theme when $CFG->allowcohortthemes is enabled.
 265              if (!empty($cohort->theme) && empty($CFG->allowcohortthemes)) {
 266                  $cohort->theme = null;
 267              }
 268  
 269              list($cohort->description, $cohort->descriptionformat) =
 270                  external_format_text($cohort->description, $cohort->descriptionformat,
 271                          $context->id, 'cohort', 'description', $cohort->id);
 272  
 273              $cohortsinfo[] = (array) $cohort;
 274          }
 275          return $cohortsinfo;
 276      }
 277  
 278  
 279      /**
 280       * Returns description of method result value
 281       *
 282       * @return external_description
 283       * @since Moodle 2.5
 284       */
 285      public static function get_cohorts_returns() {
 286          return new external_multiple_structure(
 287              new external_single_structure(
 288                  array(
 289                      'id' => new external_value(PARAM_INT, 'ID of the cohort'),
 290                      'name' => new external_value(PARAM_RAW, 'cohort name'),
 291                      'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
 292                      'description' => new external_value(PARAM_RAW, 'cohort description'),
 293                      'descriptionformat' => new external_format_value('description'),
 294                      'visible' => new external_value(PARAM_BOOL, 'cohort visible'),
 295                      'theme' => new external_value(PARAM_THEME, 'cohort theme', VALUE_OPTIONAL),
 296                  )
 297              )
 298          );
 299      }
 300  
 301      /**
 302       * Returns the description of external function parameters.
 303       *
 304       * @return external_function_parameters
 305       */
 306      public static function search_cohorts_parameters() {
 307          $query = new external_value(
 308              PARAM_RAW,
 309              'Query string'
 310          );
 311          $includes = new external_value(
 312              PARAM_ALPHA,
 313              'What other contexts to fetch the frameworks from. (all, parents, self)',
 314              VALUE_DEFAULT,
 315              'parents'
 316          );
 317          $limitfrom = new external_value(
 318              PARAM_INT,
 319              'limitfrom we are fetching the records from',
 320              VALUE_DEFAULT,
 321              0
 322          );
 323          $limitnum = new external_value(
 324              PARAM_INT,
 325              'Number of records to fetch',
 326              VALUE_DEFAULT,
 327              25
 328          );
 329          return new external_function_parameters(array(
 330              'query' => $query,
 331              'context' => self::get_context_parameters(),
 332              'includes' => $includes,
 333              'limitfrom' => $limitfrom,
 334              'limitnum' => $limitnum
 335          ));
 336      }
 337  
 338      /**
 339       * Search cohorts.
 340       *
 341       * @param string $query
 342       * @param array $context
 343       * @param string $includes
 344       * @param int $limitfrom
 345       * @param int $limitnum
 346       * @return array
 347       */
 348      public static function search_cohorts($query, $context, $includes = 'parents', $limitfrom = 0, $limitnum = 25) {
 349          global $CFG;
 350          require_once($CFG->dirroot . '/cohort/lib.php');
 351  
 352          $params = self::validate_parameters(self::search_cohorts_parameters(), array(
 353              'query' => $query,
 354              'context' => $context,
 355              'includes' => $includes,
 356              'limitfrom' => $limitfrom,
 357              'limitnum' => $limitnum,
 358          ));
 359          $query = $params['query'];
 360          $includes = $params['includes'];
 361          $context = self::get_context_from_params($params['context']);
 362          $limitfrom = $params['limitfrom'];
 363          $limitnum = $params['limitnum'];
 364  
 365          self::validate_context($context);
 366  
 367          $manager = has_capability('moodle/cohort:manage', $context);
 368          if (!$manager) {
 369              require_capability('moodle/cohort:view', $context);
 370          }
 371  
 372          // TODO Make this more efficient.
 373          if ($includes == 'self') {
 374              $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
 375              $results = $results['cohorts'];
 376          } else if ($includes == 'parents') {
 377              $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
 378              $results = $results['cohorts'];
 379              if (!$context instanceof context_system) {
 380                  $results = array_merge($results, cohort_get_available_cohorts($context, COHORT_ALL, $limitfrom, $limitnum, $query));
 381              }
 382          } else if ($includes == 'all') {
 383              $results = cohort_get_all_cohorts($limitfrom, $limitnum, $query);
 384              $results = $results['cohorts'];
 385          } else {
 386              throw new coding_exception('Invalid parameter value for \'includes\'.');
 387          }
 388  
 389          $cohorts = array();
 390          foreach ($results as $key => $cohort) {
 391              $cohortcontext = context::instance_by_id($cohort->contextid);
 392  
 393              // Only return theme when $CFG->allowcohortthemes is enabled.
 394              if (!empty($cohort->theme) && empty($CFG->allowcohortthemes)) {
 395                  $cohort->theme = null;
 396              }
 397  
 398              if (!isset($cohort->description)) {
 399                  $cohort->description = '';
 400              }
 401              if (!isset($cohort->descriptionformat)) {
 402                  $cohort->descriptionformat = FORMAT_PLAIN;
 403              }
 404  
 405              list($cohort->description, $cohort->descriptionformat) =
 406                  external_format_text($cohort->description, $cohort->descriptionformat,
 407                          $cohortcontext->id, 'cohort', 'description', $cohort->id);
 408  
 409              $cohorts[$key] = $cohort;
 410          }
 411  
 412          return array('cohorts' => $cohorts);
 413      }
 414  
 415      /**
 416       * Returns description of external function result value.
 417       *
 418       * @return external_description
 419       */
 420      public static function search_cohorts_returns() {
 421          return new external_single_structure(array(
 422              'cohorts' => new external_multiple_structure(
 423                  new external_single_structure(array(
 424                      'id' => new external_value(PARAM_INT, 'ID of the cohort'),
 425                      'name' => new external_value(PARAM_RAW, 'cohort name'),
 426                      'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
 427                      'description' => new external_value(PARAM_RAW, 'cohort description'),
 428                      'descriptionformat' => new external_format_value('description'),
 429                      'visible' => new external_value(PARAM_BOOL, 'cohort visible'),
 430                      'theme' => new external_value(PARAM_THEME, 'cohort theme', VALUE_OPTIONAL),
 431                  ))
 432              )
 433          ));
 434      }
 435  
 436  
 437  
 438      /**
 439       * Returns description of method parameters
 440       *
 441       * @return external_function_parameters
 442       * @since Moodle 2.5
 443       */
 444      public static function update_cohorts_parameters() {
 445          return new external_function_parameters(
 446              array(
 447                  'cohorts' => new external_multiple_structure(
 448                      new external_single_structure(
 449                          array(
 450                              'id' => new external_value(PARAM_INT, 'ID of the cohort'),
 451                              'categorytype' => new external_single_structure(
 452                                  array(
 453                                      'type' => new external_value(PARAM_TEXT, 'the name of the field: id (numeric value
 454                                          of course category id) or idnumber (alphanumeric value of idnumber course category)
 455                                          or system (value ignored)'),
 456                                      'value' => new external_value(PARAM_RAW, 'the value of the categorytype')
 457                                  )
 458                              ),
 459                              'name' => new external_value(PARAM_RAW, 'cohort name'),
 460                              'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
 461                              'description' => new external_value(PARAM_RAW, 'cohort description', VALUE_OPTIONAL),
 462                              'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
 463                              'visible' => new external_value(PARAM_BOOL, 'cohort visible', VALUE_OPTIONAL),
 464                              'theme' => new external_value(PARAM_THEME,
 465                                  'the cohort theme. The allowcohortthemes setting must be enabled on Moodle',
 466                                  VALUE_OPTIONAL
 467                              ),
 468                          )
 469                      )
 470                  )
 471              )
 472          );
 473      }
 474  
 475      /**
 476       * Update cohorts
 477       *
 478       * @param array $cohorts
 479       * @return null
 480       * @since Moodle 2.5
 481       */
 482      public static function update_cohorts($cohorts) {
 483          global $CFG, $DB;
 484          require_once("$CFG->dirroot/cohort/lib.php");
 485  
 486          $params = self::validate_parameters(self::update_cohorts_parameters(), array('cohorts' => $cohorts));
 487  
 488          $availablethemes = cohort_get_list_of_themes();
 489  
 490          $transaction = $DB->start_delegated_transaction();
 491          $syscontext = context_system::instance();
 492  
 493          foreach ($params['cohorts'] as $cohort) {
 494              $cohort = (object) $cohort;
 495  
 496              if (trim($cohort->name) == '') {
 497                  throw new invalid_parameter_exception('Invalid cohort name');
 498              }
 499  
 500              $oldcohort = $DB->get_record('cohort', array('id' => $cohort->id), '*', MUST_EXIST);
 501              $oldcontext = context::instance_by_id($oldcohort->contextid, MUST_EXIST);
 502              require_capability('moodle/cohort:manage', $oldcontext);
 503  
 504              // Category type (context id).
 505              $categorytype = $cohort->categorytype;
 506              if (!in_array($categorytype['type'], array('idnumber', 'id', 'system'))) {
 507                  throw new invalid_parameter_exception('category type must be id, idnumber or system:' . $categorytype['type']);
 508              }
 509              if ($categorytype['type'] === 'system') {
 510                  $cohort->contextid = $syscontext->id;
 511              } else if ($catid = $DB->get_field('course_categories', 'id', array($categorytype['type'] => $categorytype['value']))) {
 512                  $cohort->contextid = $DB->get_field('context', 'id', array('instanceid' => $catid,
 513                      'contextlevel' => CONTEXT_COURSECAT));
 514              } else {
 515                  throw new invalid_parameter_exception('category not exists: category='.$categorytype['value']);
 516              }
 517  
 518              if ($cohort->contextid != $oldcohort->contextid) {
 519                  $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 520                  if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 521                      throw new invalid_parameter_exception('Invalid context');
 522                  }
 523  
 524                  self::validate_context($context);
 525                  require_capability('moodle/cohort:manage', $context);
 526              }
 527  
 528              // Make sure theme is valid.
 529              if (!empty($cohort->theme) && !empty($CFG->allowcohortthemes)) {
 530                  if (empty($availablethemes[$cohort->theme])) {
 531                      $debuginfo = 'The following cohort theme is not installed on this site: '.$cohort->theme;
 532                      throw new moodle_exception('errorinvalidparam', 'webservice', '', 'theme', $debuginfo);
 533                  }
 534              }
 535  
 536              if (!empty($cohort->description)) {
 537                  $cohort->descriptionformat = external_validate_format($cohort->descriptionformat);
 538              }
 539  
 540              cohort_update_cohort($cohort);
 541          }
 542  
 543          $transaction->allow_commit();
 544  
 545          return null;
 546      }
 547  
 548      /**
 549       * Returns description of method result value
 550       *
 551       * @return null
 552       * @since Moodle 2.5
 553       */
 554      public static function update_cohorts_returns() {
 555          return null;
 556      }
 557  
 558      /**
 559       * Returns description of method parameters
 560       *
 561       * @return external_function_parameters
 562       * @since Moodle 2.5
 563       */
 564      public static function add_cohort_members_parameters() {
 565          return new external_function_parameters (
 566              array(
 567                  'members' => new external_multiple_structure (
 568                      new external_single_structure (
 569                          array (
 570                              'cohorttype' => new external_single_structure (
 571                                  array(
 572                                      'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the field: id
 573                                          (numeric value of cohortid) or idnumber (alphanumeric value of idnumber) '),
 574                                      'value' => new external_value(PARAM_RAW, 'The value of the cohort')
 575                                  )
 576                              ),
 577                              'usertype' => new external_single_structure (
 578                                  array(
 579                                      'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the field: id
 580                                          (numeric value of id) or username (alphanumeric value of username) '),
 581                                      'value' => new external_value(PARAM_RAW, 'The value of the cohort')
 582                                  )
 583                              )
 584                          )
 585                      )
 586                  )
 587              )
 588          );
 589      }
 590  
 591      /**
 592       * Add cohort members
 593       *
 594       * @param array $members of arrays with keys userid, cohortid
 595       * @since Moodle 2.5
 596       */
 597      public static function add_cohort_members($members) {
 598          global $CFG, $DB;
 599          require_once($CFG->dirroot."/cohort/lib.php");
 600  
 601          $params = self::validate_parameters(self::add_cohort_members_parameters(), array('members' => $members));
 602  
 603          $transaction = $DB->start_delegated_transaction();
 604          $warnings = array();
 605          foreach ($params['members'] as $member) {
 606              // Cohort parameters.
 607              $cohorttype = $member['cohorttype'];
 608              $cohortparam = array($cohorttype['type'] => $cohorttype['value']);
 609              // User parameters.
 610              $usertype = $member['usertype'];
 611              $userparam = array($usertype['type'] => $usertype['value']);
 612              try {
 613                  // Check parameters.
 614                  if ($cohorttype['type'] != 'id' && $cohorttype['type'] != 'idnumber') {
 615                      $warning = array();
 616                      $warning['warningcode'] = '1';
 617                      $warning['message'] = 'invalid parameter: cohortype='.$cohorttype['type'];
 618                      $warnings[] = $warning;
 619                      continue;
 620                  }
 621                  if ($usertype['type'] != 'id' && $usertype['type'] != 'username') {
 622                      $warning = array();
 623                      $warning['warningcode'] = '1';
 624                      $warning['message'] = 'invalid parameter: usertype='.$usertype['type'];
 625                      $warnings[] = $warning;
 626                      continue;
 627                  }
 628                  // Extract parameters.
 629                  if (!$cohortid = $DB->get_field('cohort', 'id', $cohortparam)) {
 630                      $warning = array();
 631                      $warning['warningcode'] = '2';
 632                      $warning['message'] = 'cohort '.$cohorttype['type'].'='.$cohorttype['value'].' not exists';
 633                      $warnings[] = $warning;
 634                      continue;
 635                  }
 636                  if (!$userid = $DB->get_field('user', 'id', array_merge($userparam, array('deleted' => 0,
 637                      'mnethostid' => $CFG->mnet_localhost_id)))) {
 638                      $warning = array();
 639                      $warning['warningcode'] = '2';
 640                      $warning['message'] = 'user '.$usertype['type'].'='.$usertype['value'].' not exists';
 641                      $warnings[] = $warning;
 642                      continue;
 643                  }
 644                  if ($DB->record_exists('cohort_members', array('cohortid' => $cohortid, 'userid' => $userid))) {
 645                      $warning = array();
 646                      $warning['warningcode'] = '3';
 647                      $warning['message'] = 'record already exists: cohort('.$cohorttype['type'].'='.$cohorttype['value'].' '.
 648                          $usertype['type'].'='.$usertype['value'].')';
 649                      $warnings[] = $warning;
 650                      continue;
 651                  }
 652                  $cohort = $DB->get_record('cohort', array('id'=>$cohortid), '*', MUST_EXIST);
 653                  $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 654                  if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 655                      $warning = array();
 656                      $warning['warningcode'] = '1';
 657                      $warning['message'] = 'Invalid context: '.$context->contextlevel;
 658                      $warnings[] = $warning;
 659                      continue;
 660                  }
 661                  self::validate_context($context);
 662              } catch (Exception $e) {
 663                  throw new moodle_exception('Error', 'cohort', '', $e->getMessage());
 664              }
 665              if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) {
 666                  throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', '');
 667              }
 668              cohort_add_member($cohortid, $userid);
 669          }
 670          $transaction->allow_commit();
 671          // Return.
 672          $result = array();
 673          $result['warnings'] = $warnings;
 674          return $result;
 675      }
 676  
 677      /**
 678       * Returns description of method result value
 679       *
 680       * @return null
 681       * @since Moodle 2.5
 682       */
 683      public static function add_cohort_members_returns() {
 684          return new external_single_structure(
 685              array(
 686                  'warnings' => new external_warnings()
 687              )
 688          );
 689      }
 690  
 691      /**
 692       * Returns description of method parameters
 693       *
 694       * @return external_function_parameters
 695       * @since Moodle 2.5
 696       */
 697      public static function delete_cohort_members_parameters() {
 698          return new external_function_parameters(
 699              array(
 700                  'members' => new external_multiple_structure(
 701                      new external_single_structure(
 702                          array(
 703                              'cohortid' => new external_value(PARAM_INT, 'cohort record id'),
 704                              'userid' => new external_value(PARAM_INT, 'user id'),
 705                          )
 706                      )
 707                  )
 708              )
 709          );
 710      }
 711  
 712      /**
 713       * Delete cohort members
 714       *
 715       * @param array $members of arrays with keys userid, cohortid
 716       * @since Moodle 2.5
 717       */
 718      public static function delete_cohort_members($members) {
 719          global $CFG, $DB;
 720          require_once("$CFG->dirroot/cohort/lib.php");
 721  
 722          // Validate parameters.
 723          $params = self::validate_parameters(self::delete_cohort_members_parameters(), array('members' => $members));
 724  
 725          $transaction = $DB->start_delegated_transaction();
 726  
 727          foreach ($params['members'] as $member) {
 728              $cohortid = $member['cohortid'];
 729              $userid = $member['userid'];
 730  
 731              $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
 732              $user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0, 'mnethostid' => $CFG->mnet_localhost_id),
 733                  '*', MUST_EXIST);
 734  
 735              // Now security checks.
 736              $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 737              if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 738                  throw new invalid_parameter_exception('Invalid context');
 739              }
 740              self::validate_context($context);
 741              if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) {
 742                  throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', '');
 743              }
 744  
 745              cohort_remove_member($cohort->id, $user->id);
 746          }
 747          $transaction->allow_commit();
 748      }
 749  
 750      /**
 751       * Returns description of method result value
 752       *
 753       * @return null
 754       * @since Moodle 2.5
 755       */
 756      public static function delete_cohort_members_returns() {
 757          return null;
 758      }
 759  
 760      /**
 761       * Returns description of method parameters
 762       *
 763       * @return external_function_parameters
 764       * @since Moodle 2.5
 765       */
 766      public static function get_cohort_members_parameters() {
 767          return new external_function_parameters(
 768              array(
 769                  'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'Cohort ID')),
 770              )
 771          );
 772      }
 773  
 774      /**
 775       * Return all members for a cohort
 776       *
 777       * @param array $cohortids array of cohort ids
 778       * @return array with cohort id keys containing arrays of user ids
 779       * @since Moodle 2.5
 780       */
 781      public static function get_cohort_members($cohortids) {
 782          global $DB;
 783          $params = self::validate_parameters(self::get_cohort_members_parameters(), array('cohortids' => $cohortids));
 784  
 785          $members = array();
 786  
 787          foreach ($params['cohortids'] as $cohortid) {
 788              // Validate params.
 789              $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
 790              // Now security checks.
 791              $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
 792              if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
 793                  throw new invalid_parameter_exception('Invalid context');
 794              }
 795              self::validate_context($context);
 796              if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) {
 797                  throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', '');
 798              }
 799  
 800              $cohortmembers = $DB->get_records_sql("SELECT u.id FROM {user} u, {cohort_members} cm
 801                  WHERE u.id = cm.userid AND cm.cohortid = ?
 802                  ORDER BY lastname ASC, firstname ASC", array($cohort->id));
 803              $members[] = array('cohortid' => $cohortid, 'userids' => array_keys($cohortmembers));
 804          }
 805          return $members;
 806      }
 807  
 808      /**
 809       * Returns description of method result value
 810       *
 811       * @return external_description
 812       * @since Moodle 2.5
 813       */
 814      public static function get_cohort_members_returns() {
 815          return new external_multiple_structure(
 816              new external_single_structure(
 817                  array(
 818                      'cohortid' => new external_value(PARAM_INT, 'cohort record id'),
 819                      'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
 820                  )
 821              )
 822          );
 823      }
 824  }