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