MDL-20620 ims-cc import - load resources in object, so navigation doesn't get lost...
[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
33 * @return ?
34 */
35 public static function create_groups_parameters() {
36 //TODO
37 }
38
39 /**
9a0df45a 40 * Create groups
b4c1a34e 41 * @param array $groups array of group description arrays (with keys groupname and courseid)
9a0df45a 42 * @return array of newly created group ids
43 */
b4c1a34e 44 public static function create_groups($groups) {
9a0df45a 45 global $CFG;
46 require_once("$CFG->dirroot/group/lib.php");
47
c9c5cc81 48 $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
0c96468c 49
2e13b916 50 $groups = array();
9a0df45a 51
b4c1a34e 52 foreach ($params['groups'] as $group) {
0c96468c 53 $group = (object)$group;
ab9a01f2 54
f94f09b5 55 if (trim($group->name) == '') {
ab9a01f2 56 throw new invalid_parameter_exception('Invalid group name');
57 }
58 if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
59 throw new invalid_parameter_exception('Group with the same name already exists in the course');
60 }
0c96468c 61
9a0df45a 62 // now security checks
63 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
64 self::validate_context($context);
65 require_capability('moodle/course:managegroups', $context);
66
2e13b916 67 $group->id = groups_create_group($group, false);
68 $groups[] = (array)$group;
9a0df45a 69 }
70
2e13b916 71 return $groups;
9a0df45a 72 }
73
0c96468c 74 /**
75 * Returns description of method result value
76 * @return ?
77 */
78 public static function create_groups_returns() {
79 //TODO
80 }
81
82 public static function get_groups_parameters() {
8c772ad7 83 return new external_function_parameters(
84 array(
04d212ce 85 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID'))
8c772ad7 86 )
87 );
0c96468c 88 }
89
9a0df45a 90 /**
91 * Get groups definition
b4c1a34e 92 * @param array $groupids arrays of group ids
9a0df45a 93 * @return array of group objects (id, courseid, name, enrolmentkey)
94 */
b4c1a34e 95 public static function get_groups($groupids) {
9a0df45a 96 $groups = array();
97
c9c5cc81 98 $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
0c96468c 99
9a0df45a 100 //TODO: we do need to search for groups in courses too,
101 // fetching by id is not enough!
102
0c96468c 103 foreach ($params['groupids'] as $groupid) {
ab9a01f2 104 // validate params
ab9a01f2 105 $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
106
9a0df45a 107 // now security checks
108 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
109 self::validate_context($context);
110 require_capability('moodle/course:managegroups', $context);
111
2e13b916 112 $groups[] = (array)$group;
9a0df45a 113 }
114
115 return $groups;
116 }
117
0c96468c 118 public static function get_groups_returns() {
8c772ad7 119 return new external_multiple_structure(
120 new external_single_structure(
121 array(
04d212ce 122 'id' => new external_value(PARAM_INT, 'some group id'),
123 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
124 'description' => new external_value(PARAM_RAW, 'just some text'),
125 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase')
8c772ad7 126 )
127 )
128 );
0c96468c 129 }
130
131 public static function delete_groups_parameters() {
132 //TODO
133 }
134
9a0df45a 135 /**
136 * Delete groups
b4c1a34e 137 * @param array $groupids array of group ids
9a0df45a 138 * @return void
139 */
b4c1a34e 140 public static function delete_groups($groupids) {
9a0df45a 141 global $CFG;
142 require_once("$CFG->dirroot/group/lib.php");
143
c9c5cc81 144 $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
0c96468c 145
9a0df45a 146 $groups = array();
147
0c96468c 148 foreach ($params['groupids'] as $groupid) {
ab9a01f2 149 // validate params
150 $groupid = validate_param($groupid, PARAM_INTEGER);
9a0df45a 151 if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
152 // silently ignore attempts to delete nonexisting groups
153 continue;
154 }
ab9a01f2 155
9a0df45a 156 // now security checks
157 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
158 self::validate_context($context);
159 require_capability('moodle/course:managegroups', $context);
160
161 groups_delete_group($group);
162 }
163 }
164
0c96468c 165 public static function delete_groups_returns() {
166 //TODO
167 }
168
169
170 public static function get_groupmembers_parameters() {
171 //TODO
172 }
9a0df45a 173
174 /**
175 * Return all members for a group
b4c1a34e 176 * @param array $groupids array of group ids
9a0df45a 177 * @return array with group id keys containing arrays of user ids
178 */
b4c1a34e 179 public static function get_groupmembers($groupids) {
9a0df45a 180 $groups = array();
181
c9c5cc81 182 $params = self::validate_parameters(self::get_groupmembers_parameters(), array('groupids'=>$groupids));
0c96468c 183
184 foreach ($params['groupids'] as $groupid) {
ab9a01f2 185 // validate params
9a0df45a 186 $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
187 // now security checks
188 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
189 self::validate_context($context);
190 require_capability('moodle/course:managegroups', $context);
191
192 $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
193
194 $groups[$group->id] = array_keys($groupmembers);
195 }
196
197 return $groups;
198 }
199
0c96468c 200 public static function get_groupmembers_returns() {
201 //TODO
202 }
203
204
205 public static function add_groupmembers_parameters() {
206 //TODO
207 }
9a0df45a 208
209 /**
210 * Add group members
b4c1a34e 211 * @param array $members of arrays with keys userid, groupid
9a0df45a 212 * @return void
213 */
b4c1a34e 214 public static function add_groupmembers($members) {
9a0df45a 215 global $CFG;
216 require_once("$CFG->dirroot/group/lib.php");
217
c9c5cc81 218 $params = self::validate_parameters(self::add_groupmembers_parameters(), array('members'=>$members));
9a0df45a 219
b4c1a34e 220 foreach ($params['members'] as $member) {
ab9a01f2 221 // validate params
0c96468c 222 $groupid = $member['groupid'];
223 $userid = $member['userid'];
224
9a0df45a 225 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
ab9a01f2 226 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 227
228 // now security checks
229 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
230 self::validate_context($context);
231 require_capability('moodle/course:managegroups', $context);
232 require_capability('moodle/course:view', $context, $user->id, false); // only enrolled users may be members of group!!!
233
234 groups_add_member($group, $user);
235 }
236 }
237
0c96468c 238 public static function add_groupmembers_returns() {
239 //TODO
240 }
241
242
243 public static function delete_groupmembers_parameters() {
244 //TODO
245 }
9a0df45a 246
247 /**
248 * Delete group members
b4c1a34e 249 * @param array $members of arrays with keys userid, groupid
9a0df45a 250 * @return void
251 */
b4c1a34e 252 public static function delete_groupmembers($members) {
9a0df45a 253 global $CFG;
254 require_once("$CFG->dirroot/group/lib.php");
255
c9c5cc81 256 $params = self::validate_parameters(self::delete_groupmembers_parameters(), array($members=>'members'));
9a0df45a 257
0c96468c 258 foreach ($params['members'] as $member) {
ab9a01f2 259 // validate params
0c96468c 260 $groupid = $member['groupid'];
261 $userid = $member['userid'];
262
ab9a01f2 263 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
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
271 groups_remove_member($group, $user);
272 }
273 }
274
0c96468c 275 public static function delete_groupmembers_returns() {
276 //TODO
277 }
278
9a0df45a 279}