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