MDL-36855 scorm: update to api get_scorm_question_count()
[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/>.
18 /**
19  * External groups API
20  *
21  * @package    core_group
22  * @category   external
23  * @copyright  2009 Petr Skodak
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 require_once("$CFG->libdir/externallib.php");
29 /**
30  * Group external functions
31  *
32  * @package    core_group
33  * @category   external
34  * @copyright  2011 Jerome Mouneyrac
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  * @since Moodle 2.2
37  */
38 class core_group_external extends external_api {
40     /**
41      * Returns description of method parameters
42      *
43      * @return external_function_parameters
44      * @since Moodle 2.2
45      */
46     public static function create_groups_parameters() {
47         return new external_function_parameters(
48             array(
49                 'groups' => new external_multiple_structure(
50                     new external_single_structure(
51                         array(
52                             'courseid' => new external_value(PARAM_INT, 'id of course'),
53                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
54                             'description' => new external_value(PARAM_RAW, 'group description text'),
55                             'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
56                             'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase', VALUE_OPTIONAL),
57                         )
58                     ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
59                 )
60             )
61         );
62     }
64     /**
65      * Create groups
66      *
67      * @param array $groups array of group description arrays (with keys groupname and courseid)
68      * @return array of newly created groups
69      * @since Moodle 2.2
70      */
71     public static function create_groups($groups) {
72         global $CFG, $DB;
73         require_once("$CFG->dirroot/group/lib.php");
75         $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
77         $transaction = $DB->start_delegated_transaction();
79         $groups = array();
81         foreach ($params['groups'] as $group) {
82             $group = (object)$group;
84             if (trim($group->name) == '') {
85                 throw new invalid_parameter_exception('Invalid group name');
86             }
87             if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
88                 throw new invalid_parameter_exception('Group with the same name already exists in the course');
89             }
91             // now security checks
92             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
93             try {
94                 self::validate_context($context);
95             } catch (Exception $e) {
96                 $exceptionparam = new stdClass();
97                 $exceptionparam->message = $e->getMessage();
98                 $exceptionparam->courseid = $group->courseid;
99                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
100             }
101             require_capability('moodle/course:managegroups', $context);
103             // Validate format.
104             $group->descriptionformat = external_validate_format($group->descriptionformat);
106             // finally create the group
107             $group->id = groups_create_group($group, false);
108             if (!isset($group->enrolmentkey)) {
109                 $group->enrolmentkey = '';
110             }
111             $groups[] = (array)$group;
112         }
114         $transaction->allow_commit();
116         return $groups;
117     }
119     /**
120      * Returns description of method result value
121      *
122      * @return external_description
123      * @since Moodle 2.2
124      */
125     public static function create_groups_returns() {
126         return new external_multiple_structure(
127             new external_single_structure(
128                 array(
129                     'id' => new external_value(PARAM_INT, 'group record id'),
130                     'courseid' => new external_value(PARAM_INT, 'id of course'),
131                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
132                     'description' => new external_value(PARAM_RAW, 'group description text'),
133                     'descriptionformat' => new external_format_value('description'),
134                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
135                 )
136             ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
137         );
138     }
140     /**
141      * Returns description of method parameters
142      *
143      * @return external_function_parameters
144      * @since Moodle 2.2
145      */
146     public static function get_groups_parameters() {
147         return new external_function_parameters(
148             array(
149                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
150                         ,'List of group id. A group id is an integer.'),
151             )
152         );
153     }
155     /**
156      * Get groups definition specified by ids
157      *
158      * @param array $groupids arrays of group ids
159      * @return array of group objects (id, courseid, name, enrolmentkey)
160      * @since Moodle 2.2
161      */
162     public static function get_groups($groupids) {
163         $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
165         $groups = array();
166         foreach ($params['groupids'] as $groupid) {
167             // validate params
168             $group = groups_get_group($groupid, 'id, courseid, name, description, descriptionformat, enrolmentkey', MUST_EXIST);
170             // now security checks
171             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
172             try {
173                 self::validate_context($context);
174             } catch (Exception $e) {
175                 $exceptionparam = new stdClass();
176                 $exceptionparam->message = $e->getMessage();
177                 $exceptionparam->courseid = $group->courseid;
178                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
179             }
180             require_capability('moodle/course:managegroups', $context);
182             list($group->description, $group->descriptionformat) =
183                 external_format_text($group->description, $group->descriptionformat,
184                         $context->id, 'group', 'description', $group->id);
186             $groups[] = (array)$group;
187         }
189         return $groups;
190     }
192     /**
193      * Returns description of method result value
194      *
195      * @return external_description
196      * @since Moodle 2.2
197      */
198     public static function get_groups_returns() {
199         return new external_multiple_structure(
200             new external_single_structure(
201                 array(
202                     'id' => new external_value(PARAM_INT, 'group record id'),
203                     'courseid' => new external_value(PARAM_INT, 'id of course'),
204                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
205                     'description' => new external_value(PARAM_RAW, 'group description text'),
206                     'descriptionformat' => new external_format_value('description'),
207                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
208                 )
209             )
210         );
211     }
213     /**
214      * Returns description of method parameters
215      *
216      * @return external_function_parameters
217      * @since Moodle 2.2
218      */
219     public static function get_course_groups_parameters() {
220         return new external_function_parameters(
221             array(
222                 'courseid' => new external_value(PARAM_INT, 'id of course'),
223             )
224         );
225     }
227     /**
228      * Get all groups in the specified course
229      *
230      * @param int $courseid id of course
231      * @return array of group objects (id, courseid, name, enrolmentkey)
232      * @since Moodle 2.2
233      */
234     public static function get_course_groups($courseid) {
235         $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
237         // now security checks
238         $context = get_context_instance(CONTEXT_COURSE, $params['courseid']);
239         try {
240             self::validate_context($context);
241         } catch (Exception $e) {
242                 $exceptionparam = new stdClass();
243                 $exceptionparam->message = $e->getMessage();
244                 $exceptionparam->courseid = $params['courseid'];
245                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
246         }
247         require_capability('moodle/course:managegroups', $context);
249         $gs = groups_get_all_groups($params['courseid'], 0, 0,
250             'g.id, g.courseid, g.name, g.description, g.descriptionformat, g.enrolmentkey');
252         $groups = array();
253         foreach ($gs as $group) {
254             list($group->description, $group->descriptionformat) =
255                 external_format_text($group->description, $group->descriptionformat,
256                         $context->id, 'group', 'description', $group->id);
257             $groups[] = (array)$group;
258         }
260         return $groups;
261     }
263     /**
264      * Returns description of method result value
265      *
266      * @return external_description
267      * @since Moodle 2.2
268      */
269     public static function get_course_groups_returns() {
270         return new external_multiple_structure(
271             new external_single_structure(
272                 array(
273                     'id' => new external_value(PARAM_INT, 'group record id'),
274                     'courseid' => new external_value(PARAM_INT, 'id of course'),
275                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
276                     'description' => new external_value(PARAM_RAW, 'group description text'),
277                     'descriptionformat' => new external_format_value('description'),
278                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
279                 )
280             )
281         );
282     }
284     /**
285      * Returns description of method parameters
286      *
287      * @return external_function_parameters
288      * @since Moodle 2.2
289      */
290     public static function delete_groups_parameters() {
291         return new external_function_parameters(
292             array(
293                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
294             )
295         );
296     }
298     /**
299      * Delete groups
300      *
301      * @param array $groupids array of group ids
302      * @since Moodle 2.2
303      */
304     public static function delete_groups($groupids) {
305         global $CFG, $DB;
306         require_once("$CFG->dirroot/group/lib.php");
308         $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
310         $transaction = $DB->start_delegated_transaction();
312         foreach ($params['groupids'] as $groupid) {
313             // validate params
314             $groupid = validate_param($groupid, PARAM_INTEGER);
315             if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
316                 // silently ignore attempts to delete nonexisting groups
317                 continue;
318             }
320             // now security checks
321             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
322             try {
323                 self::validate_context($context);
324             } catch (Exception $e) {
325                 $exceptionparam = new stdClass();
326                 $exceptionparam->message = $e->getMessage();
327                 $exceptionparam->courseid = $group->courseid;
328                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
329             }
330             require_capability('moodle/course:managegroups', $context);
332             groups_delete_group($group);
333         }
335         $transaction->allow_commit();
336     }
338     /**
339      * Returns description of method result value
340      *
341      * @return null
342      * @since Moodle 2.2
343      */
344     public static function delete_groups_returns() {
345         return null;
346     }
349     /**
350      * Returns description of method parameters
351      *
352      * @return external_function_parameters
353      * @since Moodle 2.2
354      */
355     public static function get_group_members_parameters() {
356         return new external_function_parameters(
357             array(
358                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
359             )
360         );
361     }
363     /**
364      * Return all members for a group
365      *
366      * @param array $groupids array of group ids
367      * @return array with  group id keys containing arrays of user ids
368      * @since Moodle 2.2
369      */
370     public static function get_group_members($groupids) {
371         $members = array();
373         $params = self::validate_parameters(self::get_group_members_parameters(), array('groupids'=>$groupids));
375         foreach ($params['groupids'] as $groupid) {
376             // validate params
377             $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
378             // now security checks
379             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
380             try {
381                 self::validate_context($context);
382             } catch (Exception $e) {
383                 $exceptionparam = new stdClass();
384                 $exceptionparam->message = $e->getMessage();
385                 $exceptionparam->courseid = $group->courseid;
386                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
387             }
388             require_capability('moodle/course:managegroups', $context);
390             $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
392             $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
393         }
395         return $members;
396     }
398     /**
399      * Returns description of method result value
400      *
401      * @return external_description
402      * @since Moodle 2.2
403      */
404     public static function get_group_members_returns() {
405         return new external_multiple_structure(
406             new external_single_structure(
407                 array(
408                     'groupid' => new external_value(PARAM_INT, 'group record id'),
409                     'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
410                 )
411             )
412         );
413     }
416     /**
417      * Returns description of method parameters
418      *
419      * @return external_function_parameters
420      * @since Moodle 2.2
421      */
422     public static function add_group_members_parameters() {
423         return new external_function_parameters(
424             array(
425                 'members'=> new external_multiple_structure(
426                     new external_single_structure(
427                         array(
428                             'groupid' => new external_value(PARAM_INT, 'group record id'),
429                             'userid' => new external_value(PARAM_INT, 'user id'),
430                         )
431                     )
432                 )
433             )
434         );
435     }
437     /**
438      * Add group members
439      *
440      * @param array $members of arrays with keys userid, groupid
441      * @since Moodle 2.2
442      */
443     public static function add_group_members($members) {
444         global $CFG, $DB;
445         require_once("$CFG->dirroot/group/lib.php");
447         $params = self::validate_parameters(self::add_group_members_parameters(), array('members'=>$members));
449         $transaction = $DB->start_delegated_transaction();
450         foreach ($params['members'] as $member) {
451             // validate params
452             $groupid = $member['groupid'];
453             $userid = $member['userid'];
455             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
456             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
458             // now security checks
459             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
460             try {
461                 self::validate_context($context);
462             } catch (Exception $e) {
463                 $exceptionparam = new stdClass();
464                 $exceptionparam->message = $e->getMessage();
465                 $exceptionparam->courseid = $group->courseid;
466                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
467             }
468             require_capability('moodle/course:managegroups', $context);
470             // now make sure user is enrolled in course - this is mandatory requirement,
471             // unfortunately this is slow
472             if (!is_enrolled($context, $userid)) {
473                 throw new invalid_parameter_exception('Only enrolled users may be members of groups');
474             }
476             groups_add_member($group, $user);
477         }
479         $transaction->allow_commit();
480     }
482     /**
483      * Returns description of method result value
484      *
485      * @return null
486      * @since Moodle 2.2
487      */
488     public static function add_group_members_returns() {
489         return null;
490     }
493     /**
494      * Returns description of method parameters
495      *
496      * @return external_function_parameters
497      * @since Moodle 2.2
498      */
499     public static function delete_group_members_parameters() {
500         return new external_function_parameters(
501             array(
502                 'members'=> new external_multiple_structure(
503                     new external_single_structure(
504                         array(
505                             'groupid' => new external_value(PARAM_INT, 'group record id'),
506                             'userid' => new external_value(PARAM_INT, 'user id'),
507                         )
508                     )
509                 )
510             )
511         );
512     }
514     /**
515      * Delete group members
516      *
517      * @param array $members of arrays with keys userid, groupid
518      * @since Moodle 2.2
519      */
520     public static function delete_group_members($members) {
521         global $CFG, $DB;
522         require_once("$CFG->dirroot/group/lib.php");
524         $params = self::validate_parameters(self::delete_group_members_parameters(), array('members'=>$members));
526         $transaction = $DB->start_delegated_transaction();
528         foreach ($params['members'] as $member) {
529             // validate params
530             $groupid = $member['groupid'];
531             $userid = $member['userid'];
533             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
534             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
536             // now security checks
537             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
538             try {
539                 self::validate_context($context);
540             } catch (Exception $e) {
541                 $exceptionparam = new stdClass();
542                 $exceptionparam->message = $e->getMessage();
543                 $exceptionparam->courseid = $group->courseid;
544                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
545             }
546             require_capability('moodle/course:managegroups', $context);
548             groups_remove_member($group, $user);
549         }
551         $transaction->allow_commit();
552     }
554     /**
555      * Returns description of method result value
556      *
557      * @return null
558      * @since Moodle 2.2
559      */
560     public static function delete_group_members_returns() {
561         return null;
562     }
564     /**
565      * Returns description of method parameters
566      *
567      * @return external_function_parameters
568      * @since Moodle 2.3
569      */
570     public static function create_groupings_parameters() {
571         return new external_function_parameters(
572             array(
573                 'groupings' => new external_multiple_structure(
574                     new external_single_structure(
575                         array(
576                             'courseid' => new external_value(PARAM_INT, 'id of course'),
577                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
578                             'description' => new external_value(PARAM_RAW, 'grouping description text'),
579                             'descriptionformat' => new external_format_value('descripiton', VALUE_DEFAULT)
580                         )
581                     ), 'List of grouping object. A grouping has a courseid, a name and a description.'
582                 )
583             )
584         );
585     }
587     /**
588      * Create groupings
589      *
590      * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
591      * @return array of newly created groupings
592      * @since Moodle 2.3
593      */
594     public static function create_groupings($groupings) {
595         global $CFG, $DB;
596         require_once("$CFG->dirroot/group/lib.php");
598         $params = self::validate_parameters(self::create_groupings_parameters(), array('groupings'=>$groupings));
600         $transaction = $DB->start_delegated_transaction();
602         $groupings = array();
604         foreach ($params['groupings'] as $grouping) {
605             $grouping = (object)$grouping;
607             if (trim($grouping->name) == '') {
608                 throw new invalid_parameter_exception('Invalid grouping name');
609             }
610             if ($DB->count_records('groupings', array('courseid'=>$grouping->courseid, 'name'=>$grouping->name))) {
611                 throw new invalid_parameter_exception('Grouping with the same name already exists in the course');
612             }
614             // Now security checks            .
615             $context = context_course::instance($grouping->courseid);
616             try {
617                 self::validate_context($context);
618             } catch (Exception $e) {
619                 $exceptionparam = new stdClass();
620                 $exceptionparam->message = $e->getMessage();
621                 $exceptionparam->courseid = $grouping->courseid;
622                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
623             }
624             require_capability('moodle/course:managegroups', $context);
626             $grouping->descriptionformat = external_validate_format($grouping->descriptionformat);
628             // Finally create the grouping.
629             $grouping->id = groups_create_grouping($grouping);
630             $groupings[] = (array)$grouping;
631         }
633         $transaction->allow_commit();
635         return $groupings;
636     }
638     /**
639      * Returns description of method result value
640      *
641      * @return external_description
642      * @since Moodle 2.3
643      */
644     public static function create_groupings_returns() {
645         return new external_multiple_structure(
646             new external_single_structure(
647                 array(
648                     'id' => new external_value(PARAM_INT, 'grouping record id'),
649                     'courseid' => new external_value(PARAM_INT, 'id of course'),
650                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
651                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
652                     'descriptionformat' => new external_format_value('description')
653                 )
654             ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
655         );
656     }
658     /**
659      * Returns description of method parameters
660      *
661      * @return external_function_parameters
662      * @since Moodle 2.3
663      */
664     public static function update_groupings_parameters() {
665         return new external_function_parameters(
666             array(
667                 'groupings' => new external_multiple_structure(
668                     new external_single_structure(
669                         array(
670                             'id' => new external_value(PARAM_INT, 'id of grouping'),
671                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
672                             'description' => new external_value(PARAM_RAW, 'grouping description text'),
673                             'descriptionformat' => new external_format_value('description', VALUE_DEFAULT)
674                         )
675                     ), 'List of grouping object. A grouping has a courseid, a name and a description.'
676                 )
677             )
678         );
679     }
681     /**
682      * Update groupings
683      *
684      * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
685      * @return array of newly updated groupings
686      * @since Moodle 2.3
687      */
688     public static function update_groupings($groupings) {
689         global $CFG, $DB;
690         require_once("$CFG->dirroot/group/lib.php");
692         $params = self::validate_parameters(self::update_groupings_parameters(), array('groupings'=>$groupings));
694         $transaction = $DB->start_delegated_transaction();
696         foreach ($params['groupings'] as $grouping) {
697             $grouping = (object)$grouping;
699             if (trim($grouping->name) == '') {
700                 throw new invalid_parameter_exception('Invalid grouping name');
701             }
703             if (! $currentgrouping = $DB->get_record('groupings', array('id'=>$grouping->id))) {
704                 throw new invalid_parameter_exception("Grouping $grouping->id does not exist in the course");
705             }
707             // Check if the new modified grouping name already exists in the course.
708             if ($grouping->name != $currentgrouping->name and
709                     $DB->count_records('groupings', array('courseid'=>$currentgrouping->courseid, 'name'=>$grouping->name))) {
710                 throw new invalid_parameter_exception('A different grouping with the same name already exists in the course');
711             }
713             $grouping->courseid = $currentgrouping->courseid;
715             // Now security checks.
716             $context = context_course::instance($grouping->courseid);
717             try {
718                 self::validate_context($context);
719             } catch (Exception $e) {
720                 $exceptionparam = new stdClass();
721                 $exceptionparam->message = $e->getMessage();
722                 $exceptionparam->courseid = $grouping->courseid;
723                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
724             }
725             require_capability('moodle/course:managegroups', $context);
727             // We must force allways FORMAT_HTML.
728             $grouping->descriptionformat = external_validate_format($grouping->descriptionformat);
730             // Finally update the grouping.
731             groups_update_grouping($grouping);
732         }
734         $transaction->allow_commit();
736         return null;
737     }
739     /**
740      * Returns description of method result value
741      *
742      * @return external_description
743      * @since Moodle 2.3
744      */
745     public static function update_groupings_returns() {
746         return null;
747     }
749     /**
750      * Returns description of method parameters
751      *
752      * @return external_function_parameters
753      * @since Moodle 2.3
754      */
755     public static function get_groupings_parameters() {
756         return new external_function_parameters(
757             array(
758                 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')
759                         , 'List of grouping id. A grouping id is an integer.'),
760             )
761         );
762     }
764     /**
765      * Get groupings definition specified by ids
766      *
767      * @param array $groupingids arrays of grouping ids
768      * @return array of grouping objects (id, courseid, name)
769      * @since Moodle 2.3
770      */
771     public static function get_groupings($groupingids) {
772         global $CFG;
773         require_once("$CFG->dirroot/group/lib.php");
774         require_once("$CFG->libdir/filelib.php");
776         $params = self::validate_parameters(self::get_groupings_parameters(), array('groupingids'=>$groupingids));
778         $groupings = array();
779         foreach ($params['groupingids'] as $groupingid) {
780             // Validate params.
781             $grouping = groups_get_grouping($groupingid, '*', MUST_EXIST);
783             // Now security checks.
784             $context = context_course::instance($grouping->courseid);
785             try {
786                 self::validate_context($context);
787             } catch (Exception $e) {
788                 $exceptionparam = new stdClass();
789                 $exceptionparam->message = $e->getMessage();
790                 $exceptionparam->courseid = $grouping->courseid;
791                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
792             }
793             require_capability('moodle/course:managegroups', $context);
795             list($grouping->description, $grouping->descriptionformat) =
796                 external_format_text($grouping->description, $grouping->descriptionformat,
797                         $context->id, 'grouping', 'description', $grouping->id);
799             $groupings[] = (array)$grouping;
800         }
802         return $groupings;
803     }
805     /**
806      * Returns description of method result value
807      *
808      * @return external_description
809      * @since Moodle 2.3
810      */
811     public static function get_groupings_returns() {
812         return new external_multiple_structure(
813             new external_single_structure(
814                 array(
815                     'id' => new external_value(PARAM_INT, 'grouping record id'),
816                     'courseid' => new external_value(PARAM_INT, 'id of course'),
817                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
818                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
819                     'descriptionformat' => new external_format_value('description')
820                 )
821             )
822         );
823     }
825     /**
826      * Returns description of method parameters
827      *
828      * @return external_function_parameters
829      * @since Moodle 2.3
830      */
831     public static function get_course_groupings_parameters() {
832         return new external_function_parameters(
833             array(
834                 'courseid' => new external_value(PARAM_INT, 'id of course'),
835             )
836         );
837     }
839     /**
840      * Get all groupings in the specified course
841      *
842      * @param int $courseid id of course
843      * @return array of grouping objects (id, courseid, name, enrolmentkey)
844      * @since Moodle 2.3
845      */
846     public static function get_course_groupings($courseid) {
847         global $CFG;
848         require_once("$CFG->dirroot/group/lib.php");
849         require_once("$CFG->libdir/filelib.php");
851         $params = self::validate_parameters(self::get_course_groupings_parameters(), array('courseid'=>$courseid));
853         // Now security checks.
854         $context = context_course::instance($params['courseid']);
856         try {
857             self::validate_context($context);
858         } catch (Exception $e) {
859                 $exceptionparam = new stdClass();
860                 $exceptionparam->message = $e->getMessage();
861                 $exceptionparam->courseid = $params['courseid'];
862                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
863         }
864         require_capability('moodle/course:managegroups', $context);
866         $gs = groups_get_all_groupings($params['courseid']);
868         $groupings = array();
869         foreach ($gs as $grouping) {
870             list($grouping->description, $grouping->descriptionformat) =
871                 external_format_text($grouping->description, $grouping->descriptionformat,
872                         $context->id, 'grouping', 'description', $grouping->id);
873             $groupings[] = (array)$grouping;
874         }
876         return $groupings;
877     }
879     /**
880      * Returns description of method result value
881      *
882      * @return external_description
883      * @since Moodle 2.3
884      */
885     public static function get_course_groupings_returns() {
886         return new external_multiple_structure(
887             new external_single_structure(
888                 array(
889                     'id' => new external_value(PARAM_INT, 'grouping record id'),
890                     'courseid' => new external_value(PARAM_INT, 'id of course'),
891                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
892                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
893                     'descriptionformat' => new external_format_value('description')
894                 )
895             )
896         );
897     }
899     /**
900      * Returns description of method parameters
901      *
902      * @return external_function_parameters
903      * @since Moodle 2.3
904      */
905     public static function delete_groupings_parameters() {
906         return new external_function_parameters(
907             array(
908                 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')),
909             )
910         );
911     }
913     /**
914      * Delete groupings
915      *
916      * @param array $groupingids array of grouping ids
917      * @return void
918      * @since Moodle 2.3
919      */
920     public static function delete_groupings($groupingids) {
921         global $CFG, $DB;
922         require_once("$CFG->dirroot/group/lib.php");
924         $params = self::validate_parameters(self::delete_groupings_parameters(), array('groupingids'=>$groupingids));
926         $transaction = $DB->start_delegated_transaction();
928         foreach ($params['groupingids'] as $groupingid) {
930             if (!$grouping = groups_get_grouping($groupingid, 'id, courseid', IGNORE_MISSING)) {
931                 // Silently ignore attempts to delete nonexisting groupings.
932                 continue;
933             }
935             // Now security checks.
936             $context = context_course::instance($grouping->courseid);
937             try {
938                 self::validate_context($context);
939             } catch (Exception $e) {
940                 $exceptionparam = new stdClass();
941                 $exceptionparam->message = $e->getMessage();
942                 $exceptionparam->courseid = $grouping->courseid;
943                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
944             }
945             require_capability('moodle/course:managegroups', $context);
947             groups_delete_grouping($grouping);
948         }
950         $transaction->allow_commit();
951     }
953     /**
954      * Returns description of method result value
955      *
956      * @return external_description
957      * @since Moodle 2.3
958      */
959     public static function delete_groupings_returns() {
960         return null;
961     }
963     /**
964      * Returns description of method parameters
965      *
966      * @return external_function_parameters
967      * @since Moodle 2.3
968      */
969     public static function assign_grouping_parameters() {
970         return new external_function_parameters(
971             array(
972                 'assignments'=> new external_multiple_structure(
973                     new external_single_structure(
974                         array(
975                             'groupingid' => new external_value(PARAM_INT, 'grouping record id'),
976                             'groupid' => new external_value(PARAM_INT, 'group record id'),
977                         )
978                     )
979                 )
980             )
981         );
982     }
984     /**
985      * Assign a group to a grouping
986      *
987      * @param array $assignments of arrays with keys groupid, groupingid
988      * @return void
989      * @since Moodle 2.3
990      */
991     public static function assign_grouping($assignments) {
992         global $CFG, $DB;
993         require_once("$CFG->dirroot/group/lib.php");
995         $params = self::validate_parameters(self::assign_grouping_parameters(), array('assignments'=>$assignments));
997         $transaction = $DB->start_delegated_transaction();
998         foreach ($params['assignments'] as $assignment) {
999             // Validate params.
1000             $groupingid = $assignment['groupingid'];
1001             $groupid = $assignment['groupid'];
1003             $grouping = groups_get_grouping($groupingid, 'id, courseid', MUST_EXIST);
1004             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
1006             if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
1007                 // Continue silently if the group is yet assigned to the grouping.
1008                 continue;
1009             }
1011             // Now security checks.
1012             $context = context_course::instance($grouping->courseid);
1013             try {
1014                 self::validate_context($context);
1015             } catch (Exception $e) {
1016                 $exceptionparam = new stdClass();
1017                 $exceptionparam->message = $e->getMessage();
1018                 $exceptionparam->courseid = $group->courseid;
1019                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
1020             }
1021             require_capability('moodle/course:managegroups', $context);
1023             groups_assign_grouping($groupingid, $groupid);
1024         }
1026         $transaction->allow_commit();
1027     }
1029     /**
1030      * Returns description of method result value
1031      *
1032      * @return null
1033      * @since Moodle 2.3
1034      */
1035     public static function assign_grouping_returns() {
1036         return null;
1037     }
1039     /**
1040      * Returns description of method parameters
1041      *
1042      * @return external_function_parameters
1043      * @since Moodle 2.3
1044      */
1045     public static function unassign_grouping_parameters() {
1046         return new external_function_parameters(
1047             array(
1048                 'unassignments'=> new external_multiple_structure(
1049                     new external_single_structure(
1050                         array(
1051                             'groupingid' => new external_value(PARAM_INT, 'grouping record id'),
1052                             'groupid' => new external_value(PARAM_INT, 'group record id'),
1053                         )
1054                     )
1055                 )
1056             )
1057         );
1058     }
1060     /**
1061      * Unassign a group from a grouping
1062      *
1063      * @param array $unassignments of arrays with keys groupid, groupingid
1064      * @return void
1065      * @since Moodle 2.3
1066      */
1067     public static function unassign_grouping($unassignments) {
1068         global $CFG, $DB;
1069         require_once("$CFG->dirroot/group/lib.php");
1071         $params = self::validate_parameters(self::unassign_grouping_parameters(), array('unassignments'=>$unassignments));
1073         $transaction = $DB->start_delegated_transaction();
1074         foreach ($params['unassignments'] as $unassignment) {
1075             // Validate params.
1076             $groupingid = $unassignment['groupingid'];
1077             $groupid = $unassignment['groupid'];
1079             $grouping = groups_get_grouping($groupingid, 'id, courseid', MUST_EXIST);
1080             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
1082             if (!$DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
1083                 // Continue silently if the group is not assigned to the grouping.
1084                 continue;
1085             }
1087             // Now security checks.
1088             $context = context_course::instance($grouping->courseid);
1089             try {
1090                 self::validate_context($context);
1091             } catch (Exception $e) {
1092                 $exceptionparam = new stdClass();
1093                 $exceptionparam->message = $e->getMessage();
1094                 $exceptionparam->courseid = $group->courseid;
1095                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
1096             }
1097             require_capability('moodle/course:managegroups', $context);
1099             groups_unassign_grouping($groupingid, $groupid);
1100         }
1102         $transaction->allow_commit();
1103     }
1105     /**
1106      * Returns description of method result value
1107      *
1108      * @return null
1109      * @since Moodle 2.3
1110      */
1111     public static function unassign_grouping_returns() {
1112         return null;
1113     }
1117 /**
1118  * Deprecated group external functions
1119  *
1120  * @package    core_group
1121  * @copyright  2009 Petr Skodak
1122  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1123  * @since Moodle 2.0
1124  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
1125  * @todo MDL-31194 This will be deleted in Moodle 2.5.
1126  * @see core_group_external
1127  */
1128 class moodle_group_external extends external_api {
1130     /**
1131      * Returns description of method parameters
1132      *
1133      * @return external_function_parameters
1134      * @since Moodle 2.0
1135      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1136      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1137      * @see core_group_external::create_groups_parameters()
1138      */
1139     public static function create_groups_parameters() {
1140         return core_group_external::create_groups_parameters();
1141     }
1143     /**
1144      * Create groups
1145      *
1146      * @param array $groups array of group description arrays (with keys groupname and courseid)
1147      * @return array of newly created groups
1148      * @since Moodle 2.0
1149      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1150      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1151      * @see use core_group_external::create_groups()
1152      */
1153     public static function create_groups($groups) {
1154         return core_group_external::create_groups($groups);
1155     }
1157     /**
1158      * Returns description of method result value
1159      *
1160      * @return external_description
1161      * @since Moodle 2.0
1162      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1163      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1164      * @see core_group_external::create_groups_returns()
1165      */
1166     public static function create_groups_returns() {
1167         return core_group_external::create_groups_returns();
1168     }
1170     /**
1171      * Returns description of method parameters
1172      *
1173      * @return external_function_parameters
1174      * @since Moodle 2.0
1175      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1176      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1177      * @see core_group_external::get_groups_parameters()
1178      */
1179     public static function get_groups_parameters() {
1180         return core_group_external::get_groups_parameters();
1181     }
1183     /**
1184      * Get groups definition specified by ids
1185      *
1186      * @param array $groupids arrays of group ids
1187      * @return array of group objects (id, courseid, name, enrolmentkey)
1188      * @since Moodle 2.0
1189      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1190      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1191      * @see core_group_external::get_groups()
1192      */
1193     public static function get_groups($groupids) {
1194         return core_group_external::get_groups($groupids);
1195     }
1197     /**
1198      * Returns description of method result value
1199      *
1200      * @return external_description
1201      * @since Moodle 2.0
1202      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1203      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1204      * @see core_group_external::get_groups_returns()
1205      */
1206     public static function get_groups_returns() {
1207         return core_group_external::get_groups_returns();
1208     }
1210     /**
1211      * Returns description of method parameters
1212      *
1213      * @return external_function_parameters
1214      * @since Moodle 2.0
1215      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1216      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1217      * @see core_group_external::get_course_groups_parameters()
1218      */
1219     public static function get_course_groups_parameters() {
1220         return core_group_external::get_course_groups_parameters();
1221     }
1223     /**
1224      * Get all groups in the specified course
1225      *
1226      * @param int $courseid id of course
1227      * @return array of group objects (id, courseid, name, enrolmentkey)
1228      * @since Moodle 2.0
1229      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1230      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1231      * @see core_group_external::get_course_groups()
1232      */
1233     public static function get_course_groups($courseid) {
1234         return core_group_external::get_course_groups($courseid);
1235     }
1237     /**
1238      * Returns description of method result value
1239      *
1240      * @return external_description
1241      * @since Moodle 2.0
1242      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1243      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1244      * @see core_group_external::get_course_groups_returns()
1245      */
1246     public static function get_course_groups_returns() {
1247         return core_group_external::get_course_groups_returns();
1248     }
1250     /**
1251      * Returns description of method parameters
1252      *
1253      * @return external_function_parameters
1254      * @since Moodle 2.0
1255      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1256      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1257      * @see core_group_external::delete_group_members_parameters()
1258      */
1259     public static function delete_groups_parameters() {
1260         return core_group_external::delete_group_members_parameters();
1261     }
1263     /**
1264      * Delete groups
1265      *
1266      * @param array $groupids array of group ids
1267      * @since Moodle 2.0
1268      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1269      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1270      * @see core_group_external::delete_groups()
1271      */
1272     public static function delete_groups($groupids) {
1273         return core_group_external::delete_groups($groupids);
1274     }
1276     /**
1277      * Returns description of method result value
1278      *
1279      * @return null
1280      * @since Moodle 2.0
1281      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1282      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1283      * @see core_group_external::delete_group_members_returns()
1284      */
1285     public static function delete_groups_returns() {
1286         return core_group_external::delete_group_members_returns();
1287     }
1290     /**
1291      * Returns description of method parameters
1292      *
1293      * @return external_function_parameters
1294      * @since Moodle 2.0
1295      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1296      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1297      * @see core_group_external::get_group_members_parameters()
1298      */
1299     public static function get_groupmembers_parameters() {
1300         return core_group_external::get_group_members_parameters();
1301     }
1303     /**
1304      * Return all members for a group
1305      *
1306      * @param array $groupids array of group ids
1307      * @return array with  group id keys containing arrays of user ids
1308      * @since Moodle 2.0
1309      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1310      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1311      * @see core_group_external::get_group_members()
1312      */
1313     public static function get_groupmembers($groupids) {
1314         return core_group_external::get_group_members($groupids);
1315     }
1317     /**
1318      * Returns description of method result value
1319      *
1320      * @return external_description
1321      * @since Moodle 2.0
1322      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1323      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1324      * @see core_group_external::get_group_members_returns()
1325      */
1326     public static function get_groupmembers_returns() {
1327         return core_group_external::get_group_members_returns();
1328     }
1331     /**
1332      * Returns description of method parameters
1333      *
1334      * @return external_function_parameters
1335      * @since Moodle 2.0
1336      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1337      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1338      * @see core_group_external::add_group_members_parameters()
1339      */
1340     public static function add_groupmembers_parameters() {
1341         return core_group_external::add_group_members_parameters();
1342     }
1344     /**
1345      * Add group members
1346      *
1347      * @param array $members of arrays with keys userid, groupid
1348      * @since Moodle 2.0
1349      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1350      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1351      * @see use core_group_external::add_group_members()
1352      */
1353     public static function add_groupmembers($members) {
1354         return core_group_external::add_group_members($members);
1355     }
1357     /**
1358      * Returns description of method result value
1359      *
1360      * @return external_description
1361      * @since Moodle 2.0
1362      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1363      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1364      * @see core_group_external::add_group_members_returns()
1365      */
1366     public static function add_groupmembers_returns() {
1367         return core_group_external::add_group_members_returns();
1368     }
1371     /**
1372      * Returns description of method parameters
1373      *
1374      * @return external_function_parameters
1375      * @since Moodle 2.0
1376      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1377      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1378      * @see core_group_external::delete_group_members_parameters()
1379      */
1380     public static function delete_groupmembers_parameters() {
1381         return core_group_external::delete_group_members_parameters();
1382     }
1384     /**
1385      * Delete group members
1386      *
1387      * @param array $members of arrays with keys userid, groupid
1388      * @since Moodle 2.0
1389      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1390      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1391      * @see core_group_external::delete_group_members()
1392      */
1393     public static function delete_groupmembers($members) {
1394         return core_group_external::delete_group_members($members);
1395     }
1397     /**
1398      * Returns description of method result value
1399      *
1400      * @return external_description
1401      * @since Moodle 2.0
1402      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1403      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1404      * @see core_group_external::delete_group_members_returns()
1405      */
1406     public static function delete_groupmembers_returns() {
1407         return core_group_external::delete_group_members_returns();
1408     }