MDL-12886 inproved hadnling of bool ws params and return values
[moodle.git] / group / externallib.php
CommitLineData
9a0df45a 1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * External groups API
20 *
21 * @package moodlecore
22 * @subpackage webservice
551f4420 23 * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
9a0df45a 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27require_once("$CFG->libdir/externallib.php");
28
29class moodle_group_external extends external_api {
30
0c96468c 31 /**
32 * Returns description of method parameters
f5072177 33 * @return external_function_parameters
0c96468c 34 */
35 public static function create_groups_parameters() {
f5072177 36 return new external_function_parameters(
37 array(
38 'groups' => new external_multiple_structure(
39 new external_single_structure(
40 array(
41 'courseid' => new external_value(PARAM_INT, 'id of course'),
42 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
43 'description' => new external_value(PARAM_RAW, 'group description text'),
44 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
45 )
46 )
47 )
48 )
49 );
0c96468c 50 }
51
52 /**
9a0df45a 53 * Create groups
b4c1a34e 54 * @param array $groups array of group description arrays (with keys groupname and courseid)
f5072177 55 * @return array of newly created groups
9a0df45a 56 */
b4c1a34e 57 public static function create_groups($groups) {
f5072177 58 global $CFG, $DB;
9a0df45a 59 require_once("$CFG->dirroot/group/lib.php");
60
c9c5cc81 61 $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
0c96468c 62
f5072177 63 // ideally create all groups or none at all, unfortunately myisam engine does not support transactions :-(
64 $DB->begin_sql();
65 try {
66 $groups = array();
67
68 foreach ($params['groups'] as $group) {
69 $group = (object)$group;
70
71 if (trim($group->name) == '') {
72 throw new invalid_parameter_exception('Invalid group name');
73 }
74 if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
75 throw new invalid_parameter_exception('Group with the same name already exists in the course');
76 }
77
78 // now security checks
79 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
80 self::validate_context($context);
81 require_capability('moodle/course:managegroups', $context);
82
83 // finally create the group
84 $group->id = groups_create_group($group, false);
85 $groups[] = (array)$group;
ab9a01f2 86 }
f5072177 87 } catch (Exception $ex) {
88 $DB->rollback_sql();
89 throw $ex;
9a0df45a 90 }
f5072177 91 $DB->commit_sql();
9a0df45a 92
2e13b916 93 return $groups;
9a0df45a 94 }
95
0c96468c 96 /**
97 * Returns description of method result value
f5072177 98 * @return external_description
0c96468c 99 */
100 public static function create_groups_returns() {
f5072177 101 return new external_multiple_structure(
102 new external_single_structure(
103 array(
104 'id' => new external_value(PARAM_INT, 'group record id'),
105 'courseid' => new external_value(PARAM_INT, 'id of course'),
106 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
107 'description' => new external_value(PARAM_RAW, 'group description text'),
108 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
109 )
110 )
111 );
0c96468c 112 }
113
f5072177 114 /**
115 * Returns description of method parameters
116 * @return external_function_parameters
117 */
0c96468c 118 public static function get_groups_parameters() {
8c772ad7 119 return new external_function_parameters(
120 array(
f5072177 121 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
8c772ad7 122 )
123 );
0c96468c 124 }
125
9a0df45a 126 /**
246f6da2 127 * Get groups definition specified by ids
b4c1a34e 128 * @param array $groupids arrays of group ids
9a0df45a 129 * @return array of group objects (id, courseid, name, enrolmentkey)
130 */
b4c1a34e 131 public static function get_groups($groupids) {
c9c5cc81 132 $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
0c96468c 133
246f6da2 134 $groups = array();
0c96468c 135 foreach ($params['groupids'] as $groupid) {
ab9a01f2 136 // validate params
ab9a01f2 137 $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
138
9a0df45a 139 // now security checks
140 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
141 self::validate_context($context);
142 require_capability('moodle/course:managegroups', $context);
143
2e13b916 144 $groups[] = (array)$group;
9a0df45a 145 }
146
147 return $groups;
148 }
149
f5072177 150 /**
151 * Returns description of method result value
152 * @return external_description
153 */
0c96468c 154 public static function get_groups_returns() {
246f6da2 155 return new external_multiple_structure(
156 new external_single_structure(
157 array(
158 'id' => new external_value(PARAM_INT, 'group record id'),
159 'courseid' => new external_value(PARAM_INT, 'id of course'),
160 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
161 'description' => new external_value(PARAM_RAW, 'group description text'),
162 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
163 )
164 )
165 );
166 }
167
168 /**
169 * Returns description of method parameters
170 * @return external_function_parameters
171 */
172 public static function get_course_groups_parameters() {
173 return new external_function_parameters(
174 array(
175 'courseid' => new external_value(PARAM_INT, 'id of course'),
176 )
177 );
178 }
179
180 /**
181 * Get all groups in the specified course
182 * @param int $courseid id of course
183 * @return array of group objects (id, courseid, name, enrolmentkey)
184 */
185 public static function get_course_groups($courseid) {
186 $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
187
188 // now security checks
189 $context = get_context_instance(CONTEXT_COURSE, $params['courseid']);
190 self::validate_context($context);
191 require_capability('moodle/course:managegroups', $context);
192
193 $gs = groups_get_all_groups($params['courseid'], 0, 0, 'g.id, g.courseid, g.name, g.description, g.enrolmentkey');
194
195 $groups = array();
196 foreach ($gs as $group) {
197 $groups[] = (array)$group;
198 }
199
200 return $groups;
201 }
202
203 /**
204 * Returns description of method result value
205 * @return external_description
206 */
207 public static function get_course_groups_returns() {
8c772ad7 208 return new external_multiple_structure(
209 new external_single_structure(
210 array(
f5072177 211 'id' => new external_value(PARAM_INT, 'group record id'),
212 'courseid' => new external_value(PARAM_INT, 'id of course'),
04d212ce 213 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
f5072177 214 'description' => new external_value(PARAM_RAW, 'group description text'),
215 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
8c772ad7 216 )
217 )
218 );
0c96468c 219 }
220
221 public static function delete_groups_parameters() {
222 //TODO
223 }
224
9a0df45a 225 /**
226 * Delete groups
b4c1a34e 227 * @param array $groupids array of group ids
9a0df45a 228 * @return void
229 */
b4c1a34e 230 public static function delete_groups($groupids) {
9a0df45a 231 global $CFG;
232 require_once("$CFG->dirroot/group/lib.php");
233
c9c5cc81 234 $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
0c96468c 235
9a0df45a 236 $groups = array();
237
0c96468c 238 foreach ($params['groupids'] as $groupid) {
ab9a01f2 239 // validate params
240 $groupid = validate_param($groupid, PARAM_INTEGER);
9a0df45a 241 if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
242 // silently ignore attempts to delete nonexisting groups
243 continue;
244 }
ab9a01f2 245
9a0df45a 246 // now security checks
247 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
248 self::validate_context($context);
249 require_capability('moodle/course:managegroups', $context);
250
251 groups_delete_group($group);
252 }
253 }
254
0c96468c 255 public static function delete_groups_returns() {
256 //TODO
257 }
258
259
260 public static function get_groupmembers_parameters() {
261 //TODO
262 }
9a0df45a 263
264 /**
265 * Return all members for a group
b4c1a34e 266 * @param array $groupids array of group ids
9a0df45a 267 * @return array with group id keys containing arrays of user ids
268 */
b4c1a34e 269 public static function get_groupmembers($groupids) {
9a0df45a 270 $groups = array();
271
c9c5cc81 272 $params = self::validate_parameters(self::get_groupmembers_parameters(), array('groupids'=>$groupids));
0c96468c 273
274 foreach ($params['groupids'] as $groupid) {
ab9a01f2 275 // validate params
9a0df45a 276 $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
277 // now security checks
278 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
279 self::validate_context($context);
280 require_capability('moodle/course:managegroups', $context);
281
282 $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
283
284 $groups[$group->id] = array_keys($groupmembers);
285 }
286
287 return $groups;
288 }
289
0c96468c 290 public static function get_groupmembers_returns() {
291 //TODO
292 }
293
294
295 public static function add_groupmembers_parameters() {
296 //TODO
297 }
9a0df45a 298
299 /**
300 * Add group members
b4c1a34e 301 * @param array $members of arrays with keys userid, groupid
9a0df45a 302 * @return void
303 */
b4c1a34e 304 public static function add_groupmembers($members) {
9a0df45a 305 global $CFG;
306 require_once("$CFG->dirroot/group/lib.php");
307
c9c5cc81 308 $params = self::validate_parameters(self::add_groupmembers_parameters(), array('members'=>$members));
9a0df45a 309
b4c1a34e 310 foreach ($params['members'] as $member) {
ab9a01f2 311 // validate params
0c96468c 312 $groupid = $member['groupid'];
313 $userid = $member['userid'];
314
9a0df45a 315 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
ab9a01f2 316 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 317
318 // now security checks
319 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
320 self::validate_context($context);
321 require_capability('moodle/course:managegroups', $context);
322 require_capability('moodle/course:view', $context, $user->id, false); // only enrolled users may be members of group!!!
323
324 groups_add_member($group, $user);
325 }
326 }
327
0c96468c 328 public static function add_groupmembers_returns() {
329 //TODO
330 }
331
332
333 public static function delete_groupmembers_parameters() {
334 //TODO
335 }
9a0df45a 336
337 /**
338 * Delete group members
b4c1a34e 339 * @param array $members of arrays with keys userid, groupid
9a0df45a 340 * @return void
341 */
b4c1a34e 342 public static function delete_groupmembers($members) {
9a0df45a 343 global $CFG;
344 require_once("$CFG->dirroot/group/lib.php");
345
c9c5cc81 346 $params = self::validate_parameters(self::delete_groupmembers_parameters(), array($members=>'members'));
9a0df45a 347
0c96468c 348 foreach ($params['members'] as $member) {
ab9a01f2 349 // validate params
0c96468c 350 $groupid = $member['groupid'];
351 $userid = $member['userid'];
352
ab9a01f2 353 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
354 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 355
356 // now security checks
357 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
358 self::validate_context($context);
359 require_capability('moodle/course:managegroups', $context);
360
361 groups_remove_member($group, $user);
362 }
363 }
364
0c96468c 365 public static function delete_groupmembers_returns() {
366 //TODO
367 }
368
9a0df45a 369}