MDL-32662 Added get_course_groupings method
[moodle.git] / group / externallib.php
CommitLineData
9a0df45a 1<?php
9a0df45a 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
4615817d 17
9a0df45a 18/**
19 * External groups API
20 *
4d8e2417 21 * @package core_group
4615817d
JM
22 * @category external
23 * @copyright 2009 Petr Skodak
9a0df45a 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27require_once("$CFG->libdir/externallib.php");
28
5d1017e1 29/**
4615817d 30 * Group external functions
4d8e2417
AG
31 *
32 * @package core_group
4615817d
JM
33 * @category external
34 * @copyright 2011 Jerome Mouneyrac
4d8e2417 35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4615817d 36 * @since Moodle 2.2
5d1017e1
JM
37 */
38class core_group_external extends external_api {
9a0df45a 39
0c96468c 40 /**
41 * Returns description of method parameters
4615817d 42 *
f5072177 43 * @return external_function_parameters
4615817d 44 * @since Moodle 2.2
0c96468c 45 */
46 public static function create_groups_parameters() {
f5072177 47 return new external_function_parameters(
48 array(
49 'groups' => new external_multiple_structure(
50 new external_single_structure(
51 array(
52 'courseid' => new external_value(PARAM_INT, 'id of course'),
53 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
54 'description' => new external_value(PARAM_RAW, 'group description text'),
55 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
56 )
d4c6ef70 57 ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
f5072177 58 )
59 )
60 );
0c96468c 61 }
62
63 /**
9a0df45a 64 * Create groups
4615817d 65 *
b4c1a34e 66 * @param array $groups array of group description arrays (with keys groupname and courseid)
f5072177 67 * @return array of newly created groups
4615817d 68 * @since Moodle 2.2
9a0df45a 69 */
b4c1a34e 70 public static function create_groups($groups) {
f5072177 71 global $CFG, $DB;
9a0df45a 72 require_once("$CFG->dirroot/group/lib.php");
73
c9c5cc81 74 $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
0c96468c 75
d5a8d9aa
PS
76 $transaction = $DB->start_delegated_transaction();
77
78 $groups = array();
79
80 foreach ($params['groups'] as $group) {
81 $group = (object)$group;
82
83 if (trim($group->name) == '') {
84 throw new invalid_parameter_exception('Invalid group name');
85 }
86 if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
87 throw new invalid_parameter_exception('Group with the same name already exists in the course');
ab9a01f2 88 }
d5a8d9aa
PS
89
90 // now security checks
91 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
41e962ff 92 try {
93 self::validate_context($context);
94 } catch (Exception $e) {
95 $exceptionparam = new stdClass();
96 $exceptionparam->message = $e->getMessage();
97 $exceptionparam->courseid = $group->courseid;
98 throw new moodle_exception(
99 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
100 }
d5a8d9aa
PS
101 require_capability('moodle/course:managegroups', $context);
102
103 // finally create the group
104 $group->id = groups_create_group($group, false);
105 $groups[] = (array)$group;
9a0df45a 106 }
d5a8d9aa
PS
107
108 $transaction->allow_commit();
9a0df45a 109
2e13b916 110 return $groups;
9a0df45a 111 }
112
4d8e2417 113 /**
0c96468c 114 * Returns description of method result value
4615817d
JM
115 *
116 * @return external_description
117 * @since Moodle 2.2
0c96468c 118 */
119 public static function create_groups_returns() {
f5072177 120 return new external_multiple_structure(
121 new external_single_structure(
122 array(
123 'id' => new external_value(PARAM_INT, 'group record id'),
124 'courseid' => new external_value(PARAM_INT, 'id of course'),
125 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
126 'description' => new external_value(PARAM_RAW, 'group description text'),
127 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
128 )
d4c6ef70 129 ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
f5072177 130 );
0c96468c 131 }
132
f5072177 133 /**
134 * Returns description of method parameters
4615817d 135 *
f5072177 136 * @return external_function_parameters
4615817d 137 * @since Moodle 2.2
f5072177 138 */
0c96468c 139 public static function get_groups_parameters() {
8c772ad7 140 return new external_function_parameters(
141 array(
d4c6ef70 142 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
143 ,'List of group id. A group id is an integer.'),
8c772ad7 144 )
145 );
0c96468c 146 }
147
9a0df45a 148 /**
246f6da2 149 * Get groups definition specified by ids
4615817d 150 *
b4c1a34e 151 * @param array $groupids arrays of group ids
9a0df45a 152 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d 153 * @since Moodle 2.2
9a0df45a 154 */
b4c1a34e 155 public static function get_groups($groupids) {
c9c5cc81 156 $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
0c96468c 157
246f6da2 158 $groups = array();
0c96468c 159 foreach ($params['groupids'] as $groupid) {
ab9a01f2 160 // validate params
ab9a01f2 161 $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
162
9a0df45a 163 // now security checks
164 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
41e962ff 165 try {
166 self::validate_context($context);
167 } catch (Exception $e) {
168 $exceptionparam = new stdClass();
169 $exceptionparam->message = $e->getMessage();
170 $exceptionparam->courseid = $group->courseid;
171 throw new moodle_exception(
172 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
173 }
9a0df45a 174 require_capability('moodle/course:managegroups', $context);
175
2e13b916 176 $groups[] = (array)$group;
9a0df45a 177 }
178
179 return $groups;
180 }
181
4d8e2417 182 /**
f5072177 183 * Returns description of method result value
4615817d
JM
184 *
185 * @return external_description
186 * @since Moodle 2.2
f5072177 187 */
0c96468c 188 public static function get_groups_returns() {
246f6da2 189 return new external_multiple_structure(
190 new external_single_structure(
191 array(
192 'id' => new external_value(PARAM_INT, 'group record id'),
193 'courseid' => new external_value(PARAM_INT, 'id of course'),
194 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
195 'description' => new external_value(PARAM_RAW, 'group description text'),
196 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
197 )
198 )
199 );
200 }
201
202 /**
203 * Returns description of method parameters
4615817d 204 *
246f6da2 205 * @return external_function_parameters
4615817d 206 * @since Moodle 2.2
246f6da2 207 */
208 public static function get_course_groups_parameters() {
209 return new external_function_parameters(
210 array(
211 'courseid' => new external_value(PARAM_INT, 'id of course'),
212 )
213 );
214 }
215
216 /**
217 * Get all groups in the specified course
4615817d 218 *
246f6da2 219 * @param int $courseid id of course
220 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d 221 * @since Moodle 2.2
246f6da2 222 */
223 public static function get_course_groups($courseid) {
224 $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
225
226 // now security checks
227 $context = get_context_instance(CONTEXT_COURSE, $params['courseid']);
41e962ff 228 try {
229 self::validate_context($context);
230 } catch (Exception $e) {
231 $exceptionparam = new stdClass();
232 $exceptionparam->message = $e->getMessage();
233 $exceptionparam->courseid = $params['courseid'];
234 throw new moodle_exception(
235 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
236 }
246f6da2 237 require_capability('moodle/course:managegroups', $context);
238
239 $gs = groups_get_all_groups($params['courseid'], 0, 0, 'g.id, g.courseid, g.name, g.description, g.enrolmentkey');
240
241 $groups = array();
242 foreach ($gs as $group) {
243 $groups[] = (array)$group;
244 }
245
246 return $groups;
247 }
248
4d8e2417 249 /**
246f6da2 250 * Returns description of method result value
4615817d
JM
251 *
252 * @return external_description
253 * @since Moodle 2.2
246f6da2 254 */
255 public static function get_course_groups_returns() {
8c772ad7 256 return new external_multiple_structure(
257 new external_single_structure(
258 array(
f5072177 259 'id' => new external_value(PARAM_INT, 'group record id'),
260 'courseid' => new external_value(PARAM_INT, 'id of course'),
04d212ce 261 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
f5072177 262 'description' => new external_value(PARAM_RAW, 'group description text'),
263 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
8c772ad7 264 )
265 )
266 );
0c96468c 267 }
268
0f4e72de
PS
269 /**
270 * Returns description of method parameters
4615817d 271 *
0f4e72de 272 * @return external_function_parameters
4615817d 273 * @since Moodle 2.2
0f4e72de 274 */
0c96468c 275 public static function delete_groups_parameters() {
0f4e72de
PS
276 return new external_function_parameters(
277 array(
278 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
279 )
280 );
0c96468c 281 }
282
9a0df45a 283 /**
284 * Delete groups
4615817d 285 *
b4c1a34e 286 * @param array $groupids array of group ids
4615817d 287 * @since Moodle 2.2
9a0df45a 288 */
b4c1a34e 289 public static function delete_groups($groupids) {
2cb1ee78 290 global $CFG, $DB;
9a0df45a 291 require_once("$CFG->dirroot/group/lib.php");
292
c9c5cc81 293 $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
0c96468c 294
d5a8d9aa
PS
295 $transaction = $DB->start_delegated_transaction();
296
d5a8d9aa
PS
297 foreach ($params['groupids'] as $groupid) {
298 // validate params
299 $groupid = validate_param($groupid, PARAM_INTEGER);
300 if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
301 // silently ignore attempts to delete nonexisting groups
302 continue;
0f4e72de 303 }
d5a8d9aa
PS
304
305 // now security checks
306 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
41e962ff 307 try {
308 self::validate_context($context);
309 } catch (Exception $e) {
310 $exceptionparam = new stdClass();
311 $exceptionparam->message = $e->getMessage();
312 $exceptionparam->courseid = $group->courseid;
313 throw new moodle_exception(
314 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
315 }
d5a8d9aa
PS
316 require_capability('moodle/course:managegroups', $context);
317
318 groups_delete_group($group);
9a0df45a 319 }
d5a8d9aa
PS
320
321 $transaction->allow_commit();
9a0df45a 322 }
323
4d8e2417 324 /**
0f4e72de 325 * Returns description of method result value
4615817d
JM
326 *
327 * @return null
328 * @since Moodle 2.2
0f4e72de 329 */
0c96468c 330 public static function delete_groups_returns() {
0f4e72de 331 return null;
0c96468c 332 }
333
334
0f4e72de
PS
335 /**
336 * Returns description of method parameters
4615817d 337 *
0f4e72de 338 * @return external_function_parameters
4615817d 339 * @since Moodle 2.2
0f4e72de 340 */
5d1017e1 341 public static function get_group_members_parameters() {
0f4e72de
PS
342 return new external_function_parameters(
343 array(
344 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
345 )
346 );
0c96468c 347 }
9a0df45a 348
349 /**
350 * Return all members for a group
4615817d 351 *
b4c1a34e 352 * @param array $groupids array of group ids
9a0df45a 353 * @return array with group id keys containing arrays of user ids
4615817d 354 * @since Moodle 2.2
9a0df45a 355 */
5d1017e1 356 public static function get_group_members($groupids) {
0f4e72de 357 $members = array();
9a0df45a 358
5d1017e1 359 $params = self::validate_parameters(self::get_group_members_parameters(), array('groupids'=>$groupids));
0c96468c 360
361 foreach ($params['groupids'] as $groupid) {
ab9a01f2 362 // validate params
9a0df45a 363 $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
364 // now security checks
365 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
41e962ff 366 try {
367 self::validate_context($context);
368 } catch (Exception $e) {
369 $exceptionparam = new stdClass();
370 $exceptionparam->message = $e->getMessage();
371 $exceptionparam->courseid = $group->courseid;
372 throw new moodle_exception(
373 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
374 }
9a0df45a 375 require_capability('moodle/course:managegroups', $context);
376
377 $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
378
0f4e72de 379 $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
9a0df45a 380 }
381
0f4e72de 382 return $members;
9a0df45a 383 }
384
4d8e2417 385 /**
0f4e72de 386 * Returns description of method result value
4615817d 387 *
0f4e72de 388 * @return external_description
4615817d 389 * @since Moodle 2.2
0f4e72de 390 */
5d1017e1 391 public static function get_group_members_returns() {
0f4e72de
PS
392 return new external_multiple_structure(
393 new external_single_structure(
394 array(
395 'groupid' => new external_value(PARAM_INT, 'group record id'),
396 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
397 )
398 )
399 );
0c96468c 400 }
401
402
0f4e72de
PS
403 /**
404 * Returns description of method parameters
4615817d 405 *
0f4e72de 406 * @return external_function_parameters
4615817d 407 * @since Moodle 2.2
0f4e72de 408 */
5d1017e1 409 public static function add_group_members_parameters() {
4efa2483
PS
410 return new external_function_parameters(
411 array(
412 'members'=> new external_multiple_structure(
413 new external_single_structure(
414 array(
415 'groupid' => new external_value(PARAM_INT, 'group record id'),
416 'userid' => new external_value(PARAM_INT, 'user id'),
417 )
418 )
0f4e72de
PS
419 )
420 )
421 );
0c96468c 422 }
9a0df45a 423
424 /**
425 * Add group members
4615817d 426 *
b4c1a34e 427 * @param array $members of arrays with keys userid, groupid
4615817d 428 * @since Moodle 2.2
9a0df45a 429 */
5d1017e1 430 public static function add_group_members($members) {
2cb1ee78 431 global $CFG, $DB;
9a0df45a 432 require_once("$CFG->dirroot/group/lib.php");
433
5d1017e1 434 $params = self::validate_parameters(self::add_group_members_parameters(), array('members'=>$members));
9a0df45a 435
d5a8d9aa 436 $transaction = $DB->start_delegated_transaction();
d5a8d9aa
PS
437 foreach ($params['members'] as $member) {
438 // validate params
439 $groupid = $member['groupid'];
440 $userid = $member['userid'];
0c96468c 441
d5a8d9aa
PS
442 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
443 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 444
d5a8d9aa
PS
445 // now security checks
446 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
41e962ff 447 try {
448 self::validate_context($context);
449 } catch (Exception $e) {
450 $exceptionparam = new stdClass();
451 $exceptionparam->message = $e->getMessage();
452 $exceptionparam->courseid = $group->courseid;
453 throw new moodle_exception(
454 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
455 }
d5a8d9aa 456 require_capability('moodle/course:managegroups', $context);
9a0df45a 457
d5a8d9aa 458 // now make sure user is enrolled in course - this is mandatory requirement,
4f0c2d00
PS
459 // unfortunately this is slow
460 if (!is_enrolled($context, $userid)) {
461 throw new invalid_parameter_exception('Only enrolled users may be members of groups');
462 }
4efa2483 463
d5a8d9aa 464 groups_add_member($group, $user);
9a0df45a 465 }
d5a8d9aa
PS
466
467 $transaction->allow_commit();
9a0df45a 468 }
469
4d8e2417 470 /**
0f4e72de 471 * Returns description of method result value
4615817d 472 *
5d1017e1 473 * @return null
4615817d 474 * @since Moodle 2.2
0f4e72de 475 */
5d1017e1 476 public static function add_group_members_returns() {
0f4e72de 477 return null;
0c96468c 478 }
479
480
0f4e72de
PS
481 /**
482 * Returns description of method parameters
4615817d 483 *
0f4e72de 484 * @return external_function_parameters
4615817d 485 * @since Moodle 2.2
0f4e72de 486 */
5d1017e1 487 public static function delete_group_members_parameters() {
4efa2483
PS
488 return new external_function_parameters(
489 array(
490 'members'=> new external_multiple_structure(
491 new external_single_structure(
492 array(
493 'groupid' => new external_value(PARAM_INT, 'group record id'),
494 'userid' => new external_value(PARAM_INT, 'user id'),
495 )
496 )
0f4e72de
PS
497 )
498 )
499 );
0c96468c 500 }
9a0df45a 501
502 /**
503 * Delete group members
4615817d 504 *
b4c1a34e 505 * @param array $members of arrays with keys userid, groupid
4615817d 506 * @since Moodle 2.2
9a0df45a 507 */
5d1017e1 508 public static function delete_group_members($members) {
2cb1ee78 509 global $CFG, $DB;
9a0df45a 510 require_once("$CFG->dirroot/group/lib.php");
511
5d1017e1 512 $params = self::validate_parameters(self::delete_group_members_parameters(), array('members'=>$members));
9a0df45a 513
d5a8d9aa
PS
514 $transaction = $DB->start_delegated_transaction();
515
0c96468c 516 foreach ($params['members'] as $member) {
d5a8d9aa
PS
517 // validate params
518 $groupid = $member['groupid'];
519 $userid = $member['userid'];
0c96468c 520
d5a8d9aa
PS
521 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
522 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 523
d5a8d9aa
PS
524 // now security checks
525 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
41e962ff 526 try {
527 self::validate_context($context);
528 } catch (Exception $e) {
529 $exceptionparam = new stdClass();
530 $exceptionparam->message = $e->getMessage();
531 $exceptionparam->courseid = $group->courseid;
532 throw new moodle_exception(
533 get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
534 }
d5a8d9aa 535 require_capability('moodle/course:managegroups', $context);
9a0df45a 536
d5a8d9aa 537 groups_remove_member($group, $user);
9a0df45a 538 }
d5a8d9aa
PS
539
540 $transaction->allow_commit();
9a0df45a 541 }
542
4d8e2417 543 /**
0f4e72de 544 * Returns description of method result value
4615817d 545 *
5d1017e1 546 * @return null
4615817d 547 * @since Moodle 2.2
0f4e72de 548 */
5d1017e1 549 public static function delete_group_members_returns() {
0f4e72de 550 return null;
0c96468c 551 }
552
882bac85
JL
553 /**
554 * Returns description of method parameters
555 * @return external_function_parameters
556 */
557 public static function create_groupings_parameters() {
558 return new external_function_parameters(
559 array(
560 'groupings' => new external_multiple_structure(
561 new external_single_structure(
562 array(
563 'courseid' => new external_value(PARAM_INT, 'id of course'),
564 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
565 'description' => new external_value(PARAM_RAW, 'grouping description text')
566 )
567 ), 'List of grouping object. A grouping has a courseid, a name and a description.'
568 )
569 )
570 );
571 }
572
573 /**
574 * Create groupings
575 * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
576 * @return array of newly created groupings
577 */
578 public static function create_groupings($groupings) {
579 global $CFG, $DB;
580 require_once("$CFG->dirroot/group/lib.php");
581
582 $params = self::validate_parameters(self::create_groupings_parameters(), array('groupings'=>$groupings));
583
584 $transaction = $DB->start_delegated_transaction();
585
586 $groupings = array();
587
588 foreach ($params['groupings'] as $grouping) {
589 $grouping = (object)$grouping;
590
591 if (trim($grouping->name) == '') {
592 throw new invalid_parameter_exception('Invalid grouping name');
593 }
594 if ($DB->get_record('groupings', array('courseid'=>$grouping->courseid, 'name'=>$grouping->name))) {
595 throw new invalid_parameter_exception('Grouping with the same name already exists in the course');
596 }
597
598 // Now security checks .
599 $context = context_course::instance($grouping->courseid);
600 try {
601 self::validate_context($context);
602 } catch (Exception $e) {
603 $exceptionparam = new stdClass();
604 $exceptionparam->message = $e->getMessage();
605 $exceptionparam->courseid = $grouping->courseid;
606 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
607 }
608 require_capability('moodle/course:managegroups', $context);
609
610 // We must force allways FORMAT_HTML.
611 $grouping->descriptionformat = FORMAT_HTML;
612
613 // Finally create the grouping.
614 $grouping->id = groups_create_grouping($grouping);
615 $groupings[] = (array)$grouping;
616 }
617
618 $transaction->allow_commit();
619
620 return $groupings;
621 }
622
623 /**
624 * Returns description of method result value
625 * @return external_description
626 */
627 public static function create_groupings_returns() {
628 return new external_multiple_structure(
629 new external_single_structure(
630 array(
631 'id' => new external_value(PARAM_INT, 'grouping record id'),
632 'courseid' => new external_value(PARAM_INT, 'id of course'),
633 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
634 'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
635 )
636 ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
637 );
638 }
639
87e959f3
JL
640 /**
641 * Returns description of method parameters
642 * @return external_function_parameters
643 */
644 public static function update_groupings_parameters() {
645 return new external_function_parameters(
646 array(
647 'groupings' => new external_multiple_structure(
648 new external_single_structure(
649 array(
650 'id' => new external_value(PARAM_INT, 'id of grouping'),
651 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
652 'description' => new external_value(PARAM_RAW, 'grouping description text')
653 )
654 ), 'List of grouping object. A grouping has a courseid, a name and a description.'
655 )
656 )
657 );
658 }
659
660 /**
661 * Update groupings
662 * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
663 * @return array of newly updated groupings
664 */
665 public static function update_groupings($groupings) {
666 global $CFG, $DB;
667 require_once("$CFG->dirroot/group/lib.php");
668
669 $params = self::validate_parameters(self::update_groupings_parameters(), array('groupings'=>$groupings));
670
671 $transaction = $DB->start_delegated_transaction();
672
673 $groupings = array();
674
675 foreach ($params['groupings'] as $grouping) {
676 $grouping = (object)$grouping;
677
678 if (trim($grouping->name) == '') {
679 throw new invalid_parameter_exception('Invalid grouping name');
680 }
681
682 if (! $currentgrouping = $DB->get_record('groupings', array('id'=>$grouping->id))) {
683 throw new invalid_parameter_exception("Grouping $grouping->id does not exist in the course");
684 }
685 $grouping->courseid = $currentgrouping->courseid;
686
687 // Now security checks.
688 $context = context_course::instance($grouping->courseid);
689 try {
690 self::validate_context($context);
691 } catch (Exception $e) {
692 $exceptionparam = new stdClass();
693 $exceptionparam->message = $e->getMessage();
694 $exceptionparam->courseid = $grouping->courseid;
695 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
696 }
697 require_capability('moodle/course:managegroups', $context);
698
699 // We must force allways FORMAT_HTML.
700 $grouping->descriptionformat = FORMAT_HTML;
701
702 // Finally update the grouping.
703 groups_update_grouping($grouping);
704 $groupings[] = (array)$grouping;
705 }
706
707 $transaction->allow_commit();
708
709 return $groupings;
710 }
711
712 /**
713 * Returns description of method result value
714 * @return external_description
715 */
716 public static function update_groupings_returns() {
717 return new external_multiple_structure(
718 new external_single_structure(
719 array(
720 'id' => new external_value(PARAM_INT, 'grouping record id'),
721 'courseid' => new external_value(PARAM_INT, 'id of course'),
722 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
723 'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
724 )
725 ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
726 );
727 }
728
ed849fba
JL
729 /**
730 * Returns description of method parameters
731 * @return external_function_parameters
732 */
733 public static function get_groupings_parameters() {
734 return new external_function_parameters(
735 array(
736 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')
737 ,'List of grouping id. A grouping id is an integer.'),
738 )
739 );
740 }
741
742 /**
743 * Get groupings definition specified by ids
744 * @param array $groupingids arrays of grouping ids
745 * @return array of grouping objects (id, courseid, name)
746 */
747 public static function get_groupings($groupingids) {
748 global $CFG;
749 require_once("$CFG->dirroot/group/lib.php");
750
751 $params = self::validate_parameters(self::get_groupings_parameters(), array('groupingids'=>$groupingids));
752
753 $groupings = array();
754 foreach ($params['groupingids'] as $groupingid) {
755 // Validate params.
756 $grouping = groups_get_grouping($groupingid, '*', MUST_EXIST);
757
758 // Now security checks.
759 $context = context_course::instance($grouping->courseid);
760 try {
761 self::validate_context($context);
762 } catch (Exception $e) {
763 $exceptionparam = new stdClass();
764 $exceptionparam->message = $e->getMessage();
765 $exceptionparam->courseid = $grouping->courseid;
766 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
767 }
768 require_capability('moodle/course:managegroups', $context);
769
770 $grouping->description = file_rewrite_pluginfile_urls($grouping->description, 'webservice/pluginfile.php', $context->id, 'grouping', 'description', $grouping->id);
771
772 $options = new stdClass;
773 $options->noclean = true;
774 $options->para = false;
775 $grouping->description = format_text($grouping->description, FORMAT_HTML, $options);
776
777 $groupings[] = (array)$grouping;
778 }
779
780 return $groupings;
781 }
782
783 /**
784 * Returns description of method result value
785 * @return external_description
786 */
787 public static function get_groupings_returns() {
788 return new external_multiple_structure(
789 new external_single_structure(
790 array(
791 'id' => new external_value(PARAM_INT, 'grouping record id'),
792 'courseid' => new external_value(PARAM_INT, 'id of course'),
793 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
794 'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
795 )
796 )
797 );
798 }
799
85e42d22
JL
800 /**
801 * Returns description of method parameters
802 * @return external_function_parameters
803 */
804 public static function get_course_groupings_parameters() {
805 return new external_function_parameters(
806 array(
807 'courseid' => new external_value(PARAM_INT, 'id of course'),
808 )
809 );
810 }
811
812 /**
813 * Get all groupings in the specified course
814 * @param int $courseid id of course
815 * @return array of grouping objects (id, courseid, name, enrolmentkey)
816 */
817 public static function get_course_groupings($courseid) {
818 global $CFG;
819 require_once("$CFG->dirroot/group/lib.php");
820
821 $params = self::validate_parameters(self::get_course_groupings_parameters(), array('courseid'=>$courseid));
822
823 // Now security checks.
824 $context = context_course::instance($params['courseid']);
825
826 try {
827 self::validate_context($context);
828 } catch (Exception $e) {
829 $exceptionparam = new stdClass();
830 $exceptionparam->message = $e->getMessage();
831 $exceptionparam->courseid = $params['courseid'];
832 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
833 }
834 require_capability('moodle/course:managegroups', $context);
835
836 $gs = groups_get_all_groupings($params['courseid']);
837
838 $groupings = array();
839 foreach ($gs as $grouping) {
840 $grouping->description = file_rewrite_pluginfile_urls($grouping->description, 'webservice/pluginfile.php', $context->id, 'grouping', 'description', $grouping->id);
841
842 $options = new stdClass;
843 $options->noclean = true;
844 $options->para = false;
845 $grouping->description = format_text($grouping->description, FORMAT_HTML, $options);
846
847 $groupings[] = (array)$grouping;
848 }
849
850 return $groupings;
851 }
852
853 /**
854 * Returns description of method result value
855 * @return external_description
856 */
857 public static function get_course_groupings_returns() {
858 return new external_multiple_structure(
859 new external_single_structure(
860 array(
861 'id' => new external_value(PARAM_INT, 'grouping record id'),
862 'courseid' => new external_value(PARAM_INT, 'id of course'),
863 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
864 'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
865 )
866 )
867 );
868 }
869
4ca6cfbf 870}
5d1017e1
JM
871
872/**
4615817d
JM
873 * Deprecated group external functions
874 *
875 * @package core_group
876 * @copyright 2009 Petr Skodak
877 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
878 * @since Moodle 2.0
879 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
880 * @todo MDL-31194 This will be deleted in Moodle 2.5.
881 * @see core_group_external
5d1017e1
JM
882 */
883class moodle_group_external extends external_api {
884
885 /**
886 * Returns description of method parameters
4615817d 887 *
5d1017e1 888 * @return external_function_parameters
4615817d
JM
889 * @since Moodle 2.0
890 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
891 * @todo MDL-31194 This will be deleted in Moodle 2.5.
892 * @see core_group_external::create_groups_parameters()
5d1017e1
JM
893 */
894 public static function create_groups_parameters() {
895 return core_group_external::create_groups_parameters();
896 }
897
898 /**
899 * Create groups
4615817d 900 *
5d1017e1
JM
901 * @param array $groups array of group description arrays (with keys groupname and courseid)
902 * @return array of newly created groups
4615817d
JM
903 * @since Moodle 2.0
904 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
905 * @todo MDL-31194 This will be deleted in Moodle 2.5.
906 * @see use core_group_external::create_groups()
5d1017e1
JM
907 */
908 public static function create_groups($groups) {
909 return core_group_external::create_groups($groups);
910 }
911
e757f518
EL
912 /**
913 * Returns description of method result value
4615817d 914 *
e757f518 915 * @return external_description
4615817d
JM
916 * @since Moodle 2.0
917 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
918 * @todo MDL-31194 This will be deleted in Moodle 2.5.
919 * @see core_group_external::create_groups_returns()
e757f518 920 */
5d1017e1
JM
921 public static function create_groups_returns() {
922 return core_group_external::create_groups_returns();
923 }
924
925 /**
926 * Returns description of method parameters
4615817d 927 *
5d1017e1 928 * @return external_function_parameters
4615817d
JM
929 * @since Moodle 2.0
930 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
931 * @todo MDL-31194 This will be deleted in Moodle 2.5.
932 * @see core_group_external::get_groups_parameters()
5d1017e1
JM
933 */
934 public static function get_groups_parameters() {
935 return core_group_external::get_groups_parameters();
936 }
937
938 /**
939 * Get groups definition specified by ids
4615817d 940 *
5d1017e1
JM
941 * @param array $groupids arrays of group ids
942 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d
JM
943 * @since Moodle 2.0
944 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
945 * @todo MDL-31194 This will be deleted in Moodle 2.5.
946 * @see core_group_external::get_groups()
5d1017e1
JM
947 */
948 public static function get_groups($groupids) {
949 return core_group_external::get_groups($groupids);
950 }
951
e757f518
EL
952 /**
953 * Returns description of method result value
4615817d 954 *
e757f518 955 * @return external_description
4615817d
JM
956 * @since Moodle 2.0
957 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
958 * @todo MDL-31194 This will be deleted in Moodle 2.5.
959 * @see core_group_external::get_groups_returns()
e757f518 960 */
5d1017e1
JM
961 public static function get_groups_returns() {
962 return core_group_external::get_groups_returns();
963 }
964
e757f518
EL
965 /**
966 * Returns description of method parameters
4615817d 967 *
e757f518 968 * @return external_function_parameters
4615817d
JM
969 * @since Moodle 2.0
970 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
971 * @todo MDL-31194 This will be deleted in Moodle 2.5.
972 * @see core_group_external::get_course_groups_parameters()
e757f518 973 */
5d1017e1
JM
974 public static function get_course_groups_parameters() {
975 return core_group_external::get_course_groups_parameters();
976 }
977
e757f518
EL
978 /**
979 * Get all groups in the specified course
4615817d 980 *
e757f518
EL
981 * @param int $courseid id of course
982 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d
JM
983 * @since Moodle 2.0
984 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
985 * @todo MDL-31194 This will be deleted in Moodle 2.5.
986 * @see core_group_external::get_course_groups()
e757f518 987 */
5d1017e1
JM
988 public static function get_course_groups($courseid) {
989 return core_group_external::get_course_groups($courseid);
990 }
991
e757f518
EL
992 /**
993 * Returns description of method result value
4615817d 994 *
e757f518 995 * @return external_description
4615817d
JM
996 * @since Moodle 2.0
997 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
998 * @todo MDL-31194 This will be deleted in Moodle 2.5.
999 * @see core_group_external::get_course_groups_returns()
e757f518 1000 */
5d1017e1
JM
1001 public static function get_course_groups_returns() {
1002 return core_group_external::get_course_groups_returns();
1003 }
1004
1005 /**
1006 * Returns description of method parameters
4615817d 1007 *
5d1017e1 1008 * @return external_function_parameters
4615817d
JM
1009 * @since Moodle 2.0
1010 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1011 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1012 * @see core_group_external::delete_group_members_parameters()
5d1017e1
JM
1013 */
1014 public static function delete_groups_parameters() {
1015 return core_group_external::delete_group_members_parameters();
1016 }
1017
1018 /**
1019 * Delete groups
4615817d 1020 *
5d1017e1 1021 * @param array $groupids array of group ids
4615817d
JM
1022 * @since Moodle 2.0
1023 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1024 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1025 * @see core_group_external::delete_groups()
5d1017e1
JM
1026 */
1027 public static function delete_groups($groupids) {
1028 return core_group_external::delete_groups($groupids);
1029 }
1030
e757f518
EL
1031 /**
1032 * Returns description of method result value
4615817d
JM
1033 *
1034 * @return null
1035 * @since Moodle 2.0
1036 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1037 * @todo MDL-31194 This will be deleted in Moodle 2.5.
e757f518 1038 * @see core_group_external::delete_group_members_returns()
e757f518 1039 */
5d1017e1
JM
1040 public static function delete_groups_returns() {
1041 return core_group_external::delete_group_members_returns();
1042 }
1043
1044
1045 /**
1046 * Returns description of method parameters
4615817d 1047 *
5d1017e1 1048 * @return external_function_parameters
4615817d
JM
1049 * @since Moodle 2.0
1050 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1051 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1052 * @see core_group_external::get_group_members_parameters()
5d1017e1
JM
1053 */
1054 public static function get_groupmembers_parameters() {
1055 return core_group_external::get_group_members_parameters();
1056 }
1057
1058 /**
1059 * Return all members for a group
4615817d 1060 *
5d1017e1
JM
1061 * @param array $groupids array of group ids
1062 * @return array with group id keys containing arrays of user ids
4615817d
JM
1063 * @since Moodle 2.0
1064 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1065 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1066 * @see core_group_external::get_group_members()
5d1017e1
JM
1067 */
1068 public static function get_groupmembers($groupids) {
1069 return core_group_external::get_group_members($groupids);
1070 }
1071
e757f518
EL
1072 /**
1073 * Returns description of method result value
4615817d 1074 *
e757f518 1075 * @return external_description
4615817d
JM
1076 * @since Moodle 2.0
1077 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1078 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1079 * @see core_group_external::get_group_members_returns()
e757f518 1080 */
5d1017e1
JM
1081 public static function get_groupmembers_returns() {
1082 return core_group_external::get_group_members_returns();
1083 }
1084
1085
1086 /**
1087 * Returns description of method parameters
4615817d 1088 *
5d1017e1 1089 * @return external_function_parameters
4615817d
JM
1090 * @since Moodle 2.0
1091 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1092 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1093 * @see core_group_external::add_group_members_parameters()
5d1017e1
JM
1094 */
1095 public static function add_groupmembers_parameters() {
1096 return core_group_external::add_group_members_parameters();
1097 }
1098
1099 /**
1100 * Add group members
4615817d 1101 *
5d1017e1 1102 * @param array $members of arrays with keys userid, groupid
4615817d
JM
1103 * @since Moodle 2.0
1104 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1105 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1106 * @see use core_group_external::add_group_members()
5d1017e1
JM
1107 */
1108 public static function add_groupmembers($members) {
1109 return core_group_external::add_group_members($members);
1110 }
1111
e757f518
EL
1112 /**
1113 * Returns description of method result value
4615817d 1114 *
e757f518 1115 * @return external_description
4615817d
JM
1116 * @since Moodle 2.0
1117 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1118 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1119 * @see core_group_external::add_group_members_returns()
e757f518 1120 */
5d1017e1
JM
1121 public static function add_groupmembers_returns() {
1122 return core_group_external::add_group_members_returns();
1123 }
1124
1125
1126 /**
1127 * Returns description of method parameters
4615817d 1128 *
5d1017e1 1129 * @return external_function_parameters
4615817d
JM
1130 * @since Moodle 2.0
1131 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1132 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1133 * @see core_group_external::delete_group_members_parameters()
5d1017e1
JM
1134 */
1135 public static function delete_groupmembers_parameters() {
1136 return core_group_external::delete_group_members_parameters();
1137 }
1138
1139 /**
1140 * Delete group members
4615817d 1141 *
5d1017e1 1142 * @param array $members of arrays with keys userid, groupid
4615817d
JM
1143 * @since Moodle 2.0
1144 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1145 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1146 * @see core_group_external::delete_group_members()
5d1017e1
JM
1147 */
1148 public static function delete_groupmembers($members) {
1149 return core_group_external::delete_group_members($members);
1150 }
1151
e757f518
EL
1152 /**
1153 * Returns description of method result value
4615817d 1154 *
e757f518 1155 * @return external_description
4615817d
JM
1156 * @since Moodle 2.0
1157 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1158 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1159 * @see core_group_external::delete_group_members_returns()
e757f518 1160 */
5d1017e1
JM
1161 public static function delete_groupmembers_returns() {
1162 return core_group_external::delete_group_members_returns();
1163 }
1164
e757f518 1165}