weekly release 3.5dev
[moodle.git] / cohort / externallib.php
CommitLineData
088645e2
AB
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
e71687ba
JL
26defined('MOODLE_INTERNAL') || die();
27
088645e2
AB
28require_once("$CFG->libdir/externallib.php");
29
30class core_cohort_external extends external_api {
31
32 /**
33 * Returns description of method parameters
34 *
35 * @return external_function_parameters
66d6221f 36 * @since Moodle 2.5
088645e2
AB
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
66d6221f
DW
47 of course category id) or idnumber (alphanumeric value of idnumber course category)
48 or system (value ignored)'),
088645e2
AB
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),
80f98467 56 'visible' => new external_value(PARAM_BOOL, 'cohort visible', VALUE_OPTIONAL, true),
088645e2
AB
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
66d6221f 69 * @since Moodle 2.5
088645e2
AB
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
66d6221f 79 $syscontext = context_system::instance();
088645e2
AB
80 $cohortids = array();
81
82 foreach ($params['cohorts'] as $cohort) {
83 $cohort = (object)$cohort;
84
85 // Category type (context id).
86 $categorytype = $cohort->categorytype;
66d6221f
DW
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;
088645e2
AB
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);
66d6221f 117 $cohortids[] = (array)$cohort;
088645e2
AB
118 }
119 $transaction->allow_commit();
120
121 return $cohortids;
122 }
123
124 /**
125 * Returns description of method result value
126 *
127 * @return external_description
66d6221f 128 * @since Moodle 2.5
088645e2
AB
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'),
80f98467 139 'visible' => new external_value(PARAM_BOOL, 'cohort visible'),
088645e2
AB
140 )
141 )
142 );
143 }
144
145 /**
146 * Returns description of method parameters
147 *
148 * @return external_function_parameters
66d6221f 149 * @since Moodle 2.5
088645e2
AB
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
66d6221f 164 * @since Moodle 2.5
088645e2
AB
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
66d6221f 197 * @since Moodle 2.5
088645e2
AB
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
66d6221f 207 * @since Moodle 2.5
088645e2
AB
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')
cfd8c0fe 213 , 'List of cohort id. A cohort id is an integer.', VALUE_DEFAULT, array()),
088645e2
AB
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)
66d6221f 223 * @since Moodle 2.5
088645e2 224 */
cfd8c0fe 225 public static function get_cohorts($cohortids = array()) {
088645e2
AB
226 global $DB;
227
228 $params = self::validate_parameters(self::get_cohorts_parameters(), array('cohortids' => $cohortids));
229
cfd8c0fe
KB
230 if (empty($cohortids)) {
231 $cohorts = $DB->get_records('cohort');
232 } else {
233 $cohorts = $DB->get_records_list('cohort', 'id', $params['cohortids']);
234 }
088645e2 235
cfd8c0fe
KB
236 $cohortsinfo = array();
237 foreach ($cohorts as $cohort) {
088645e2
AB
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);
66d6221f
DW
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 }
088645e2
AB
247
248 list($cohort->description, $cohort->descriptionformat) =
249 external_format_text($cohort->description, $cohort->descriptionformat,
250 $context->id, 'cohort', 'description', $cohort->id);
251
cfd8c0fe 252 $cohortsinfo[] = (array) $cohort;
088645e2 253 }
cfd8c0fe 254 return $cohortsinfo;
088645e2
AB
255 }
256
cfd8c0fe 257
088645e2
AB
258 /**
259 * Returns description of method result value
260 *
261 * @return external_description
66d6221f 262 * @since Moodle 2.5
088645e2
AB
263 */
264 public static function get_cohorts_returns() {
265 return new external_multiple_structure(
266 new external_single_structure(
267 array(
fb5ce7d3 268 'id' => new external_value(PARAM_INT, 'ID of the cohort'),
088645e2
AB
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'),
80f98467 273 'visible' => new external_value(PARAM_BOOL, 'cohort visible'),
088645e2
AB
274 )
275 )
276 );
277 }
278
a60e8ba5
DW
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) {
a7648556 327 global $CFG;
a60e8ba5
DW
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);
a60e8ba5
DW
344
345 $manager = has_capability('moodle/cohort:manage', $context);
346 if (!$manager) {
347 require_capability('moodle/cohort:view', $context);
348 }
349
350 // TODO Make this more efficient.
351 if ($includes == 'self') {
352 $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
353 $results = $results['cohorts'];
354 } else if ($includes == 'parents') {
355 $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
356 $results = $results['cohorts'];
357 if (!$context instanceof context_system) {
358 $results = array_merge($results, cohort_get_available_cohorts($context, COHORT_ALL, $limitfrom, $limitnum, $query));
359 }
360 } else if ($includes == 'all') {
361 $results = cohort_get_all_cohorts($limitfrom, $limitnum, $query);
362 $results = $results['cohorts'];
363 } else {
364 throw new coding_exception('Invalid parameter value for \'includes\'.');
365 }
366
367 $cohorts = array();
368 foreach ($results as $key => $cohort) {
369 $cohortcontext = context::instance_by_id($cohort->contextid);
370 if (!isset($cohort->description)) {
371 $cohort->description = '';
372 }
373 if (!isset($cohort->descriptionformat)) {
374 $cohort->descriptionformat = FORMAT_PLAIN;
375 }
376
377 list($cohort->description, $cohort->descriptionformat) =
378 external_format_text($cohort->description, $cohort->descriptionformat,
379 $cohortcontext->id, 'cohort', 'description', $cohort->id);
380
381 $cohorts[$key] = $cohort;
382 }
383
384 return array('cohorts' => $cohorts);
385 }
386
387 /**
388 * Returns description of external function result value.
389 *
390 * @return external_description
391 */
392 public static function search_cohorts_returns() {
393 return new external_single_structure(array(
394 'cohorts' => new external_multiple_structure(
395 new external_single_structure(array(
396 'id' => new external_value(PARAM_INT, 'ID of the cohort'),
397 'name' => new external_value(PARAM_RAW, 'cohort name'),
398 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
399 'description' => new external_value(PARAM_RAW, 'cohort description'),
400 'descriptionformat' => new external_format_value('description'),
401 'visible' => new external_value(PARAM_BOOL, 'cohort visible'),
402 ))
403 )
404 ));
405 }
406
407
408
088645e2
AB
409 /**
410 * Returns description of method parameters
411 *
412 * @return external_function_parameters
66d6221f 413 * @since Moodle 2.5
088645e2
AB
414 */
415 public static function update_cohorts_parameters() {
416 return new external_function_parameters(
417 array(
418 'cohorts' => new external_multiple_structure(
419 new external_single_structure(
420 array(
fb5ce7d3 421 'id' => new external_value(PARAM_INT, 'ID of the cohort'),
088645e2
AB
422 'categorytype' => new external_single_structure(
423 array(
424 'type' => new external_value(PARAM_TEXT, 'the name of the field: id (numeric value
66d6221f
DW
425 of course category id) or idnumber (alphanumeric value of idnumber course category)
426 or system (value ignored)'),
088645e2
AB
427 'value' => new external_value(PARAM_RAW, 'the value of the categorytype')
428 )
429 ),
430 'name' => new external_value(PARAM_RAW, 'cohort name'),
431 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'),
432 'description' => new external_value(PARAM_RAW, 'cohort description', VALUE_OPTIONAL),
433 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
80f98467 434 'visible' => new external_value(PARAM_BOOL, 'cohort visible', VALUE_OPTIONAL),
088645e2
AB
435 )
436 )
437 )
438 )
439 );
440 }
441
442 /**
443 * Update cohorts
444 *
445 * @param array $cohorts
446 * @return null
66d6221f 447 * @since Moodle 2.5
088645e2
AB
448 */
449 public static function update_cohorts($cohorts) {
450 global $CFG, $DB;
451 require_once("$CFG->dirroot/cohort/lib.php");
452
453 $params = self::validate_parameters(self::update_cohorts_parameters(), array('cohorts' => $cohorts));
454
455 $transaction = $DB->start_delegated_transaction();
66d6221f 456 $syscontext = context_system::instance();
088645e2
AB
457
458 foreach ($params['cohorts'] as $cohort) {
459 $cohort = (object) $cohort;
460
461 if (trim($cohort->name) == '') {
462 throw new invalid_parameter_exception('Invalid cohort name');
463 }
464
66d6221f
DW
465 $oldcohort = $DB->get_record('cohort', array('id' => $cohort->id), '*', MUST_EXIST);
466 $oldcontext = context::instance_by_id($oldcohort->contextid, MUST_EXIST);
467 require_capability('moodle/cohort:manage', $oldcontext);
468
088645e2
AB
469 // Category type (context id).
470 $categorytype = $cohort->categorytype;
66d6221f
DW
471 if (!in_array($categorytype['type'], array('idnumber', 'id', 'system'))) {
472 throw new invalid_parameter_exception('category type must be id, idnumber or system:' . $categorytype['type']);
473 }
474 if ($categorytype['type'] === 'system') {
475 $cohort->contextid = $syscontext->id;
476 } else if ($catid = $DB->get_field('course_categories', 'id', array($categorytype['type'] => $categorytype['value']))) {
088645e2
AB
477 $cohort->contextid = $DB->get_field('context', 'id', array('instanceid' => $catid,
478 'contextlevel' => CONTEXT_COURSECAT));
479 } else {
480 throw new invalid_parameter_exception('category not exists: category='.$categorytype['value']);
481 }
482
66d6221f
DW
483 if ($cohort->contextid != $oldcohort->contextid) {
484 $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
485 if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
486 throw new invalid_parameter_exception('Invalid context');
487 }
488
489 self::validate_context($context);
490 require_capability('moodle/cohort:manage', $context);
088645e2 491 }
088645e2
AB
492
493 if (!empty($cohort->description)) {
494 $cohort->descriptionformat = external_validate_format($cohort->descriptionformat);
495 }
496
497 cohort_update_cohort($cohort);
498 }
499
500 $transaction->allow_commit();
501
502 return null;
503 }
504
505 /**
506 * Returns description of method result value
507 *
508 * @return null
66d6221f 509 * @since Moodle 2.5
088645e2
AB
510 */
511 public static function update_cohorts_returns() {
512 return null;
513 }
514
515 /**
516 * Returns description of method parameters
517 *
518 * @return external_function_parameters
66d6221f 519 * @since Moodle 2.5
088645e2
AB
520 */
521 public static function add_cohort_members_parameters() {
522 return new external_function_parameters (
523 array(
524 'members' => new external_multiple_structure (
525 new external_single_structure (
526 array (
527 'cohorttype' => new external_single_structure (
528 array(
529 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the field: id
530 (numeric value of cohortid) or idnumber (alphanumeric value of idnumber) '),
531 'value' => new external_value(PARAM_RAW, 'The value of the cohort')
532 )
533 ),
534 'usertype' => new external_single_structure (
535 array(
536 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the field: id
537 (numeric value of id) or username (alphanumeric value of username) '),
538 'value' => new external_value(PARAM_RAW, 'The value of the cohort')
539 )
540 )
541 )
542 )
543 )
544 )
545 );
546 }
547
548 /**
549 * Add cohort members
550 *
551 * @param array $members of arrays with keys userid, cohortid
66d6221f 552 * @since Moodle 2.5
088645e2
AB
553 */
554 public static function add_cohort_members($members) {
555 global $CFG, $DB;
556 require_once($CFG->dirroot."/cohort/lib.php");
557
558 $params = self::validate_parameters(self::add_cohort_members_parameters(), array('members' => $members));
559
560 $transaction = $DB->start_delegated_transaction();
561 $warnings = array();
562 foreach ($params['members'] as $member) {
563 // Cohort parameters.
564 $cohorttype = $member['cohorttype'];
565 $cohortparam = array($cohorttype['type'] => $cohorttype['value']);
566 // User parameters.
567 $usertype = $member['usertype'];
568 $userparam = array($usertype['type'] => $usertype['value']);
569 try {
570 // Check parameters.
571 if ($cohorttype['type'] != 'id' && $cohorttype['type'] != 'idnumber') {
572 $warning = array();
573 $warning['warningcode'] = '1';
574 $warning['message'] = 'invalid parameter: cohortype='.$cohorttype['type'];
575 $warnings[] = $warning;
576 continue;
577 }
578 if ($usertype['type'] != 'id' && $usertype['type'] != 'username') {
579 $warning = array();
580 $warning['warningcode'] = '1';
581 $warning['message'] = 'invalid parameter: usertype='.$usertype['type'];
582 $warnings[] = $warning;
583 continue;
584 }
585 // Extract parameters.
586 if (!$cohortid = $DB->get_field('cohort', 'id', $cohortparam)) {
587 $warning = array();
588 $warning['warningcode'] = '2';
589 $warning['message'] = 'cohort '.$cohorttype['type'].'='.$cohorttype['value'].' not exists';
590 $warnings[] = $warning;
591 continue;
592 }
593 if (!$userid = $DB->get_field('user', 'id', array_merge($userparam, array('deleted' => 0,
594 'mnethostid' => $CFG->mnet_localhost_id)))) {
595 $warning = array();
596 $warning['warningcode'] = '2';
597 $warning['message'] = 'user '.$usertype['type'].'='.$usertype['value'].' not exists';
598 $warnings[] = $warning;
599 continue;
600 }
601 if ($DB->record_exists('cohort_members', array('cohortid' => $cohortid, 'userid' => $userid))) {
602 $warning = array();
603 $warning['warningcode'] = '3';
604 $warning['message'] = 'record already exists: cohort('.$cohorttype['type'].'='.$cohorttype['value'].' '.
605 $usertype['type'].'='.$usertype['value'].')';
606 $warnings[] = $warning;
607 continue;
608 }
609 $cohort = $DB->get_record('cohort', array('id'=>$cohortid), '*', MUST_EXIST);
610 $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
611 if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
612 $warning = array();
613 $warning['warningcode'] = '1';
614 $warning['message'] = 'Invalid context: '.$context->contextlevel;
615 $warnings[] = $warning;
616 continue;
617 }
618 self::validate_context($context);
619 } catch (Exception $e) {
620 throw new moodle_exception('Error', 'cohort', '', $e->getMessage());
621 }
66d6221f
DW
622 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) {
623 throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', '');
624 }
088645e2
AB
625 cohort_add_member($cohortid, $userid);
626 }
627 $transaction->allow_commit();
628 // Return.
629 $result = array();
630 $result['warnings'] = $warnings;
631 return $result;
632 }
633
634 /**
635 * Returns description of method result value
636 *
637 * @return null
66d6221f 638 * @since Moodle 2.5
088645e2
AB
639 */
640 public static function add_cohort_members_returns() {
641 return new external_single_structure(
642 array(
643 'warnings' => new external_warnings()
644 )
645 );
646 }
647
648 /**
649 * Returns description of method parameters
650 *
651 * @return external_function_parameters
66d6221f 652 * @since Moodle 2.5
088645e2
AB
653 */
654 public static function delete_cohort_members_parameters() {
655 return new external_function_parameters(
656 array(
657 'members' => new external_multiple_structure(
658 new external_single_structure(
659 array(
660 'cohortid' => new external_value(PARAM_INT, 'cohort record id'),
661 'userid' => new external_value(PARAM_INT, 'user id'),
662 )
663 )
664 )
665 )
666 );
667 }
668
669 /**
670 * Delete cohort members
671 *
672 * @param array $members of arrays with keys userid, cohortid
66d6221f 673 * @since Moodle 2.5
088645e2
AB
674 */
675 public static function delete_cohort_members($members) {
676 global $CFG, $DB;
677 require_once("$CFG->dirroot/cohort/lib.php");
678
679 // Validate parameters.
680 $params = self::validate_parameters(self::delete_cohort_members_parameters(), array('members' => $members));
681
682 $transaction = $DB->start_delegated_transaction();
683
684 foreach ($params['members'] as $member) {
685 $cohortid = $member['cohortid'];
686 $userid = $member['userid'];
687
688 $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
689 $user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0, 'mnethostid' => $CFG->mnet_localhost_id),
690 '*', MUST_EXIST);
691
692 // Now security checks.
693 $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
694 if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
695 throw new invalid_parameter_exception('Invalid context');
696 }
697 self::validate_context($context);
66d6221f
DW
698 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) {
699 throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', '');
700 }
088645e2
AB
701
702 cohort_remove_member($cohort->id, $user->id);
703 }
704 $transaction->allow_commit();
705 }
706
707 /**
708 * Returns description of method result value
709 *
710 * @return null
66d6221f 711 * @since Moodle 2.5
088645e2
AB
712 */
713 public static function delete_cohort_members_returns() {
714 return null;
715 }
716
717 /**
718 * Returns description of method parameters
719 *
720 * @return external_function_parameters
66d6221f 721 * @since Moodle 2.5
088645e2
AB
722 */
723 public static function get_cohort_members_parameters() {
724 return new external_function_parameters(
725 array(
726 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'Cohort ID')),
727 )
728 );
729 }
730
731 /**
732 * Return all members for a cohort
733 *
734 * @param array $cohortids array of cohort ids
735 * @return array with cohort id keys containing arrays of user ids
66d6221f 736 * @since Moodle 2.5
088645e2
AB
737 */
738 public static function get_cohort_members($cohortids) {
739 global $DB;
740 $params = self::validate_parameters(self::get_cohort_members_parameters(), array('cohortids' => $cohortids));
741
742 $members = array();
743
744 foreach ($params['cohortids'] as $cohortid) {
745 // Validate params.
746 $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
747 // Now security checks.
748 $context = context::instance_by_id($cohort->contextid, MUST_EXIST);
749 if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) {
750 throw new invalid_parameter_exception('Invalid context');
751 }
752 self::validate_context($context);
66d6221f
DW
753 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) {
754 throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', '');
755 }
088645e2
AB
756
757 $cohortmembers = $DB->get_records_sql("SELECT u.id FROM {user} u, {cohort_members} cm
758 WHERE u.id = cm.userid AND cm.cohortid = ?
759 ORDER BY lastname ASC, firstname ASC", array($cohort->id));
760 $members[] = array('cohortid' => $cohortid, 'userids' => array_keys($cohortmembers));
761 }
762 return $members;
763 }
764
765 /**
766 * Returns description of method result value
767 *
768 * @return external_description
66d6221f 769 * @since Moodle 2.5
088645e2
AB
770 */
771 public static function get_cohort_members_returns() {
772 return new external_multiple_structure(
773 new external_single_structure(
774 array(
775 'cohortid' => new external_value(PARAM_INT, 'cohort record id'),
776 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
777 )
778 )
779 );
780 }
66d6221f 781}