cohort/externallib.php

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