2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
20 * @package core_cohort
22 * @copyright MediaTouch 2000 srl
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 require_once("$CFG->libdir/externallib.php");
28 class core_cohort_external
extends external_api
{
31 * Returns description of method parameters
33 * @return external_function_parameters
36 public static function create_cohorts_parameters() {
37 return new external_function_parameters(
39 'cohorts' => new external_multiple_structure(
40 new external_single_structure(
42 'categorytype' => new external_single_structure(
44 'type' => new external_value(PARAM_TEXT
, 'the name of the field: id (numeric value
45 of course category id) or idnumber (alphanumeric value of idnumber course category)
46 or system (value ignored)'),
47 'value' => new external_value(PARAM_RAW
, 'the value of the categorytype')
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
),
54 'visible' => new external_value(PARAM_BOOL
, 'cohort visible', VALUE_OPTIONAL
, true),
63 * Create one or more cohorts
65 * @param array $cohorts An array of cohorts to create.
66 * @return array An array of arrays
69 public static function create_cohorts($cohorts) {
71 require_once("$CFG->dirroot/cohort/lib.php");
73 $params = self
::validate_parameters(self
::create_cohorts_parameters(), array('cohorts' => $cohorts));
75 $transaction = $DB->start_delegated_transaction();
77 $syscontext = context_system
::instance();
80 foreach ($params['cohorts'] as $cohort) {
81 $cohort = (object)$cohort;
83 // Category type (context id).
84 $categorytype = $cohort->categorytype
;
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']);
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
;
94 throw new invalid_parameter_exception('category not exists: category '
95 .$categorytype['type'].' = '.$categorytype['value']);
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
);
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');
105 self
::validate_context($context);
106 require_capability('moodle/cohort:manage', $context);
109 $cohort->descriptionformat
= external_validate_format($cohort->descriptionformat
);
110 $cohort->id
= cohort_add_cohort($cohort);
112 list($cohort->description
, $cohort->descriptionformat
) =
113 external_format_text($cohort->description
, $cohort->descriptionformat
,
114 $context->id
, 'cohort', 'description', $cohort->id
);
115 $cohortids[] = (array)$cohort;
117 $transaction->allow_commit();
123 * Returns description of method result value
125 * @return external_description
128 public static function create_cohorts_returns() {
129 return new external_multiple_structure(
130 new external_single_structure(
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'),
137 'visible' => new external_value(PARAM_BOOL
, 'cohort visible'),
144 * Returns description of method parameters
146 * @return external_function_parameters
149 public static function delete_cohorts_parameters() {
150 return new external_function_parameters(
152 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT
, 'cohort ID')),
160 * @param array $cohortids
164 public static function delete_cohorts($cohortids) {
166 require_once("$CFG->dirroot/cohort/lib.php");
168 $params = self
::validate_parameters(self
::delete_cohorts_parameters(), array('cohortids' => $cohortids));
170 $transaction = $DB->start_delegated_transaction();
172 foreach ($params['cohortids'] as $cohortid) {
174 $cohortid = validate_param($cohortid, PARAM_INT
);
175 $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST
);
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');
182 self
::validate_context($context);
183 require_capability('moodle/cohort:manage', $context);
184 cohort_delete_cohort($cohort);
186 $transaction->allow_commit();
192 * Returns description of method result value
197 public static function delete_cohorts_returns() {
202 * Returns description of method parameters
204 * @return external_function_parameters
207 public static function get_cohorts_parameters() {
208 return new external_function_parameters(
210 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT
, 'Cohort ID')
211 , 'List of cohort id. A cohort id is an integer.', VALUE_DEFAULT
, array()),
217 * Get cohorts definition specified by ids
219 * @param array $cohortids array of cohort ids
220 * @return array of cohort objects (id, courseid, name)
223 public static function get_cohorts($cohortids = array()) {
226 $params = self
::validate_parameters(self
::get_cohorts_parameters(), array('cohortids' => $cohortids));
228 if (empty($cohortids)) {
229 $cohorts = $DB->get_records('cohort');
231 $cohorts = $DB->get_records_list('cohort', 'id', $params['cohortids']);
234 $cohortsinfo = array();
235 foreach ($cohorts as $cohort) {
236 // Now security checks.
237 $context = context
::instance_by_id($cohort->contextid
, MUST_EXIST
);
238 if ($context->contextlevel
!= CONTEXT_COURSECAT
and $context->contextlevel
!= CONTEXT_SYSTEM
) {
239 throw new invalid_parameter_exception('Invalid context');
241 self
::validate_context($context);
242 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) {
243 throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', '');
246 list($cohort->description
, $cohort->descriptionformat
) =
247 external_format_text($cohort->description
, $cohort->descriptionformat
,
248 $context->id
, 'cohort', 'description', $cohort->id
);
250 $cohortsinfo[] = (array) $cohort;
257 * Returns description of method result value
259 * @return external_description
262 public static function get_cohorts_returns() {
263 return new external_multiple_structure(
264 new external_single_structure(
266 'id' => new external_value(PARAM_INT
, 'ID of the cohort'),
267 'name' => new external_value(PARAM_RAW
, 'cohort name'),
268 'idnumber' => new external_value(PARAM_RAW
, 'cohort idnumber'),
269 'description' => new external_value(PARAM_RAW
, 'cohort description'),
270 'descriptionformat' => new external_format_value('description'),
271 'visible' => new external_value(PARAM_BOOL
, 'cohort visible'),
278 * Returns description of method parameters
280 * @return external_function_parameters
283 public static function update_cohorts_parameters() {
284 return new external_function_parameters(
286 'cohorts' => new external_multiple_structure(
287 new external_single_structure(
289 'id' => new external_value(PARAM_INT
, 'ID of the cohort'),
290 'categorytype' => new external_single_structure(
292 'type' => new external_value(PARAM_TEXT
, 'the name of the field: id (numeric value
293 of course category id) or idnumber (alphanumeric value of idnumber course category)
294 or system (value ignored)'),
295 'value' => new external_value(PARAM_RAW
, 'the value of the categorytype')
298 'name' => new external_value(PARAM_RAW
, 'cohort name'),
299 'idnumber' => new external_value(PARAM_RAW
, 'cohort idnumber'),
300 'description' => new external_value(PARAM_RAW
, 'cohort description', VALUE_OPTIONAL
),
301 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT
),
302 'visible' => new external_value(PARAM_BOOL
, 'cohort visible', VALUE_OPTIONAL
),
313 * @param array $cohorts
317 public static function update_cohorts($cohorts) {
319 require_once("$CFG->dirroot/cohort/lib.php");
321 $params = self
::validate_parameters(self
::update_cohorts_parameters(), array('cohorts' => $cohorts));
323 $transaction = $DB->start_delegated_transaction();
324 $syscontext = context_system
::instance();
326 foreach ($params['cohorts'] as $cohort) {
327 $cohort = (object) $cohort;
329 if (trim($cohort->name
) == '') {
330 throw new invalid_parameter_exception('Invalid cohort name');
333 $oldcohort = $DB->get_record('cohort', array('id' => $cohort->id
), '*', MUST_EXIST
);
334 $oldcontext = context
::instance_by_id($oldcohort->contextid
, MUST_EXIST
);
335 require_capability('moodle/cohort:manage', $oldcontext);
337 // Category type (context id).
338 $categorytype = $cohort->categorytype
;
339 if (!in_array($categorytype['type'], array('idnumber', 'id', 'system'))) {
340 throw new invalid_parameter_exception('category type must be id, idnumber or system:' . $categorytype['type']);
342 if ($categorytype['type'] === 'system') {
343 $cohort->contextid
= $syscontext->id
;
344 } else if ($catid = $DB->get_field('course_categories', 'id', array($categorytype['type'] => $categorytype['value']))) {
345 $cohort->contextid
= $DB->get_field('context', 'id', array('instanceid' => $catid,
346 'contextlevel' => CONTEXT_COURSECAT
));
348 throw new invalid_parameter_exception('category not exists: category='.$categorytype['value']);
351 if ($cohort->contextid
!= $oldcohort->contextid
) {
352 $context = context
::instance_by_id($cohort->contextid
, MUST_EXIST
);
353 if ($context->contextlevel
!= CONTEXT_COURSECAT
and $context->contextlevel
!= CONTEXT_SYSTEM
) {
354 throw new invalid_parameter_exception('Invalid context');
357 self
::validate_context($context);
358 require_capability('moodle/cohort:manage', $context);
361 if (!empty($cohort->description
)) {
362 $cohort->descriptionformat
= external_validate_format($cohort->descriptionformat
);
365 cohort_update_cohort($cohort);
368 $transaction->allow_commit();
374 * Returns description of method result value
379 public static function update_cohorts_returns() {
384 * Returns description of method parameters
386 * @return external_function_parameters
389 public static function add_cohort_members_parameters() {
390 return new external_function_parameters (
392 'members' => new external_multiple_structure (
393 new external_single_structure (
395 'cohorttype' => new external_single_structure (
397 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the field: id
398 (numeric value of cohortid) or idnumber (alphanumeric value of idnumber) '),
399 'value' => new external_value(PARAM_RAW
, 'The value of the cohort')
402 'usertype' => new external_single_structure (
404 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the field: id
405 (numeric value of id) or username (alphanumeric value of username) '),
406 'value' => new external_value(PARAM_RAW
, 'The value of the cohort')
419 * @param array $members of arrays with keys userid, cohortid
422 public static function add_cohort_members($members) {
424 require_once($CFG->dirroot
."/cohort/lib.php");
426 $params = self
::validate_parameters(self
::add_cohort_members_parameters(), array('members' => $members));
428 $transaction = $DB->start_delegated_transaction();
430 foreach ($params['members'] as $member) {
431 // Cohort parameters.
432 $cohorttype = $member['cohorttype'];
433 $cohortparam = array($cohorttype['type'] => $cohorttype['value']);
435 $usertype = $member['usertype'];
436 $userparam = array($usertype['type'] => $usertype['value']);
439 if ($cohorttype['type'] != 'id' && $cohorttype['type'] != 'idnumber') {
441 $warning['warningcode'] = '1';
442 $warning['message'] = 'invalid parameter: cohortype='.$cohorttype['type'];
443 $warnings[] = $warning;
446 if ($usertype['type'] != 'id' && $usertype['type'] != 'username') {
448 $warning['warningcode'] = '1';
449 $warning['message'] = 'invalid parameter: usertype='.$usertype['type'];
450 $warnings[] = $warning;
453 // Extract parameters.
454 if (!$cohortid = $DB->get_field('cohort', 'id', $cohortparam)) {
456 $warning['warningcode'] = '2';
457 $warning['message'] = 'cohort '.$cohorttype['type'].'='.$cohorttype['value'].' not exists';
458 $warnings[] = $warning;
461 if (!$userid = $DB->get_field('user', 'id', array_merge($userparam, array('deleted' => 0,
462 'mnethostid' => $CFG->mnet_localhost_id
)))) {
464 $warning['warningcode'] = '2';
465 $warning['message'] = 'user '.$usertype['type'].'='.$usertype['value'].' not exists';
466 $warnings[] = $warning;
469 if ($DB->record_exists('cohort_members', array('cohortid' => $cohortid, 'userid' => $userid))) {
471 $warning['warningcode'] = '3';
472 $warning['message'] = 'record already exists: cohort('.$cohorttype['type'].'='.$cohorttype['value'].' '.
473 $usertype['type'].'='.$usertype['value'].')';
474 $warnings[] = $warning;
477 $cohort = $DB->get_record('cohort', array('id'=>$cohortid), '*', MUST_EXIST
);
478 $context = context
::instance_by_id($cohort->contextid
, MUST_EXIST
);
479 if ($context->contextlevel
!= CONTEXT_COURSECAT
and $context->contextlevel
!= CONTEXT_SYSTEM
) {
481 $warning['warningcode'] = '1';
482 $warning['message'] = 'Invalid context: '.$context->contextlevel
;
483 $warnings[] = $warning;
486 self
::validate_context($context);
487 } catch (Exception
$e) {
488 throw new moodle_exception('Error', 'cohort', '', $e->getMessage());
490 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) {
491 throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', '');
493 cohort_add_member($cohortid, $userid);
495 $transaction->allow_commit();
498 $result['warnings'] = $warnings;
503 * Returns description of method result value
508 public static function add_cohort_members_returns() {
509 return new external_single_structure(
511 'warnings' => new external_warnings()
517 * Returns description of method parameters
519 * @return external_function_parameters
522 public static function delete_cohort_members_parameters() {
523 return new external_function_parameters(
525 'members' => new external_multiple_structure(
526 new external_single_structure(
528 'cohortid' => new external_value(PARAM_INT
, 'cohort record id'),
529 'userid' => new external_value(PARAM_INT
, 'user id'),
538 * Delete cohort members
540 * @param array $members of arrays with keys userid, cohortid
543 public static function delete_cohort_members($members) {
545 require_once("$CFG->dirroot/cohort/lib.php");
547 // Validate parameters.
548 $params = self
::validate_parameters(self
::delete_cohort_members_parameters(), array('members' => $members));
550 $transaction = $DB->start_delegated_transaction();
552 foreach ($params['members'] as $member) {
553 $cohortid = $member['cohortid'];
554 $userid = $member['userid'];
556 $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST
);
557 $user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0, 'mnethostid' => $CFG->mnet_localhost_id
),
560 // Now security checks.
561 $context = context
::instance_by_id($cohort->contextid
, MUST_EXIST
);
562 if ($context->contextlevel
!= CONTEXT_COURSECAT
and $context->contextlevel
!= CONTEXT_SYSTEM
) {
563 throw new invalid_parameter_exception('Invalid context');
565 self
::validate_context($context);
566 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) {
567 throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', '');
570 cohort_remove_member($cohort->id
, $user->id
);
572 $transaction->allow_commit();
576 * Returns description of method result value
581 public static function delete_cohort_members_returns() {
586 * Returns description of method parameters
588 * @return external_function_parameters
591 public static function get_cohort_members_parameters() {
592 return new external_function_parameters(
594 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT
, 'Cohort ID')),
600 * Return all members for a cohort
602 * @param array $cohortids array of cohort ids
603 * @return array with cohort id keys containing arrays of user ids
606 public static function get_cohort_members($cohortids) {
608 $params = self
::validate_parameters(self
::get_cohort_members_parameters(), array('cohortids' => $cohortids));
612 foreach ($params['cohortids'] as $cohortid) {
614 $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST
);
615 // Now security checks.
616 $context = context
::instance_by_id($cohort->contextid
, MUST_EXIST
);
617 if ($context->contextlevel
!= CONTEXT_COURSECAT
and $context->contextlevel
!= CONTEXT_SYSTEM
) {
618 throw new invalid_parameter_exception('Invalid context');
620 self
::validate_context($context);
621 if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) {
622 throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', '');
625 $cohortmembers = $DB->get_records_sql("SELECT u.id FROM {user} u, {cohort_members} cm
626 WHERE u.id = cm.userid AND cm.cohortid = ?
627 ORDER BY lastname ASC, firstname ASC", array($cohort->id
));
628 $members[] = array('cohortid' => $cohortid, 'userids' => array_keys($cohortmembers));
634 * Returns description of method result value
636 * @return external_description
639 public static function get_cohort_members_returns() {
640 return new external_multiple_structure(
641 new external_single_structure(
643 'cohortid' => new external_value(PARAM_INT
, 'cohort record id'),
644 'userids' => new external_multiple_structure(new external_value(PARAM_INT
, 'user id')),