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