123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476 |
- <?php
- // This file is part of Moodle - http://moodle.org/
- //
- // Moodle is free software: you can redistribute it and/or modify
- // it under the terms of the GNU General Public License as published by
- // the Free Software Foundation, either version 3 of the License, or
- // (at your option) any later version.
- //
- // Moodle is distributed in the hope that it will be useful,
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- // GNU General Public License for more details.
- //
- // You should have received a copy of the GNU General Public License
- // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
- /**
- * External groups API
- *
- * @package core_group
- * @category external
- * @copyright 2009 Petr Skodak
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
- require_once("$CFG->libdir/externallib.php");
- /**
- * Group external functions
- *
- * @package core_group
- * @category external
- * @copyright 2011 Jerome Mouneyrac
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since Moodle 2.2
- */
- class core_group_external extends external_api {
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function create_groups_parameters() {
- return new external_function_parameters(
- array(
- 'groups' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'group description text'),
- 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
- 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase', VALUE_OPTIONAL),
- 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
- )
- ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
- )
- )
- );
- }
- /**
- * Create groups
- *
- * @param array $groups array of group description arrays (with keys groupname and courseid)
- * @return array of newly created groups
- * @since Moodle 2.2
- */
- public static function create_groups($groups) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
- $transaction = $DB->start_delegated_transaction();
- $groups = array();
- foreach ($params['groups'] as $group) {
- $group = (object)$group;
- if (trim($group->name) == '') {
- throw new invalid_parameter_exception('Invalid group name');
- }
- if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
- throw new invalid_parameter_exception('Group with the same name already exists in the course');
- }
- if (!empty($group->idnumber) && $DB->count_records('groups', array('idnumber' => $group->idnumber))) {
- throw new invalid_parameter_exception('Group with the same idnumber already exists');
- }
- // now security checks
- $context = context_course::instance($group->courseid, IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- // Validate format.
- $group->descriptionformat = external_validate_format($group->descriptionformat);
- // finally create the group
- $group->id = groups_create_group($group, false);
- if (!isset($group->enrolmentkey)) {
- $group->enrolmentkey = '';
- }
- if (!isset($group->idnumber)) {
- $group->idnumber = '';
- }
- $groups[] = (array)$group;
- }
- $transaction->allow_commit();
- return $groups;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.2
- */
- public static function create_groups_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'group record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'group description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number')
- )
- ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function get_groups_parameters() {
- return new external_function_parameters(
- array(
- 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
- ,'List of group id. A group id is an integer.'),
- )
- );
- }
- /**
- * Get groups definition specified by ids
- *
- * @param array $groupids arrays of group ids
- * @return array of group objects (id, courseid, name, enrolmentkey)
- * @since Moodle 2.2
- */
- public static function get_groups($groupids) {
- $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
- $groups = array();
- foreach ($params['groupids'] as $groupid) {
- // validate params
- $group = groups_get_group($groupid, 'id, courseid, name, idnumber, description, descriptionformat, enrolmentkey', MUST_EXIST);
- // now security checks
- $context = context_course::instance($group->courseid, IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- list($group->description, $group->descriptionformat) =
- external_format_text($group->description, $group->descriptionformat,
- $context->id, 'group', 'description', $group->id);
- $groups[] = (array)$group;
- }
- return $groups;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.2
- */
- public static function get_groups_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'group record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'group description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number')
- )
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function get_course_groups_parameters() {
- return new external_function_parameters(
- array(
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- )
- );
- }
- /**
- * Get all groups in the specified course
- *
- * @param int $courseid id of course
- * @return array of group objects (id, courseid, name, enrolmentkey)
- * @since Moodle 2.2
- */
- public static function get_course_groups($courseid) {
- $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
- // now security checks
- $context = context_course::instance($params['courseid'], IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $params['courseid'];
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- $gs = groups_get_all_groups($params['courseid'], 0, 0,
- 'g.id, g.courseid, g.name, g.idnumber, g.description, g.descriptionformat, g.enrolmentkey');
- $groups = array();
- foreach ($gs as $group) {
- list($group->description, $group->descriptionformat) =
- external_format_text($group->description, $group->descriptionformat,
- $context->id, 'group', 'description', $group->id);
- $groups[] = (array)$group;
- }
- return $groups;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.2
- */
- public static function get_course_groups_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'group record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'group description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number')
- )
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function delete_groups_parameters() {
- return new external_function_parameters(
- array(
- 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
- )
- );
- }
- /**
- * Delete groups
- *
- * @param array $groupids array of group ids
- * @since Moodle 2.2
- */
- public static function delete_groups($groupids) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['groupids'] as $groupid) {
- // validate params
- $groupid = validate_param($groupid, PARAM_INT);
- if (!$group = groups_get_group($groupid, '*', IGNORE_MISSING)) {
- // silently ignore attempts to delete nonexisting groups
- continue;
- }
- // now security checks
- $context = context_course::instance($group->courseid, IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- groups_delete_group($group);
- }
- $transaction->allow_commit();
- }
- /**
- * Returns description of method result value
- *
- * @return null
- * @since Moodle 2.2
- */
- public static function delete_groups_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function get_group_members_parameters() {
- return new external_function_parameters(
- array(
- 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
- )
- );
- }
- /**
- * Return all members for a group
- *
- * @param array $groupids array of group ids
- * @return array with group id keys containing arrays of user ids
- * @since Moodle 2.2
- */
- public static function get_group_members($groupids) {
- $members = array();
- $params = self::validate_parameters(self::get_group_members_parameters(), array('groupids'=>$groupids));
- foreach ($params['groupids'] as $groupid) {
- // validate params
- $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
- // now security checks
- $context = context_course::instance($group->courseid, IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
- $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
- }
- return $members;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.2
- */
- public static function get_group_members_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'groupid' => new external_value(PARAM_INT, 'group record id'),
- 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
- )
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function add_group_members_parameters() {
- return new external_function_parameters(
- array(
- 'members'=> new external_multiple_structure(
- new external_single_structure(
- array(
- 'groupid' => new external_value(PARAM_INT, 'group record id'),
- 'userid' => new external_value(PARAM_INT, 'user id'),
- )
- )
- )
- )
- );
- }
- /**
- * Add group members
- *
- * @param array $members of arrays with keys userid, groupid
- * @since Moodle 2.2
- */
- public static function add_group_members($members) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::add_group_members_parameters(), array('members'=>$members));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['members'] as $member) {
- // validate params
- $groupid = $member['groupid'];
- $userid = $member['userid'];
- $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
- $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
- // now security checks
- $context = context_course::instance($group->courseid, IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- // now make sure user is enrolled in course - this is mandatory requirement,
- // unfortunately this is slow
- if (!is_enrolled($context, $userid)) {
- throw new invalid_parameter_exception('Only enrolled users may be members of groups');
- }
- groups_add_member($group, $user);
- }
- $transaction->allow_commit();
- }
- /**
- * Returns description of method result value
- *
- * @return null
- * @since Moodle 2.2
- */
- public static function add_group_members_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.2
- */
- public static function delete_group_members_parameters() {
- return new external_function_parameters(
- array(
- 'members'=> new external_multiple_structure(
- new external_single_structure(
- array(
- 'groupid' => new external_value(PARAM_INT, 'group record id'),
- 'userid' => new external_value(PARAM_INT, 'user id'),
- )
- )
- )
- )
- );
- }
- /**
- * Delete group members
- *
- * @param array $members of arrays with keys userid, groupid
- * @since Moodle 2.2
- */
- public static function delete_group_members($members) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::delete_group_members_parameters(), array('members'=>$members));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['members'] as $member) {
- // validate params
- $groupid = $member['groupid'];
- $userid = $member['userid'];
- $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
- $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
- // now security checks
- $context = context_course::instance($group->courseid, IGNORE_MISSING);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- if (!groups_remove_member_allowed($group, $user)) {
- throw new moodle_exception('errorremovenotpermitted', 'group', '', fullname($user));
- }
- groups_remove_member($group, $user);
- }
- $transaction->allow_commit();
- }
- /**
- * Returns description of method result value
- *
- * @return null
- * @since Moodle 2.2
- */
- public static function delete_group_members_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function create_groupings_parameters() {
- return new external_function_parameters(
- array(
- 'groupings' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'grouping description text'),
- 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
- 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
- )
- ), 'List of grouping object. A grouping has a courseid, a name and a description.'
- )
- )
- );
- }
- /**
- * Create groupings
- *
- * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
- * @return array of newly created groupings
- * @since Moodle 2.3
- */
- public static function create_groupings($groupings) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::create_groupings_parameters(), array('groupings'=>$groupings));
- $transaction = $DB->start_delegated_transaction();
- $groupings = array();
- foreach ($params['groupings'] as $grouping) {
- $grouping = (object)$grouping;
- if (trim($grouping->name) == '') {
- throw new invalid_parameter_exception('Invalid grouping name');
- }
- if ($DB->count_records('groupings', array('courseid'=>$grouping->courseid, 'name'=>$grouping->name))) {
- throw new invalid_parameter_exception('Grouping with the same name already exists in the course');
- }
- if (!empty($grouping->idnumber) && $DB->count_records('groupings', array('idnumber' => $grouping->idnumber))) {
- throw new invalid_parameter_exception('Grouping with the same idnumber already exists');
- }
- // Now security checks .
- $context = context_course::instance($grouping->courseid);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $grouping->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- $grouping->descriptionformat = external_validate_format($grouping->descriptionformat);
- // Finally create the grouping.
- $grouping->id = groups_create_grouping($grouping);
- $groupings[] = (array)$grouping;
- }
- $transaction->allow_commit();
- return $groupings;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.3
- */
- public static function create_groupings_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'grouping record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'grouping description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number')
- )
- ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function update_groupings_parameters() {
- return new external_function_parameters(
- array(
- 'groupings' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'id of grouping'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'grouping description text'),
- 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
- 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
- )
- ), 'List of grouping object. A grouping has a courseid, a name and a description.'
- )
- )
- );
- }
- /**
- * Update groupings
- *
- * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
- * @return array of newly updated groupings
- * @since Moodle 2.3
- */
- public static function update_groupings($groupings) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::update_groupings_parameters(), array('groupings'=>$groupings));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['groupings'] as $grouping) {
- $grouping = (object)$grouping;
- if (trim($grouping->name) == '') {
- throw new invalid_parameter_exception('Invalid grouping name');
- }
- if (! $currentgrouping = $DB->get_record('groupings', array('id'=>$grouping->id))) {
- throw new invalid_parameter_exception("Grouping $grouping->id does not exist in the course");
- }
- // Check if the new modified grouping name already exists in the course.
- if ($grouping->name != $currentgrouping->name and
- $DB->count_records('groupings', array('courseid'=>$currentgrouping->courseid, 'name'=>$grouping->name))) {
- throw new invalid_parameter_exception('A different grouping with the same name already exists in the course');
- }
- // Check if the new modified grouping idnumber already exists.
- if (!empty($grouping->idnumber) && $grouping->idnumber != $currentgrouping->idnumber &&
- $DB->count_records('groupings', array('idnumber' => $grouping->idnumber))) {
- throw new invalid_parameter_exception('A different grouping with the same idnumber already exists');
- }
- $grouping->courseid = $currentgrouping->courseid;
- // Now security checks.
- $context = context_course::instance($grouping->courseid);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $grouping->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- // We must force allways FORMAT_HTML.
- $grouping->descriptionformat = external_validate_format($grouping->descriptionformat);
- // Finally update the grouping.
- groups_update_grouping($grouping);
- }
- $transaction->allow_commit();
- return null;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.3
- */
- public static function update_groupings_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function get_groupings_parameters() {
- return new external_function_parameters(
- array(
- 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')
- , 'List of grouping id. A grouping id is an integer.'),
- 'returngroups' => new external_value(PARAM_BOOL, 'return associated groups', VALUE_DEFAULT, 0)
- )
- );
- }
- /**
- * Get groupings definition specified by ids
- *
- * @param array $groupingids arrays of grouping ids
- * @param boolean $returngroups return the associated groups if true. The default is false.
- * @return array of grouping objects (id, courseid, name)
- * @since Moodle 2.3
- */
- public static function get_groupings($groupingids, $returngroups = false) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- require_once("$CFG->libdir/filelib.php");
- $params = self::validate_parameters(self::get_groupings_parameters(),
- array('groupingids' => $groupingids,
- 'returngroups' => $returngroups));
- $groupings = array();
- foreach ($params['groupingids'] as $groupingid) {
- // Validate params.
- $grouping = groups_get_grouping($groupingid, '*', MUST_EXIST);
- // Now security checks.
- $context = context_course::instance($grouping->courseid);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $grouping->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- list($grouping->description, $grouping->descriptionformat) =
- external_format_text($grouping->description, $grouping->descriptionformat,
- $context->id, 'grouping', 'description', $grouping->id);
- $groupingarray = (array)$grouping;
- if ($params['returngroups']) {
- $grouprecords = $DB->get_records_sql("SELECT * FROM {groups} g INNER JOIN {groupings_groups} gg ".
- "ON g.id = gg.groupid WHERE gg.groupingid = ? ".
- "ORDER BY groupid", array($groupingid));
- if ($grouprecords) {
- $groups = array();
- foreach ($grouprecords as $grouprecord) {
- list($grouprecord->description, $grouprecord->descriptionformat) =
- external_format_text($grouprecord->description, $grouprecord->descriptionformat,
- $context->id, 'group', 'description', $grouprecord->groupid);
- $groups[] = array('id' => $grouprecord->groupid,
- 'name' => $grouprecord->name,
- 'idnumber' => $grouprecord->idnumber,
- 'description' => $grouprecord->description,
- 'descriptionformat' => $grouprecord->descriptionformat,
- 'enrolmentkey' => $grouprecord->enrolmentkey,
- 'courseid' => $grouprecord->courseid
- );
- }
- $groupingarray['groups'] = $groups;
- }
- }
- $groupings[] = $groupingarray;
- }
- return $groupings;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.3
- */
- public static function get_groupings_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'grouping record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'grouping description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number'),
- 'groups' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'group record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'group description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number')
- )
- ),
- 'optional groups', VALUE_OPTIONAL)
- )
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function get_course_groupings_parameters() {
- return new external_function_parameters(
- array(
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- )
- );
- }
- /**
- * Get all groupings in the specified course
- *
- * @param int $courseid id of course
- * @return array of grouping objects (id, courseid, name, enrolmentkey)
- * @since Moodle 2.3
- */
- public static function get_course_groupings($courseid) {
- global $CFG;
- require_once("$CFG->dirroot/group/lib.php");
- require_once("$CFG->libdir/filelib.php");
- $params = self::validate_parameters(self::get_course_groupings_parameters(), array('courseid'=>$courseid));
- // Now security checks.
- $context = context_course::instance($params['courseid']);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $params['courseid'];
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- $gs = groups_get_all_groupings($params['courseid']);
- $groupings = array();
- foreach ($gs as $grouping) {
- list($grouping->description, $grouping->descriptionformat) =
- external_format_text($grouping->description, $grouping->descriptionformat,
- $context->id, 'grouping', 'description', $grouping->id);
- $groupings[] = (array)$grouping;
- }
- return $groupings;
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.3
- */
- public static function get_course_groupings_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'grouping record id'),
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'grouping description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number')
- )
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function delete_groupings_parameters() {
- return new external_function_parameters(
- array(
- 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')),
- )
- );
- }
- /**
- * Delete groupings
- *
- * @param array $groupingids array of grouping ids
- * @return void
- * @since Moodle 2.3
- */
- public static function delete_groupings($groupingids) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::delete_groupings_parameters(), array('groupingids'=>$groupingids));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['groupingids'] as $groupingid) {
- if (!$grouping = groups_get_grouping($groupingid, 'id, courseid', IGNORE_MISSING)) {
- // Silently ignore attempts to delete nonexisting groupings.
- continue;
- }
- // Now security checks.
- $context = context_course::instance($grouping->courseid);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $grouping->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- groups_delete_grouping($grouping);
- }
- $transaction->allow_commit();
- }
- /**
- * Returns description of method result value
- *
- * @return external_description
- * @since Moodle 2.3
- */
- public static function delete_groupings_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function assign_grouping_parameters() {
- return new external_function_parameters(
- array(
- 'assignments'=> new external_multiple_structure(
- new external_single_structure(
- array(
- 'groupingid' => new external_value(PARAM_INT, 'grouping record id'),
- 'groupid' => new external_value(PARAM_INT, 'group record id'),
- )
- )
- )
- )
- );
- }
- /**
- * Assign a group to a grouping
- *
- * @param array $assignments of arrays with keys groupid, groupingid
- * @return void
- * @since Moodle 2.3
- */
- public static function assign_grouping($assignments) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::assign_grouping_parameters(), array('assignments'=>$assignments));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['assignments'] as $assignment) {
- // Validate params.
- $groupingid = $assignment['groupingid'];
- $groupid = $assignment['groupid'];
- $grouping = groups_get_grouping($groupingid, 'id, courseid', MUST_EXIST);
- $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
- if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
- // Continue silently if the group is yet assigned to the grouping.
- continue;
- }
- // Now security checks.
- $context = context_course::instance($grouping->courseid);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- groups_assign_grouping($groupingid, $groupid);
- }
- $transaction->allow_commit();
- }
- /**
- * Returns description of method result value
- *
- * @return null
- * @since Moodle 2.3
- */
- public static function assign_grouping_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.3
- */
- public static function unassign_grouping_parameters() {
- return new external_function_parameters(
- array(
- 'unassignments'=> new external_multiple_structure(
- new external_single_structure(
- array(
- 'groupingid' => new external_value(PARAM_INT, 'grouping record id'),
- 'groupid' => new external_value(PARAM_INT, 'group record id'),
- )
- )
- )
- )
- );
- }
- /**
- * Unassign a group from a grouping
- *
- * @param array $unassignments of arrays with keys groupid, groupingid
- * @return void
- * @since Moodle 2.3
- */
- public static function unassign_grouping($unassignments) {
- global $CFG, $DB;
- require_once("$CFG->dirroot/group/lib.php");
- $params = self::validate_parameters(self::unassign_grouping_parameters(), array('unassignments'=>$unassignments));
- $transaction = $DB->start_delegated_transaction();
- foreach ($params['unassignments'] as $unassignment) {
- // Validate params.
- $groupingid = $unassignment['groupingid'];
- $groupid = $unassignment['groupid'];
- $grouping = groups_get_grouping($groupingid, 'id, courseid', MUST_EXIST);
- $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
- if (!$DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
- // Continue silently if the group is not assigned to the grouping.
- continue;
- }
- // Now security checks.
- $context = context_course::instance($grouping->courseid);
- try {
- self::validate_context($context);
- } catch (Exception $e) {
- $exceptionparam = new stdClass();
- $exceptionparam->message = $e->getMessage();
- $exceptionparam->courseid = $group->courseid;
- throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
- }
- require_capability('moodle/course:managegroups', $context);
- groups_unassign_grouping($groupingid, $groupid);
- }
- $transaction->allow_commit();
- }
- /**
- * Returns description of method result value
- *
- * @return null
- * @since Moodle 2.3
- */
- public static function unassign_grouping_returns() {
- return null;
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 2.9
- */
- public static function get_course_user_groups_parameters() {
- return new external_function_parameters(
- array(
- 'courseid' => new external_value(PARAM_INT, 'id of course'),
- 'userid' => new external_value(PARAM_INT, 'id of user'),
- 'groupingid' => new external_value(PARAM_INT, 'returns only groups in the specified grouping', VALUE_DEFAULT, 0)
- )
- );
- }
- /**
- * Get all groups in the specified course for the specified user.
- *
- * @throws moodle_exception
- * @param int $courseid id of course.
- * @param int $userid id of user.
- * @param int $groupingid optional returns only groups in the specified grouping.
- * @return array of group objects (id, name, description, format) and possible warnings.
- * @since Moodle 2.9
- */
- public static function get_course_user_groups($courseid, $userid, $groupingid = 0) {
- global $USER;
- // Warnings array, it can be empty at the end but is mandatory.
- $warnings = array();
- $params = array(
- 'courseid' => $courseid,
- 'userid' => $userid,
- 'groupingid' => $groupingid
- );
- $params = self::validate_parameters(self::get_course_user_groups_parameters(), $params);
- $courseid = $params['courseid'];
- $userid = $params['userid'];
- $groupingid = $params['groupingid'];
- // Validate course and user. get_course throws an exception if the course does not exists.
- $course = get_course($courseid);
- $user = core_user::get_user($userid, '*', MUST_EXIST);
- core_user::require_active_user($user);
- // Security checks.
- $context = context_course::instance($course->id);
- self::validate_context($context);
- // Check if we have permissions for retrieve the information.
- if ($user->id != $USER->id) {
- if (!has_capability('moodle/course:managegroups', $context)) {
- throw new moodle_exception('accessdenied', 'admin');
- }
- // Validate if the user is enrolled in the course.
- if (!is_enrolled($context, $user->id)) {
- // We return a warning because the function does not fail for not enrolled users.
- $warning['item'] = 'course';
- $warning['itemid'] = $course->id;
- $warning['warningcode'] = '1';
- $warning['message'] = "User $user->id is not enrolled in course $course->id";
- $warnings[] = $warning;
- }
- }
- $usergroups = array();
- if (empty($warnings)) {
- $groups = groups_get_all_groups($course->id, $user->id, 0, 'g.id, g.name, g.description, g.descriptionformat, g.idnumber');
- foreach ($groups as $group) {
- list($group->description, $group->descriptionformat) =
- external_format_text($group->description, $group->descriptionformat,
- $context->id, 'group', 'description', $group->id);
- $group->courseid = $course->id;
- $usergroups[] = $group;
- }
- }
- $results = array(
- 'groups' => $usergroups,
- 'warnings' => $warnings
- );
- return $results;
- }
- /**
- * Returns description of method result value.
- *
- * @return external_description A single structure containing groups and possible warnings.
- * @since Moodle 2.9
- */
- public static function get_course_user_groups_returns() {
- return new external_single_structure(
- array(
- 'groups' => new external_multiple_structure(self::group_description()),
- 'warnings' => new external_warnings(),
- )
- );
- }
- /**
- * Create group return value description.
- *
- * @return external_single_structure The group description
- */
- public static function group_description() {
- return new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'group record id'),
- 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
- 'description' => new external_value(PARAM_RAW, 'group description text'),
- 'descriptionformat' => new external_format_value('description'),
- 'idnumber' => new external_value(PARAM_RAW, 'id number'),
- 'courseid' => new external_value(PARAM_INT, 'course id', VALUE_OPTIONAL),
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 3.0
- */
- public static function get_activity_allowed_groups_parameters() {
- return new external_function_parameters(
- array(
- 'cmid' => new external_value(PARAM_INT, 'course module id'),
- 'userid' => new external_value(PARAM_INT, 'id of user, empty for current user', VALUE_DEFAULT, 0)
- )
- );
- }
- /**
- * Gets a list of groups that the user is allowed to access within the specified activity.
- *
- * @throws moodle_exception
- * @param int $cmid course module id
- * @param int $userid id of user.
- * @return array of group objects (id, name, description, format) and possible warnings.
- * @since Moodle 3.0
- */
- public static function get_activity_allowed_groups($cmid, $userid = 0) {
- global $USER;
- // Warnings array, it can be empty at the end but is mandatory.
- $warnings = array();
- $params = array(
- 'cmid' => $cmid,
- 'userid' => $userid
- );
- $params = self::validate_parameters(self::get_activity_allowed_groups_parameters(), $params);
- $cmid = $params['cmid'];
- $userid = $params['userid'];
- $cm = get_coursemodule_from_id(null, $cmid, 0, false, MUST_EXIST);
- // Security checks.
- $context = context_module::instance($cm->id);
- $coursecontext = context_course::instance($cm->course);
- self::validate_context($context);
- if (empty($userid)) {
- $userid = $USER->id;
- }
- $user = core_user::get_user($userid, '*', MUST_EXIST);
- core_user::require_active_user($user);
- // Check if we have permissions for retrieve the information.
- if ($user->id != $USER->id) {
- if (!has_capability('moodle/course:managegroups', $context)) {
- throw new moodle_exception('accessdenied', 'admin');
- }
- // Validate if the user is enrolled in the course.
- $course = get_course($cm->course);
- if (!can_access_course($course, $user, '', true)) {
- // We return a warning because the function does not fail for not enrolled users.
- $warning = array();
- $warning['item'] = 'course';
- $warning['itemid'] = $cm->course;
- $warning['warningcode'] = '1';
- $warning['message'] = "User $user->id cannot access course $cm->course";
- $warnings[] = $warning;
- }
- }
- $usergroups = array();
- if (empty($warnings)) {
- $groups = groups_get_activity_allowed_groups($cm, $user->id);
- foreach ($groups as $group) {
- list($group->description, $group->descriptionformat) =
- external_format_text($group->description, $group->descriptionformat,
- $coursecontext->id, 'group', 'description', $group->id);
- $group->courseid = $cm->course;
- $usergroups[] = $group;
- }
- }
- $results = array(
- 'groups' => $usergroups,
- 'warnings' => $warnings
- );
- return $results;
- }
- /**
- * Returns description of method result value.
- *
- * @return external_description A single structure containing groups and possible warnings.
- * @since Moodle 3.0
- */
- public static function get_activity_allowed_groups_returns() {
- return new external_single_structure(
- array(
- 'groups' => new external_multiple_structure(self::group_description()),
- 'warnings' => new external_warnings(),
- )
- );
- }
- /**
- * Returns description of method parameters
- *
- * @return external_function_parameters
- * @since Moodle 3.0
- */
- public static function get_activity_groupmode_parameters() {
- return new external_function_parameters(
- array(
- 'cmid' => new external_value(PARAM_INT, 'course module id')
- )
- );
- }
- /**
- * Returns effective groupmode used in a given activity.
- *
- * @throws moodle_exception
- * @param int $cmid course module id.
- * @return array containing the group mode and possible warnings.
- * @since Moodle 3.0
- * @throws moodle_exception
- */
- public static function get_activity_groupmode($cmid) {
- global $USER;
- // Warnings array, it can be empty at the end but is mandatory.
- $warnings = array();
- $params = array(
- 'cmid' => $cmid
- );
- $params = self::validate_parameters(self::get_activity_groupmode_parameters(), $params);
- $cmid = $params['cmid'];
- $cm = get_coursemodule_from_id(null, $cmid, 0, false, MUST_EXIST);
- // Security checks.
- $context = context_module::instance($cm->id);
- self::validate_context($context);
- $groupmode = groups_get_activity_groupmode($cm);
- $results = array(
- 'groupmode' => $groupmode,
- 'warnings' => $warnings
- );
- return $results;
- }
- /**
- * Returns description of method result value.
- *
- * @return external_description
- * @since Moodle 3.0
- */
- public static function get_activity_groupmode_returns() {
- return new external_single_structure(
- array(
- 'groupmode' => new external_value(PARAM_INT, 'group mode:
- 0 for no groups, 1 for separate groups, 2 for visible groups'),
- 'warnings' => new external_warnings(),
- )
- );
- }
- }
|