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