MDL-30997 - group - trailing whitespace + comment alignment fixes
[moodle.git] / group / externallib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * External groups API
19  *
20  * @package    core_group
21  * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 require_once("$CFG->libdir/externallib.php");
27 /**
28  * Group functions
29  *
30  * @package    core_group
31  * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
32  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
33  */
34 class core_group_external extends external_api {
36     /**
37      * Returns description of method parameters
38      * @return external_function_parameters
39      */
40     public static function create_groups_parameters() {
41         return new external_function_parameters(
42             array(
43                 'groups' => new external_multiple_structure(
44                     new external_single_structure(
45                         array(
46                             'courseid' => new external_value(PARAM_INT, 'id of course'),
47                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
48                             'description' => new external_value(PARAM_RAW, 'group description text'),
49                             'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
50                         )
51                     ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
52                 )
53             )
54         );
55     }
57     /**
58      * Create groups
59      * @param array $groups array of group description arrays (with keys groupname and courseid)
60      * @return array of newly created groups
61      */
62     public static function create_groups($groups) {
63         global $CFG, $DB;
64         require_once("$CFG->dirroot/group/lib.php");
66         $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
68         $transaction = $DB->start_delegated_transaction();
70         $groups = array();
72         foreach ($params['groups'] as $group) {
73             $group = (object)$group;
75             if (trim($group->name) == '') {
76                 throw new invalid_parameter_exception('Invalid group name');
77             }
78             if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
79                 throw new invalid_parameter_exception('Group with the same name already exists in the course');
80             }
82             // now security checks
83             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
84             try {
85                 self::validate_context($context);
86             } catch (Exception $e) {
87                 $exceptionparam = new stdClass();
88                 $exceptionparam->message = $e->getMessage();
89                 $exceptionparam->courseid = $group->courseid;
90                 throw new moodle_exception(
91                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
92             }
93             require_capability('moodle/course:managegroups', $context);
95             // finally create the group
96             $group->id = groups_create_group($group, false);
97             $groups[] = (array)$group;
98         }
100         $transaction->allow_commit();
102         return $groups;
103     }
105     /**
106      * Returns description of method result value
107      * @return external_multiple_structure
108      */
109     public static function create_groups_returns() {
110         return new external_multiple_structure(
111             new external_single_structure(
112                 array(
113                     'id' => new external_value(PARAM_INT, 'group record id'),
114                     'courseid' => new external_value(PARAM_INT, 'id of course'),
115                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
116                     'description' => new external_value(PARAM_RAW, 'group description text'),
117                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
118                 )
119             ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
120         );
121     }
123     /**
124      * Returns description of method parameters
125      * @return external_function_parameters
126      */
127     public static function get_groups_parameters() {
128         return new external_function_parameters(
129             array(
130                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
131                         ,'List of group id. A group id is an integer.'),
132             )
133         );
134     }
136     /**
137      * Get groups definition specified by ids
138      * @param array $groupids arrays of group ids
139      * @return array of group objects (id, courseid, name, enrolmentkey)
140      */
141     public static function get_groups($groupids) {
142         $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
144         $groups = array();
145         foreach ($params['groupids'] as $groupid) {
146             // validate params
147             $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
149             // now security checks
150             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
151             try {
152                 self::validate_context($context);
153             } catch (Exception $e) {
154                 $exceptionparam = new stdClass();
155                 $exceptionparam->message = $e->getMessage();
156                 $exceptionparam->courseid = $group->courseid;
157                 throw new moodle_exception(
158                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
159             }
160             require_capability('moodle/course:managegroups', $context);
162             $groups[] = (array)$group;
163         }
165         return $groups;
166     }
168     /**
169      * Returns description of method result value
170      * @return external_multiple_structure
171      */
172     public static function get_groups_returns() {
173         return new external_multiple_structure(
174             new external_single_structure(
175                 array(
176                     'id' => new external_value(PARAM_INT, 'group record id'),
177                     'courseid' => new external_value(PARAM_INT, 'id of course'),
178                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
179                     'description' => new external_value(PARAM_RAW, 'group description text'),
180                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
181                 )
182             )
183         );
184     }
186     /**
187      * Returns description of method parameters
188      * @return external_function_parameters
189      */
190     public static function get_course_groups_parameters() {
191         return new external_function_parameters(
192             array(
193                 'courseid' => new external_value(PARAM_INT, 'id of course'),
194             )
195         );
196     }
198     /**
199      * Get all groups in the specified course
200      * @param int $courseid id of course
201      * @return array of group objects (id, courseid, name, enrolmentkey)
202      */
203     public static function get_course_groups($courseid) {
204         $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
206         // now security checks
207         $context = get_context_instance(CONTEXT_COURSE, $params['courseid']);
208         try {
209             self::validate_context($context);
210         } catch (Exception $e) {
211                 $exceptionparam = new stdClass();
212                 $exceptionparam->message = $e->getMessage();
213                 $exceptionparam->courseid = $params['courseid'];
214                 throw new moodle_exception(
215                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
216         }
217         require_capability('moodle/course:managegroups', $context);
219         $gs = groups_get_all_groups($params['courseid'], 0, 0, 'g.id, g.courseid, g.name, g.description, g.enrolmentkey');
221         $groups = array();
222         foreach ($gs as $group) {
223             $groups[] = (array)$group;
224         }
226         return $groups;
227     }
229     /**
230      * Returns description of method result value
231      * @return external_multiple_structure
232      */
233     public static function get_course_groups_returns() {
234         return new external_multiple_structure(
235             new external_single_structure(
236                 array(
237                     'id' => new external_value(PARAM_INT, 'group record id'),
238                     'courseid' => new external_value(PARAM_INT, 'id of course'),
239                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
240                     'description' => new external_value(PARAM_RAW, 'group description text'),
241                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
242                 )
243             )
244         );
245     }
247     /**
248      * Returns description of method parameters
249      * @return external_function_parameters
250      */
251     public static function delete_groups_parameters() {
252         return new external_function_parameters(
253             array(
254                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
255             )
256         );
257     }
259     /**
260      * Delete groups
261      * @param array $groupids array of group ids
262      * @return void
263      */
264     public static function delete_groups($groupids) {
265         global $CFG, $DB;
266         require_once("$CFG->dirroot/group/lib.php");
268         $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
270         $transaction = $DB->start_delegated_transaction();
272         foreach ($params['groupids'] as $groupid) {
273             // validate params
274             $groupid = validate_param($groupid, PARAM_INTEGER);
275             if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
276                 // silently ignore attempts to delete nonexisting groups
277                 continue;
278             }
280             // now security checks
281             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
282             try {
283                 self::validate_context($context);
284             } catch (Exception $e) {
285                 $exceptionparam = new stdClass();
286                 $exceptionparam->message = $e->getMessage();
287                 $exceptionparam->courseid = $group->courseid;
288                 throw new moodle_exception(
289                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
290             }
291             require_capability('moodle/course:managegroups', $context);
293             groups_delete_group($group);
294         }
296         $transaction->allow_commit();
297     }
299     /**
300      * Returns description of method result value
301      * @return external_description
302      */
303     public static function delete_groups_returns() {
304         return null;
305     }
308     /**
309      * Returns description of method parameters
310      * @return external_function_parameters
311      */
312     public static function get_group_members_parameters() {
313         return new external_function_parameters(
314             array(
315                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
316             )
317         );
318     }
320     /**
321      * Return all members for a group
322      * @param array $groupids array of group ids
323      * @return array with  group id keys containing arrays of user ids
324      */
325     public static function get_group_members($groupids) {
326         $members = array();
328         $params = self::validate_parameters(self::get_group_members_parameters(), array('groupids'=>$groupids));
330         foreach ($params['groupids'] as $groupid) {
331             // validate params
332             $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
333             // now security checks
334             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
335             try {
336                 self::validate_context($context);
337             } catch (Exception $e) {
338                 $exceptionparam = new stdClass();
339                 $exceptionparam->message = $e->getMessage();
340                 $exceptionparam->courseid = $group->courseid;
341                 throw new moodle_exception(
342                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
343             }
344             require_capability('moodle/course:managegroups', $context);
346             $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
348             $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
349         }
351         return $members;
352     }
354     /**
355      * Returns description of method result value
356      * @return external_description
357      */
358     public static function get_group_members_returns() {
359         return new external_multiple_structure(
360             new external_single_structure(
361                 array(
362                     'groupid' => new external_value(PARAM_INT, 'group record id'),
363                     'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
364                 )
365             )
366         );
367     }
370     /**
371      * Returns description of method parameters
372      * @return external_function_parameters
373      */
374     public static function add_group_members_parameters() {
375         return new external_function_parameters(
376             array(
377                 'members'=> new external_multiple_structure(
378                     new external_single_structure(
379                         array(
380                             'groupid' => new external_value(PARAM_INT, 'group record id'),
381                             'userid' => new external_value(PARAM_INT, 'user id'),
382                         )
383                     )
384                 )
385             )
386         );
387     }
389     /**
390      * Add group members
391      * @param array $members of arrays with keys userid, groupid
392      */
393     public static function add_group_members($members) {
394         global $CFG, $DB;
395         require_once("$CFG->dirroot/group/lib.php");
397         $params = self::validate_parameters(self::add_group_members_parameters(), array('members'=>$members));
399         $transaction = $DB->start_delegated_transaction();
400         foreach ($params['members'] as $member) {
401             // validate params
402             $groupid = $member['groupid'];
403             $userid = $member['userid'];
405             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
406             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
408             // now security checks
409             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
410             try {
411                 self::validate_context($context);
412             } catch (Exception $e) {
413                 $exceptionparam = new stdClass();
414                 $exceptionparam->message = $e->getMessage();
415                 $exceptionparam->courseid = $group->courseid;
416                 throw new moodle_exception(
417                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
418             }
419             require_capability('moodle/course:managegroups', $context);
421             // now make sure user is enrolled in course - this is mandatory requirement,
422             // unfortunately this is slow
423             if (!is_enrolled($context, $userid)) {
424                 throw new invalid_parameter_exception('Only enrolled users may be members of groups');
425             }
427             groups_add_member($group, $user);
428         }
430         $transaction->allow_commit();
431     }
433     /**
434      * Returns description of method result value
435      * @return null
436      */
437     public static function add_group_members_returns() {
438         return null;
439     }
442     /**
443      * Returns description of method parameters
444      * @return external_function_parameters
445      */
446     public static function delete_group_members_parameters() {
447         return new external_function_parameters(
448             array(
449                 'members'=> new external_multiple_structure(
450                     new external_single_structure(
451                         array(
452                             'groupid' => new external_value(PARAM_INT, 'group record id'),
453                             'userid' => new external_value(PARAM_INT, 'user id'),
454                         )
455                     )
456                 )
457             )
458         );
459     }
461     /**
462      * Delete group members
463      * @param array $members of arrays with keys userid, groupid
464      */
465     public static function delete_group_members($members) {
466         global $CFG, $DB;
467         require_once("$CFG->dirroot/group/lib.php");
469         $params = self::validate_parameters(self::delete_group_members_parameters(), array('members'=>$members));
471         $transaction = $DB->start_delegated_transaction();
473         foreach ($params['members'] as $member) {
474             // validate params
475             $groupid = $member['groupid'];
476             $userid = $member['userid'];
478             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
479             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
481             // now security checks
482             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
483             try {
484                 self::validate_context($context);
485             } catch (Exception $e) {
486                 $exceptionparam = new stdClass();
487                 $exceptionparam->message = $e->getMessage();
488                 $exceptionparam->courseid = $group->courseid;
489                 throw new moodle_exception(
490                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
491             }
492             require_capability('moodle/course:managegroups', $context);
494             groups_remove_member($group, $user);
495         }
497         $transaction->allow_commit();
498     }
500     /**
501      * Returns description of method result value
502      * @return null
503      */
504     public static function delete_group_members_returns() {
505         return null;
506     }
510 /**
511  * Deprecated group functions
512  * @deprecated since Moodle 2.2 please do not call this class any more.
513  * @see core_group_external()
514  */
515 class moodle_group_external extends external_api {
517     /**
518      * Returns description of method parameters
519      * @deprecated since Moodle 2.2 please do not call this function any more.
520      * @see core_group_external::create_groups_parameters()
521      * @return external_function_parameters
522      */
523     public static function create_groups_parameters() {
524         return core_group_external::create_groups_parameters();
525     }
527     /**
528      * Create groups
529      * @deprecated since Moodle 2.2 please do not call this function any more.
530      * @see core_group_external::create_groups()
531      * @param array $groups array of group description arrays (with keys groupname and courseid)
532      * @return array of newly created groups
533      */
534     public static function create_groups($groups) {
535         return core_group_external::create_groups($groups);
536     }
538     /**
539      * Returns description of method result value
540      * @deprecated since Moodle 2.2 please do not call this function any more.
541      * @see core_group_external::create_groups_returns()
542      * @return external_description
543      */
544     public static function create_groups_returns() {
545         return core_group_external::create_groups_returns();
546     }
548     /**
549      * Returns description of method parameters
550      * @deprecated since Moodle 2.2 please do not call this function any more.
551      * @see core_group_external::get_groups_parameters()
552      * @return external_function_parameters
553      */
554     public static function get_groups_parameters() {
555         return core_group_external::get_groups_parameters();
556     }
558     /**
559      * Get groups definition specified by ids
560      * @deprecated since Moodle 2.2 please do not call this function any more.
561      * @see core_group_external::get_groups()
562      * @param array $groupids arrays of group ids
563      * @return array of group objects (id, courseid, name, enrolmentkey)
564      */
565     public static function get_groups($groupids) {
566         return core_group_external::get_groups($groupids);
567     }
569     /**
570      * Returns description of method result value
571      * @deprecated since Moodle 2.2 please do not call this function any more.
572      * @see core_group_external::get_groups_returns()
573      * @return external_description
574      */
575     public static function get_groups_returns() {
576         return core_group_external::get_groups_returns();
577     }
579     /**
580      * Returns description of method parameters
581      * @deprecated since Moodle 2.2 please do not call this function any more.
582      * @see core_group_external::get_course_groups_parameters()
583      * @return external_function_parameters
584      */
585     public static function get_course_groups_parameters() {
586         return core_group_external::get_course_groups_parameters();
587     }
589     /**
590      * Get all groups in the specified course
591      * @deprecated since Moodle 2.2 please do not call this function any more.
592      * @see core_group_external::get_course_groups()
593      * @param int $courseid id of course
594      * @return array of group objects (id, courseid, name, enrolmentkey)
595      */
596     public static function get_course_groups($courseid) {
597         return core_group_external::get_course_groups($courseid);
598     }
600     /**
601      * Returns description of method result value
602      * @deprecated since Moodle 2.2 please do not call this function any more.
603      * @see core_group_external::get_course_groups_returns()
604      * @return external_description
605      */
606     public static function get_course_groups_returns() {
607         return core_group_external::get_course_groups_returns();
608     }
610     /**
611      * Returns description of method parameters
612      * @deprecated since Moodle 2.2 please do not call this function any more.
613      * @see core_group_external::delete_group_members_parameters()
614      * @return external_function_parameters
615      */
616     public static function delete_groups_parameters() {
617         return core_group_external::delete_group_members_parameters();
618     }
620     /**
621      * Delete groups
622      * @deprecated since Moodle 2.2 please do not call this function any more.
623      * @see core_group_external::delete_groups()
624      * @param array $groupids array of group ids
625      * @return void
626      */
627     public static function delete_groups($groupids) {
628         return core_group_external::delete_groups($groupids);
629     }
631     /**
632      * Returns description of method result value
633      * @deprecated since Moodle 2.2 please do not call this function any more.
634      * @see core_group_external::delete_group_members_returns()
635      * @return external_description
636      */
637     public static function delete_groups_returns() {
638         return core_group_external::delete_group_members_returns();
639     }
642     /**
643      * Returns description of method parameters
644      * @deprecated since Moodle 2.2 please do not call this function any more.
645      * @see core_group_external::get_group_members_parameters()
646      * @return external_function_parameters
647      */
648     public static function get_groupmembers_parameters() {
649         return core_group_external::get_group_members_parameters();
650     }
652     /**
653      * Return all members for a group
654      * @deprecated since Moodle 2.2 please do not call this function any more.
655      * @see core_group_external::get_group_members()
656      * @param array $groupids array of group ids
657      * @return array with  group id keys containing arrays of user ids
658      */
659     public static function get_groupmembers($groupids) {
660         return core_group_external::get_group_members($groupids);
661     }
663     /**
664      * Returns description of method result value
665      * @deprecated since Moodle 2.2 please do not call this function any more.
666      * @see core_group_external::get_group_members_returns()
667      * @return external_description
668      */
669     public static function get_groupmembers_returns() {
670         return core_group_external::get_group_members_returns();
671     }
674     /**
675      * Returns description of method parameters
676      * @deprecated since Moodle 2.2 please do not call this function any more.
677      * @see core_group_external::add_group_members_parameters()
678      * @return external_function_parameters
679      */
680     public static function add_groupmembers_parameters() {
681         return core_group_external::add_group_members_parameters();
682     }
684     /**
685      * Add group members
686      * @deprecated since Moodle 2.2 please do not call this function any more.
687      * @see core_group_external::add_group_members()
688      * @param array $members of arrays with keys userid, groupid
689      * @return void
690      */
691     public static function add_groupmembers($members) {
692         return core_group_external::add_group_members($members);
693     }
695     /**
696      * Returns description of method result value
697      * @deprecated since Moodle 2.2 please do not call this function any more.
698      * @see core_group_external::add_group_members_returns()
699      * @return external_description
700      */
701     public static function add_groupmembers_returns() {
702         return core_group_external::add_group_members_returns();
703     }
706     /**
707      * Returns description of method parameters
708      * @deprecated since Moodle 2.2 please do not call this function any more.
709      * @see core_group_external::delete_group_members_parameters()
710      * @return external_function_parameters
711      */
712     public static function delete_groupmembers_parameters() {
713         return core_group_external::delete_group_members_parameters();
714     }
716     /**
717      * Delete group members
718      * @deprecated since Moodle 2.2 please do not call this function any more.
719      * @see core_group_external::delete_group_members()
720      * @param array $members of arrays with keys userid, groupid
721      * @return void
722      */
723     public static function delete_groupmembers($members) {
724         return core_group_external::delete_group_members($members);
725     }
727     /**
728      * Returns description of method result value
729      * @deprecated since Moodle 2.2 please do not call this function any more.
730      * @see core_group_external::delete_group_members_returns()
731      * @return external_description
732      */
733     public static function delete_groupmembers_returns() {
734         return core_group_external::delete_group_members_returns();
735     }