blog MDL-23574 fixed filter problem with user blog rss feeds
[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 )
d4c6ef70 46 ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
f5072177 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
d5a8d9aa
PS
63 $transaction = $DB->start_delegated_transaction();
64
65 $groups = array();
66
67 foreach ($params['groups'] as $group) {
68 $group = (object)$group;
69
70 if (trim($group->name) == '') {
71 throw new invalid_parameter_exception('Invalid group name');
72 }
73 if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
74 throw new invalid_parameter_exception('Group with the same name already exists in the course');
ab9a01f2 75 }
d5a8d9aa
PS
76
77 // now security checks
78 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
79 self::validate_context($context);
80 require_capability('moodle/course:managegroups', $context);
81
82 // finally create the group
83 $group->id = groups_create_group($group, false);
84 $groups[] = (array)$group;
9a0df45a 85 }
d5a8d9aa
PS
86
87 $transaction->allow_commit();
9a0df45a 88
2e13b916 89 return $groups;
9a0df45a 90 }
91
0c96468c 92 /**
93 * Returns description of method result value
f5072177 94 * @return external_description
0c96468c 95 */
96 public static function create_groups_returns() {
f5072177 97 return new external_multiple_structure(
98 new external_single_structure(
99 array(
100 'id' => new external_value(PARAM_INT, 'group record id'),
101 'courseid' => new external_value(PARAM_INT, 'id of course'),
102 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
103 'description' => new external_value(PARAM_RAW, 'group description text'),
104 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
105 )
d4c6ef70 106 ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
f5072177 107 );
0c96468c 108 }
109
f5072177 110 /**
111 * Returns description of method parameters
112 * @return external_function_parameters
113 */
0c96468c 114 public static function get_groups_parameters() {
8c772ad7 115 return new external_function_parameters(
116 array(
d4c6ef70 117 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
118 ,'List of group id. A group id is an integer.'),
8c772ad7 119 )
120 );
0c96468c 121 }
122
9a0df45a 123 /**
246f6da2 124 * Get groups definition specified by ids
b4c1a34e 125 * @param array $groupids arrays of group ids
9a0df45a 126 * @return array of group objects (id, courseid, name, enrolmentkey)
127 */
b4c1a34e 128 public static function get_groups($groupids) {
c9c5cc81 129 $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
0c96468c 130
246f6da2 131 $groups = array();
0c96468c 132 foreach ($params['groupids'] as $groupid) {
ab9a01f2 133 // validate params
ab9a01f2 134 $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
135
9a0df45a 136 // now security checks
137 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
138 self::validate_context($context);
139 require_capability('moodle/course:managegroups', $context);
140
2e13b916 141 $groups[] = (array)$group;
9a0df45a 142 }
143
144 return $groups;
145 }
146
f5072177 147 /**
148 * Returns description of method result value
149 * @return external_description
150 */
0c96468c 151 public static function get_groups_returns() {
246f6da2 152 return new external_multiple_structure(
153 new external_single_structure(
154 array(
155 'id' => new external_value(PARAM_INT, 'group record id'),
156 'courseid' => new external_value(PARAM_INT, 'id of course'),
157 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
158 'description' => new external_value(PARAM_RAW, 'group description text'),
159 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
160 )
161 )
162 );
163 }
164
165 /**
166 * Returns description of method parameters
167 * @return external_function_parameters
168 */
169 public static function get_course_groups_parameters() {
170 return new external_function_parameters(
171 array(
172 'courseid' => new external_value(PARAM_INT, 'id of course'),
173 )
174 );
175 }
176
177 /**
178 * Get all groups in the specified course
179 * @param int $courseid id of course
180 * @return array of group objects (id, courseid, name, enrolmentkey)
181 */
182 public static function get_course_groups($courseid) {
183 $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
184
185 // now security checks
186 $context = get_context_instance(CONTEXT_COURSE, $params['courseid']);
187 self::validate_context($context);
188 require_capability('moodle/course:managegroups', $context);
189
190 $gs = groups_get_all_groups($params['courseid'], 0, 0, 'g.id, g.courseid, g.name, g.description, g.enrolmentkey');
191
192 $groups = array();
193 foreach ($gs as $group) {
194 $groups[] = (array)$group;
195 }
196
197 return $groups;
198 }
199
200 /**
201 * Returns description of method result value
202 * @return external_description
203 */
204 public static function get_course_groups_returns() {
8c772ad7 205 return new external_multiple_structure(
206 new external_single_structure(
207 array(
f5072177 208 'id' => new external_value(PARAM_INT, 'group record id'),
209 'courseid' => new external_value(PARAM_INT, 'id of course'),
04d212ce 210 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
f5072177 211 'description' => new external_value(PARAM_RAW, 'group description text'),
212 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
8c772ad7 213 )
214 )
215 );
0c96468c 216 }
217
0f4e72de
PS
218 /**
219 * Returns description of method parameters
220 * @return external_function_parameters
221 */
0c96468c 222 public static function delete_groups_parameters() {
0f4e72de
PS
223 return new external_function_parameters(
224 array(
225 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
226 )
227 );
0c96468c 228 }
229
9a0df45a 230 /**
231 * Delete groups
b4c1a34e 232 * @param array $groupids array of group ids
9a0df45a 233 * @return void
234 */
b4c1a34e 235 public static function delete_groups($groupids) {
2cb1ee78 236 global $CFG, $DB;
9a0df45a 237 require_once("$CFG->dirroot/group/lib.php");
238
c9c5cc81 239 $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
0c96468c 240
d5a8d9aa
PS
241 $transaction = $DB->start_delegated_transaction();
242
6ccaf3f5 243// TODO: this is problematic because the DB rollback does not handle deleting of group images!
d5a8d9aa
PS
244 foreach ($params['groupids'] as $groupid) {
245 // validate params
246 $groupid = validate_param($groupid, PARAM_INTEGER);
247 if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
248 // silently ignore attempts to delete nonexisting groups
249 continue;
0f4e72de 250 }
d5a8d9aa
PS
251
252 // now security checks
253 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
254 self::validate_context($context);
255 require_capability('moodle/course:managegroups', $context);
256
257 groups_delete_group($group);
9a0df45a 258 }
d5a8d9aa
PS
259
260 $transaction->allow_commit();
9a0df45a 261 }
262
0f4e72de
PS
263 /**
264 * Returns description of method result value
265 * @return external_description
266 */
0c96468c 267 public static function delete_groups_returns() {
0f4e72de 268 return null;
0c96468c 269 }
270
271
0f4e72de
PS
272 /**
273 * Returns description of method parameters
274 * @return external_function_parameters
275 */
0c96468c 276 public static function get_groupmembers_parameters() {
0f4e72de
PS
277 return new external_function_parameters(
278 array(
279 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
280 )
281 );
0c96468c 282 }
9a0df45a 283
284 /**
285 * Return all members for a group
b4c1a34e 286 * @param array $groupids array of group ids
9a0df45a 287 * @return array with group id keys containing arrays of user ids
288 */
b4c1a34e 289 public static function get_groupmembers($groupids) {
0f4e72de 290 $members = array();
9a0df45a 291
c9c5cc81 292 $params = self::validate_parameters(self::get_groupmembers_parameters(), array('groupids'=>$groupids));
0c96468c 293
294 foreach ($params['groupids'] as $groupid) {
ab9a01f2 295 // validate params
9a0df45a 296 $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
297 // now security checks
298 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
299 self::validate_context($context);
300 require_capability('moodle/course:managegroups', $context);
301
302 $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
303
0f4e72de 304 $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
9a0df45a 305 }
306
0f4e72de 307 return $members;
9a0df45a 308 }
309
0f4e72de
PS
310 /**
311 * Returns description of method result value
312 * @return external_description
313 */
0c96468c 314 public static function get_groupmembers_returns() {
0f4e72de
PS
315 return new external_multiple_structure(
316 new external_single_structure(
317 array(
318 'groupid' => new external_value(PARAM_INT, 'group record id'),
319 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
320 )
321 )
322 );
0c96468c 323 }
324
325
0f4e72de
PS
326 /**
327 * Returns description of method parameters
328 * @return external_function_parameters
329 */
0c96468c 330 public static function add_groupmembers_parameters() {
4efa2483
PS
331 return new external_function_parameters(
332 array(
333 'members'=> new external_multiple_structure(
334 new external_single_structure(
335 array(
336 'groupid' => new external_value(PARAM_INT, 'group record id'),
337 'userid' => new external_value(PARAM_INT, 'user id'),
338 )
339 )
0f4e72de
PS
340 )
341 )
342 );
0c96468c 343 }
9a0df45a 344
345 /**
346 * Add group members
b4c1a34e 347 * @param array $members of arrays with keys userid, groupid
9a0df45a 348 * @return void
349 */
b4c1a34e 350 public static function add_groupmembers($members) {
2cb1ee78 351 global $CFG, $DB;
9a0df45a 352 require_once("$CFG->dirroot/group/lib.php");
353
c9c5cc81 354 $params = self::validate_parameters(self::add_groupmembers_parameters(), array('members'=>$members));
9a0df45a 355
d5a8d9aa 356 $transaction = $DB->start_delegated_transaction();
d5a8d9aa
PS
357 foreach ($params['members'] as $member) {
358 // validate params
359 $groupid = $member['groupid'];
360 $userid = $member['userid'];
0c96468c 361
d5a8d9aa
PS
362 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
363 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 364
d5a8d9aa
PS
365 // now security checks
366 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
367 self::validate_context($context);
368 require_capability('moodle/course:managegroups', $context);
9a0df45a 369
d5a8d9aa 370 // now make sure user is enrolled in course - this is mandatory requirement,
4f0c2d00
PS
371 // unfortunately this is slow
372 if (!is_enrolled($context, $userid)) {
373 throw new invalid_parameter_exception('Only enrolled users may be members of groups');
374 }
4efa2483 375
d5a8d9aa 376 groups_add_member($group, $user);
9a0df45a 377 }
d5a8d9aa
PS
378
379 $transaction->allow_commit();
9a0df45a 380 }
381
0f4e72de
PS
382 /**
383 * Returns description of method result value
384 * @return external_description
385 */
0c96468c 386 public static function add_groupmembers_returns() {
0f4e72de 387 return null;
0c96468c 388 }
389
390
0f4e72de
PS
391 /**
392 * Returns description of method parameters
393 * @return external_function_parameters
394 */
0c96468c 395 public static function delete_groupmembers_parameters() {
4efa2483
PS
396 return new external_function_parameters(
397 array(
398 'members'=> new external_multiple_structure(
399 new external_single_structure(
400 array(
401 'groupid' => new external_value(PARAM_INT, 'group record id'),
402 'userid' => new external_value(PARAM_INT, 'user id'),
403 )
404 )
0f4e72de
PS
405 )
406 )
407 );
0c96468c 408 }
9a0df45a 409
410 /**
411 * Delete group members
b4c1a34e 412 * @param array $members of arrays with keys userid, groupid
9a0df45a 413 * @return void
414 */
b4c1a34e 415 public static function delete_groupmembers($members) {
2cb1ee78 416 global $CFG, $DB;
9a0df45a 417 require_once("$CFG->dirroot/group/lib.php");
418
443364ab 419 $params = self::validate_parameters(self::delete_groupmembers_parameters(), array('members'=>$members));
9a0df45a 420
d5a8d9aa
PS
421 $transaction = $DB->start_delegated_transaction();
422
0c96468c 423 foreach ($params['members'] as $member) {
d5a8d9aa
PS
424 // validate params
425 $groupid = $member['groupid'];
426 $userid = $member['userid'];
0c96468c 427
d5a8d9aa
PS
428 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
429 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 430
d5a8d9aa
PS
431 // now security checks
432 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
433 self::validate_context($context);
434 require_capability('moodle/course:managegroups', $context);
9a0df45a 435
d5a8d9aa 436 groups_remove_member($group, $user);
9a0df45a 437 }
d5a8d9aa
PS
438
439 $transaction->allow_commit();
9a0df45a 440 }
441
0f4e72de
PS
442 /**
443 * Returns description of method result value
444 * @return external_description
445 */
0c96468c 446 public static function delete_groupmembers_returns() {
0f4e72de 447 return null;
0c96468c 448 }
449
4ca6cfbf 450}