MDL-12886 one more external group function, other minor fixes
[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 /**
127 * Get groups definition
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) {
9a0df45a 132 $groups = array();
133
c9c5cc81 134 $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
0c96468c 135
0c96468c 136 foreach ($params['groupids'] as $groupid) {
ab9a01f2 137 // validate params
ab9a01f2 138 $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
139
9a0df45a 140 // now security checks
141 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
142 self::validate_context($context);
143 require_capability('moodle/course:managegroups', $context);
144
2e13b916 145 $groups[] = (array)$group;
9a0df45a 146 }
147
148 return $groups;
149 }
150
f5072177 151 /**
152 * Returns description of method result value
153 * @return external_description
154 */
0c96468c 155 public static function get_groups_returns() {
8c772ad7 156 return new external_multiple_structure(
157 new external_single_structure(
158 array(
f5072177 159 'id' => new external_value(PARAM_INT, 'group record id'),
160 'courseid' => new external_value(PARAM_INT, 'id of course'),
04d212ce 161 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
f5072177 162 'description' => new external_value(PARAM_RAW, 'group description text'),
163 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
8c772ad7 164 )
165 )
166 );
0c96468c 167 }
168
169 public static function delete_groups_parameters() {
170 //TODO
171 }
172
9a0df45a 173 /**
174 * Delete groups
b4c1a34e 175 * @param array $groupids array of group ids
9a0df45a 176 * @return void
177 */
b4c1a34e 178 public static function delete_groups($groupids) {
9a0df45a 179 global $CFG;
180 require_once("$CFG->dirroot/group/lib.php");
181
c9c5cc81 182 $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
0c96468c 183
9a0df45a 184 $groups = array();
185
0c96468c 186 foreach ($params['groupids'] as $groupid) {
ab9a01f2 187 // validate params
188 $groupid = validate_param($groupid, PARAM_INTEGER);
9a0df45a 189 if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
190 // silently ignore attempts to delete nonexisting groups
191 continue;
192 }
ab9a01f2 193
9a0df45a 194 // now security checks
195 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
196 self::validate_context($context);
197 require_capability('moodle/course:managegroups', $context);
198
199 groups_delete_group($group);
200 }
201 }
202
0c96468c 203 public static function delete_groups_returns() {
204 //TODO
205 }
206
207
208 public static function get_groupmembers_parameters() {
209 //TODO
210 }
9a0df45a 211
212 /**
213 * Return all members for a group
b4c1a34e 214 * @param array $groupids array of group ids
9a0df45a 215 * @return array with group id keys containing arrays of user ids
216 */
b4c1a34e 217 public static function get_groupmembers($groupids) {
9a0df45a 218 $groups = array();
219
c9c5cc81 220 $params = self::validate_parameters(self::get_groupmembers_parameters(), array('groupids'=>$groupids));
0c96468c 221
222 foreach ($params['groupids'] as $groupid) {
ab9a01f2 223 // validate params
9a0df45a 224 $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
225 // now security checks
226 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
227 self::validate_context($context);
228 require_capability('moodle/course:managegroups', $context);
229
230 $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
231
232 $groups[$group->id] = array_keys($groupmembers);
233 }
234
235 return $groups;
236 }
237
0c96468c 238 public static function get_groupmembers_returns() {
239 //TODO
240 }
241
242
243 public static function add_groupmembers_parameters() {
244 //TODO
245 }
9a0df45a 246
247 /**
248 * Add group members
b4c1a34e 249 * @param array $members of arrays with keys userid, groupid
9a0df45a 250 * @return void
251 */
b4c1a34e 252 public static function add_groupmembers($members) {
9a0df45a 253 global $CFG;
254 require_once("$CFG->dirroot/group/lib.php");
255
c9c5cc81 256 $params = self::validate_parameters(self::add_groupmembers_parameters(), array('members'=>$members));
9a0df45a 257
b4c1a34e 258 foreach ($params['members'] as $member) {
ab9a01f2 259 // validate params
0c96468c 260 $groupid = $member['groupid'];
261 $userid = $member['userid'];
262
9a0df45a 263 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
ab9a01f2 264 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 265
266 // now security checks
267 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
268 self::validate_context($context);
269 require_capability('moodle/course:managegroups', $context);
270 require_capability('moodle/course:view', $context, $user->id, false); // only enrolled users may be members of group!!!
271
272 groups_add_member($group, $user);
273 }
274 }
275
0c96468c 276 public static function add_groupmembers_returns() {
277 //TODO
278 }
279
280
281 public static function delete_groupmembers_parameters() {
282 //TODO
283 }
9a0df45a 284
285 /**
286 * Delete group members
b4c1a34e 287 * @param array $members of arrays with keys userid, groupid
9a0df45a 288 * @return void
289 */
b4c1a34e 290 public static function delete_groupmembers($members) {
9a0df45a 291 global $CFG;
292 require_once("$CFG->dirroot/group/lib.php");
293
c9c5cc81 294 $params = self::validate_parameters(self::delete_groupmembers_parameters(), array($members=>'members'));
9a0df45a 295
0c96468c 296 foreach ($params['members'] as $member) {
ab9a01f2 297 // validate params
0c96468c 298 $groupid = $member['groupid'];
299 $userid = $member['userid'];
300
ab9a01f2 301 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
302 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 303
304 // now security checks
305 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
306 self::validate_context($context);
307 require_capability('moodle/course:managegroups', $context);
308
309 groups_remove_member($group, $user);
310 }
311 }
312
0c96468c 313 public static function delete_groupmembers_returns() {
314 //TODO
315 }
316
9a0df45a 317}