MDL-32662 Added get_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
4ca6cfbf 800}
5d1017e1
JM
801
802/**
4615817d
JM
803 * Deprecated group external functions
804 *
805 * @package core_group
806 * @copyright 2009 Petr Skodak
807 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
808 * @since Moodle 2.0
809 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
810 * @todo MDL-31194 This will be deleted in Moodle 2.5.
811 * @see core_group_external
5d1017e1
JM
812 */
813class moodle_group_external extends external_api {
814
815 /**
816 * Returns description of method parameters
4615817d 817 *
5d1017e1 818 * @return external_function_parameters
4615817d
JM
819 * @since Moodle 2.0
820 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
821 * @todo MDL-31194 This will be deleted in Moodle 2.5.
822 * @see core_group_external::create_groups_parameters()
5d1017e1
JM
823 */
824 public static function create_groups_parameters() {
825 return core_group_external::create_groups_parameters();
826 }
827
828 /**
829 * Create groups
4615817d 830 *
5d1017e1
JM
831 * @param array $groups array of group description arrays (with keys groupname and courseid)
832 * @return array of newly created groups
4615817d
JM
833 * @since Moodle 2.0
834 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
835 * @todo MDL-31194 This will be deleted in Moodle 2.5.
836 * @see use core_group_external::create_groups()
5d1017e1
JM
837 */
838 public static function create_groups($groups) {
839 return core_group_external::create_groups($groups);
840 }
841
e757f518
EL
842 /**
843 * Returns description of method result value
4615817d 844 *
e757f518 845 * @return external_description
4615817d
JM
846 * @since Moodle 2.0
847 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
848 * @todo MDL-31194 This will be deleted in Moodle 2.5.
849 * @see core_group_external::create_groups_returns()
e757f518 850 */
5d1017e1
JM
851 public static function create_groups_returns() {
852 return core_group_external::create_groups_returns();
853 }
854
855 /**
856 * Returns description of method parameters
4615817d 857 *
5d1017e1 858 * @return external_function_parameters
4615817d
JM
859 * @since Moodle 2.0
860 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
861 * @todo MDL-31194 This will be deleted in Moodle 2.5.
862 * @see core_group_external::get_groups_parameters()
5d1017e1
JM
863 */
864 public static function get_groups_parameters() {
865 return core_group_external::get_groups_parameters();
866 }
867
868 /**
869 * Get groups definition specified by ids
4615817d 870 *
5d1017e1
JM
871 * @param array $groupids arrays of group ids
872 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d
JM
873 * @since Moodle 2.0
874 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
875 * @todo MDL-31194 This will be deleted in Moodle 2.5.
876 * @see core_group_external::get_groups()
5d1017e1
JM
877 */
878 public static function get_groups($groupids) {
879 return core_group_external::get_groups($groupids);
880 }
881
e757f518
EL
882 /**
883 * Returns description of method result value
4615817d 884 *
e757f518 885 * @return external_description
4615817d
JM
886 * @since Moodle 2.0
887 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
888 * @todo MDL-31194 This will be deleted in Moodle 2.5.
889 * @see core_group_external::get_groups_returns()
e757f518 890 */
5d1017e1
JM
891 public static function get_groups_returns() {
892 return core_group_external::get_groups_returns();
893 }
894
e757f518
EL
895 /**
896 * Returns description of method parameters
4615817d 897 *
e757f518 898 * @return external_function_parameters
4615817d
JM
899 * @since Moodle 2.0
900 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
901 * @todo MDL-31194 This will be deleted in Moodle 2.5.
902 * @see core_group_external::get_course_groups_parameters()
e757f518 903 */
5d1017e1
JM
904 public static function get_course_groups_parameters() {
905 return core_group_external::get_course_groups_parameters();
906 }
907
e757f518
EL
908 /**
909 * Get all groups in the specified course
4615817d 910 *
e757f518
EL
911 * @param int $courseid id of course
912 * @return array of group objects (id, courseid, name, enrolmentkey)
4615817d
JM
913 * @since Moodle 2.0
914 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
915 * @todo MDL-31194 This will be deleted in Moodle 2.5.
916 * @see core_group_external::get_course_groups()
e757f518 917 */
5d1017e1
JM
918 public static function get_course_groups($courseid) {
919 return core_group_external::get_course_groups($courseid);
920 }
921
e757f518
EL
922 /**
923 * Returns description of method result value
4615817d 924 *
e757f518 925 * @return external_description
4615817d
JM
926 * @since Moodle 2.0
927 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
928 * @todo MDL-31194 This will be deleted in Moodle 2.5.
929 * @see core_group_external::get_course_groups_returns()
e757f518 930 */
5d1017e1
JM
931 public static function get_course_groups_returns() {
932 return core_group_external::get_course_groups_returns();
933 }
934
935 /**
936 * Returns description of method parameters
4615817d 937 *
5d1017e1 938 * @return external_function_parameters
4615817d
JM
939 * @since Moodle 2.0
940 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
941 * @todo MDL-31194 This will be deleted in Moodle 2.5.
942 * @see core_group_external::delete_group_members_parameters()
5d1017e1
JM
943 */
944 public static function delete_groups_parameters() {
945 return core_group_external::delete_group_members_parameters();
946 }
947
948 /**
949 * Delete groups
4615817d 950 *
5d1017e1 951 * @param array $groupids array of group ids
4615817d
JM
952 * @since Moodle 2.0
953 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
954 * @todo MDL-31194 This will be deleted in Moodle 2.5.
955 * @see core_group_external::delete_groups()
5d1017e1
JM
956 */
957 public static function delete_groups($groupids) {
958 return core_group_external::delete_groups($groupids);
959 }
960
e757f518
EL
961 /**
962 * Returns description of method result value
4615817d
JM
963 *
964 * @return null
965 * @since Moodle 2.0
966 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
967 * @todo MDL-31194 This will be deleted in Moodle 2.5.
e757f518 968 * @see core_group_external::delete_group_members_returns()
e757f518 969 */
5d1017e1
JM
970 public static function delete_groups_returns() {
971 return core_group_external::delete_group_members_returns();
972 }
973
974
975 /**
976 * Returns description of method parameters
4615817d 977 *
5d1017e1 978 * @return external_function_parameters
4615817d
JM
979 * @since Moodle 2.0
980 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
981 * @todo MDL-31194 This will be deleted in Moodle 2.5.
982 * @see core_group_external::get_group_members_parameters()
5d1017e1
JM
983 */
984 public static function get_groupmembers_parameters() {
985 return core_group_external::get_group_members_parameters();
986 }
987
988 /**
989 * Return all members for a group
4615817d 990 *
5d1017e1
JM
991 * @param array $groupids array of group ids
992 * @return array with group id keys containing arrays of user ids
4615817d
JM
993 * @since Moodle 2.0
994 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
995 * @todo MDL-31194 This will be deleted in Moodle 2.5.
996 * @see core_group_external::get_group_members()
5d1017e1
JM
997 */
998 public static function get_groupmembers($groupids) {
999 return core_group_external::get_group_members($groupids);
1000 }
1001
e757f518
EL
1002 /**
1003 * Returns description of method result value
4615817d 1004 *
e757f518 1005 * @return external_description
4615817d
JM
1006 * @since Moodle 2.0
1007 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1008 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1009 * @see core_group_external::get_group_members_returns()
e757f518 1010 */
5d1017e1
JM
1011 public static function get_groupmembers_returns() {
1012 return core_group_external::get_group_members_returns();
1013 }
1014
1015
1016 /**
1017 * Returns description of method parameters
4615817d 1018 *
5d1017e1 1019 * @return external_function_parameters
4615817d
JM
1020 * @since Moodle 2.0
1021 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1022 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1023 * @see core_group_external::add_group_members_parameters()
5d1017e1
JM
1024 */
1025 public static function add_groupmembers_parameters() {
1026 return core_group_external::add_group_members_parameters();
1027 }
1028
1029 /**
1030 * Add group members
4615817d 1031 *
5d1017e1 1032 * @param array $members of arrays with keys userid, groupid
4615817d
JM
1033 * @since Moodle 2.0
1034 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1035 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1036 * @see use core_group_external::add_group_members()
5d1017e1
JM
1037 */
1038 public static function add_groupmembers($members) {
1039 return core_group_external::add_group_members($members);
1040 }
1041
e757f518
EL
1042 /**
1043 * Returns description of method result value
4615817d 1044 *
e757f518 1045 * @return external_description
4615817d
JM
1046 * @since Moodle 2.0
1047 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1048 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1049 * @see core_group_external::add_group_members_returns()
e757f518 1050 */
5d1017e1
JM
1051 public static function add_groupmembers_returns() {
1052 return core_group_external::add_group_members_returns();
1053 }
1054
1055
1056 /**
1057 * Returns description of method parameters
4615817d 1058 *
5d1017e1 1059 * @return external_function_parameters
4615817d
JM
1060 * @since Moodle 2.0
1061 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1062 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1063 * @see core_group_external::delete_group_members_parameters()
5d1017e1
JM
1064 */
1065 public static function delete_groupmembers_parameters() {
1066 return core_group_external::delete_group_members_parameters();
1067 }
1068
1069 /**
1070 * Delete group members
4615817d 1071 *
5d1017e1 1072 * @param array $members of arrays with keys userid, groupid
4615817d
JM
1073 * @since Moodle 2.0
1074 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1075 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1076 * @see core_group_external::delete_group_members()
5d1017e1
JM
1077 */
1078 public static function delete_groupmembers($members) {
1079 return core_group_external::delete_group_members($members);
1080 }
1081
e757f518
EL
1082 /**
1083 * Returns description of method result value
4615817d 1084 *
e757f518 1085 * @return external_description
4615817d
JM
1086 * @since Moodle 2.0
1087 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1088 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1089 * @see core_group_external::delete_group_members_returns()
e757f518 1090 */
5d1017e1
JM
1091 public static function delete_groupmembers_returns() {
1092 return core_group_external::delete_group_members_returns();
1093 }
1094
e757f518 1095}