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