MDL-32662 Added update_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
4ca6cfbf 729}
5d1017e1
JM
730
731/**
4615817d
JM
732 * Deprecated group external functions
733 *
734 * @package core_group
735 * @copyright 2009 Petr Skodak
736 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
737 * @since Moodle 2.0
738 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
739 * @todo MDL-31194 This will be deleted in Moodle 2.5.
740 * @see core_group_external
5d1017e1
JM
741 */
742class moodle_group_external extends external_api {
743
744 /**
745 * Returns description of method parameters
4615817d 746 *
5d1017e1 747 * @return external_function_parameters
4615817d
JM
748 * @since Moodle 2.0
749 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
750 * @todo MDL-31194 This will be deleted in Moodle 2.5.
751 * @see core_group_external::create_groups_parameters()
5d1017e1
JM
752 */
753 public static function create_groups_parameters() {
754 return core_group_external::create_groups_parameters();
755 }
756
757 /**
758 * Create groups
4615817d 759 *
5d1017e1
JM
760 * @param array $groups array of group description arrays (with keys groupname and courseid)
761 * @return array of newly created groups
4615817d
JM
762 * @since Moodle 2.0
763 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
764 * @todo MDL-31194 This will be deleted in Moodle 2.5.
765 * @see use core_group_external::create_groups()
5d1017e1
JM
766 */
767 public static function create_groups($groups) {
768 return core_group_external::create_groups($groups);
769 }
770
e757f518
EL
771 /**
772 * Returns description of method result value
4615817d 773 *
e757f518 774 * @return external_description
4615817d
JM
775 * @since Moodle 2.0
776 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
777 * @todo MDL-31194 This will be deleted in Moodle 2.5.
778 * @see core_group_external::create_groups_returns()
e757f518 779 */
5d1017e1
JM
780 public static function create_groups_returns() {
781 return core_group_external::create_groups_returns();
782 }
783
784 /**
785 * Returns description of method parameters
4615817d 786 *
5d1017e1 787 * @return external_function_parameters
4615817d
JM
788 * @since Moodle 2.0
789 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
790 * @todo MDL-31194 This will be deleted in Moodle 2.5.
791 * @see core_group_external::get_groups_parameters()
5d1017e1
JM
792 */
793 public static function get_groups_parameters() {
794 return core_group_external::get_groups_parameters();
795 }
796
797 /**
798 * Get groups definition specified by ids
4615817d 799 *
5d1017e1
JM
800 * @param array $groupids arrays of group ids
801 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d
JM
802 * @since Moodle 2.0
803 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
804 * @todo MDL-31194 This will be deleted in Moodle 2.5.
805 * @see core_group_external::get_groups()
5d1017e1
JM
806 */
807 public static function get_groups($groupids) {
808 return core_group_external::get_groups($groupids);
809 }
810
e757f518
EL
811 /**
812 * Returns description of method result value
4615817d 813 *
e757f518 814 * @return external_description
4615817d
JM
815 * @since Moodle 2.0
816 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
817 * @todo MDL-31194 This will be deleted in Moodle 2.5.
818 * @see core_group_external::get_groups_returns()
e757f518 819 */
5d1017e1
JM
820 public static function get_groups_returns() {
821 return core_group_external::get_groups_returns();
822 }
823
e757f518
EL
824 /**
825 * Returns description of method parameters
4615817d 826 *
e757f518 827 * @return external_function_parameters
4615817d
JM
828 * @since Moodle 2.0
829 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
830 * @todo MDL-31194 This will be deleted in Moodle 2.5.
831 * @see core_group_external::get_course_groups_parameters()
e757f518 832 */
5d1017e1
JM
833 public static function get_course_groups_parameters() {
834 return core_group_external::get_course_groups_parameters();
835 }
836
e757f518
EL
837 /**
838 * Get all groups in the specified course
4615817d 839 *
e757f518
EL
840 * @param int $courseid id of course
841 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d
JM
842 * @since Moodle 2.0
843 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
844 * @todo MDL-31194 This will be deleted in Moodle 2.5.
845 * @see core_group_external::get_course_groups()
e757f518 846 */
5d1017e1
JM
847 public static function get_course_groups($courseid) {
848 return core_group_external::get_course_groups($courseid);
849 }
850
e757f518
EL
851 /**
852 * Returns description of method result value
4615817d 853 *
e757f518 854 * @return external_description
4615817d
JM
855 * @since Moodle 2.0
856 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
857 * @todo MDL-31194 This will be deleted in Moodle 2.5.
858 * @see core_group_external::get_course_groups_returns()
e757f518 859 */
5d1017e1
JM
860 public static function get_course_groups_returns() {
861 return core_group_external::get_course_groups_returns();
862 }
863
864 /**
865 * Returns description of method parameters
4615817d 866 *
5d1017e1 867 * @return external_function_parameters
4615817d
JM
868 * @since Moodle 2.0
869 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
870 * @todo MDL-31194 This will be deleted in Moodle 2.5.
871 * @see core_group_external::delete_group_members_parameters()
5d1017e1
JM
872 */
873 public static function delete_groups_parameters() {
874 return core_group_external::delete_group_members_parameters();
875 }
876
877 /**
878 * Delete groups
4615817d 879 *
5d1017e1 880 * @param array $groupids array of group ids
4615817d
JM
881 * @since Moodle 2.0
882 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
883 * @todo MDL-31194 This will be deleted in Moodle 2.5.
884 * @see core_group_external::delete_groups()
5d1017e1
JM
885 */
886 public static function delete_groups($groupids) {
887 return core_group_external::delete_groups($groupids);
888 }
889
e757f518
EL
890 /**
891 * Returns description of method result value
4615817d
JM
892 *
893 * @return null
894 * @since Moodle 2.0
895 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
896 * @todo MDL-31194 This will be deleted in Moodle 2.5.
e757f518 897 * @see core_group_external::delete_group_members_returns()
e757f518 898 */
5d1017e1
JM
899 public static function delete_groups_returns() {
900 return core_group_external::delete_group_members_returns();
901 }
902
903
904 /**
905 * Returns description of method parameters
4615817d 906 *
5d1017e1 907 * @return external_function_parameters
4615817d
JM
908 * @since Moodle 2.0
909 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
910 * @todo MDL-31194 This will be deleted in Moodle 2.5.
911 * @see core_group_external::get_group_members_parameters()
5d1017e1
JM
912 */
913 public static function get_groupmembers_parameters() {
914 return core_group_external::get_group_members_parameters();
915 }
916
917 /**
918 * Return all members for a group
4615817d 919 *
5d1017e1
JM
920 * @param array $groupids array of group ids
921 * @return array with group id keys containing arrays of user ids
4615817d
JM
922 * @since Moodle 2.0
923 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
924 * @todo MDL-31194 This will be deleted in Moodle 2.5.
925 * @see core_group_external::get_group_members()
5d1017e1
JM
926 */
927 public static function get_groupmembers($groupids) {
928 return core_group_external::get_group_members($groupids);
929 }
930
e757f518
EL
931 /**
932 * Returns description of method result value
4615817d 933 *
e757f518 934 * @return external_description
4615817d
JM
935 * @since Moodle 2.0
936 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
937 * @todo MDL-31194 This will be deleted in Moodle 2.5.
938 * @see core_group_external::get_group_members_returns()
e757f518 939 */
5d1017e1
JM
940 public static function get_groupmembers_returns() {
941 return core_group_external::get_group_members_returns();
942 }
943
944
945 /**
946 * Returns description of method parameters
4615817d 947 *
5d1017e1 948 * @return external_function_parameters
4615817d
JM
949 * @since Moodle 2.0
950 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
951 * @todo MDL-31194 This will be deleted in Moodle 2.5.
952 * @see core_group_external::add_group_members_parameters()
5d1017e1
JM
953 */
954 public static function add_groupmembers_parameters() {
955 return core_group_external::add_group_members_parameters();
956 }
957
958 /**
959 * Add group members
4615817d 960 *
5d1017e1 961 * @param array $members of arrays with keys userid, groupid
4615817d
JM
962 * @since Moodle 2.0
963 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
964 * @todo MDL-31194 This will be deleted in Moodle 2.5.
965 * @see use core_group_external::add_group_members()
5d1017e1
JM
966 */
967 public static function add_groupmembers($members) {
968 return core_group_external::add_group_members($members);
969 }
970
e757f518
EL
971 /**
972 * Returns description of method result value
4615817d 973 *
e757f518 974 * @return external_description
4615817d
JM
975 * @since Moodle 2.0
976 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
977 * @todo MDL-31194 This will be deleted in Moodle 2.5.
978 * @see core_group_external::add_group_members_returns()
e757f518 979 */
5d1017e1
JM
980 public static function add_groupmembers_returns() {
981 return core_group_external::add_group_members_returns();
982 }
983
984
985 /**
986 * Returns description of method parameters
4615817d 987 *
5d1017e1 988 * @return external_function_parameters
4615817d
JM
989 * @since Moodle 2.0
990 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
991 * @todo MDL-31194 This will be deleted in Moodle 2.5.
992 * @see core_group_external::delete_group_members_parameters()
5d1017e1
JM
993 */
994 public static function delete_groupmembers_parameters() {
995 return core_group_external::delete_group_members_parameters();
996 }
997
998 /**
999 * Delete group members
4615817d 1000 *
5d1017e1 1001 * @param array $members of arrays with keys userid, groupid
4615817d
JM
1002 * @since Moodle 2.0
1003 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1004 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1005 * @see core_group_external::delete_group_members()
5d1017e1
JM
1006 */
1007 public static function delete_groupmembers($members) {
1008 return core_group_external::delete_group_members($members);
1009 }
1010
e757f518
EL
1011 /**
1012 * Returns description of method result value
4615817d 1013 *
e757f518 1014 * @return external_description
4615817d
JM
1015 * @since Moodle 2.0
1016 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1017 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1018 * @see core_group_external::delete_group_members_returns()
e757f518 1019 */
5d1017e1
JM
1020 public static function delete_groupmembers_returns() {
1021 return core_group_external::delete_group_members_returns();
1022 }
1023
e757f518 1024}