MDL-12886 api improvments - the actuall validation implementation is missing - we...
[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
23 * @copyright 2009 Petr Skoda (http://skodak.org)
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
31 /**
32 * Create groups
33 * @param array $params array of group description arrays (with keys groupname and courseid)
34 * @return array of newly created group ids
35 */
36 public static function create_groups($params) {
37 global $CFG;
38 require_once("$CFG->dirroot/group/lib.php");
39
40 $groupids = array();
41
42 foreach ($params as $groupparam) {
43 $group = new object();
ab9a01f2 44
45 // validate params
46 $group->courseid = validate_param($groupparam['courseid'], PARAM_INTEGER);
47 $group->name = validate_param($groupparam['groupname'], PARAM_MULTILANG); // must be course unique!
48 $group->description = validate_param($groupparam['description'], PARAM_RAW);
9a0df45a 49 if (array_key_exists('enrolmentkey', $groupparam)) {
ab9a01f2 50 $group->enrolmentkey = validate_param($groupparam['enrolmentkey'], PARAM_RAW);
9a0df45a 51 } else {
52 $group->enrolmentkey = '';
53 }
ab9a01f2 54 if (empty($group->name)) {
55 throw new invalid_parameter_exception('Invalid group name');
56 }
57 if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
58 throw new invalid_parameter_exception('Group with the same name already exists in the course');
59 }
60
9a0df45a 61 // now security checks
62 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
63 self::validate_context($context);
64 require_capability('moodle/course:managegroups', $context);
65
66 $id = groups_create_group($group, false);
67 $group->id = $id;
68 $groupids[$id] = $group;
69 }
70
71 return $groupids;
72 }
73
74 /**
75 * Get groups definition
76 * @param array $params arrays of group ids
77 * @return array of group objects (id, courseid, name, enrolmentkey)
78 */
79 public static function get_groups($params) {
80 $groups = array();
81
82 //TODO: we do need to search for groups in courses too,
83 // fetching by id is not enough!
84
85 foreach ($params as $groupid) {
ab9a01f2 86 // validate params
87 $groupid = validate_param($groupid, PARAM_INTEGER);
88 $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
89
9a0df45a 90 // now security checks
91 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
92 self::validate_context($context);
93 require_capability('moodle/course:managegroups', $context);
94
95 $groups[$group->id] = $group;
96 }
97
98 return $groups;
99 }
100
101 /**
102 * Delete groups
103 * @param array $params array of group ids
104 * @return void
105 */
106 public static function delete_groups($params) {
107 global $CFG;
108 require_once("$CFG->dirroot/group/lib.php");
109
110 $groups = array();
111
112 foreach ($params as $groupid) {
ab9a01f2 113 // validate params
114 $groupid = validate_param($groupid, PARAM_INTEGER);
9a0df45a 115 if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
116 // silently ignore attempts to delete nonexisting groups
117 continue;
118 }
ab9a01f2 119
9a0df45a 120 // now security checks
121 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
122 self::validate_context($context);
123 require_capability('moodle/course:managegroups', $context);
124
125 groups_delete_group($group);
126 }
127 }
128
129
130 /**
131 * Return all members for a group
132 * @param array $params array of group ids
133 * @return array with group id keys containing arrays of user ids
134 */
135 public static function get_groupmembers($params) {
136 $groups = array();
137
138 foreach ($params as $groupid) {
ab9a01f2 139 // validate params
140 $groupid = validate_param($groupid, PARAM_INTEGER);
9a0df45a 141 $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
142 // now security checks
143 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
144 self::validate_context($context);
145 require_capability('moodle/course:managegroups', $context);
146
147 $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
148
149 $groups[$group->id] = array_keys($groupmembers);
150 }
151
152 return $groups;
153 }
154
155
156 /**
157 * Add group members
158 * @param array of arrays with keys userid, groupid
159 * @return void
160 */
161 public static function add_groupmembers($params) {
162 global $CFG;
163 require_once("$CFG->dirroot/group/lib.php");
164
165 $groups = array();
166
167 foreach ($params as $member) {
ab9a01f2 168 // validate params
169 $groupid = validate_param($member['groupid'], PARAM_INTEGER);
170 $userid = validate_param($member['userid'], PARAM_INTEGER);
9a0df45a 171 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
ab9a01f2 172 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 173
174 // now security checks
175 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
176 self::validate_context($context);
177 require_capability('moodle/course:managegroups', $context);
178 require_capability('moodle/course:view', $context, $user->id, false); // only enrolled users may be members of group!!!
179
180 groups_add_member($group, $user);
181 }
182 }
183
184
185 /**
186 * Delete group members
187 * @param array of arrays with keys userid, groupid
188 * @return void
189 */
190 public static function delete_groupmembers($params){
191 global $CFG;
192 require_once("$CFG->dirroot/group/lib.php");
193
194 $groups = array();
195
196 foreach ($params as $member) {
ab9a01f2 197 // validate params
198 $groupid = validate_param($member['groupid'], PARAM_INTEGER);
199 $userid = validate_param($member['userid'], PARAM_INTEGER);
200 $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
201 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
9a0df45a 202
203 // now security checks
204 $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
205 self::validate_context($context);
206 require_capability('moodle/course:managegroups', $context);
207
208 groups_remove_member($group, $user);
209 }
210 }
211
212}