moodle/group/externallib.php
Petr Skoda c5eeccbec9 MDL-31117 delete obsolete TODO
This TODO was added when we were still using moodledata folder for group images, it is not relevant any more because group images are in new file API which supports DB transaction rollbacks.
2012-01-15 00:43:28 +01:00

715 lines
26 KiB
PHP

<?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 moodlecore
* @subpackage webservice
* @copyright 2009 Moodle Pty Ltd (http://moodle.com)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->libdir/externallib.php");
/**
* Group functions
*/
class core_group_external extends external_api {
/**
* Returns description of method parameters
* @return external_function_parameters
*/
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'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
), '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
*/
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');
}
// now security checks
$context = get_context_instance(CONTEXT_COURSE, $group->courseid);
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $group->courseid;
throw new moodle_exception(
get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
}
require_capability('moodle/course:managegroups', $context);
// finally create the group
$group->id = groups_create_group($group, false);
$groups[] = (array)$group;
}
$transaction->allow_commit();
return $groups;
}
/**
* Returns description of method result value
* @return external_description
*/
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'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
), '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
*/
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)
*/
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, description, enrolmentkey', MUST_EXIST);
// now security checks
$context = get_context_instance(CONTEXT_COURSE, $group->courseid);
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $group->courseid;
throw new moodle_exception(
get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
}
require_capability('moodle/course:managegroups', $context);
$groups[] = (array)$group;
}
return $groups;
}
/**
* Returns description of method result value
* @return external_description
*/
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'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
)
);
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
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)
*/
public static function get_course_groups($courseid) {
$params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
// now security checks
$context = get_context_instance(CONTEXT_COURSE, $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(
get_string('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.description, g.enrolmentkey');
$groups = array();
foreach ($gs as $group) {
$groups[] = (array)$group;
}
return $groups;
}
/**
* Returns description of method result value
* @return external_description
*/
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'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
)
);
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
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
* @return void
*/
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_INTEGER);
if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
// silently ignore attempts to delete nonexisting groups
continue;
}
// now security checks
$context = get_context_instance(CONTEXT_COURSE, $group->courseid);
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $group->courseid;
throw new moodle_exception(
get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
}
require_capability('moodle/course:managegroups', $context);
groups_delete_group($group);
}
$transaction->allow_commit();
}
/**
* Returns description of method result value
* @return external_description
*/
public static function delete_groups_returns() {
return null;
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
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
*/
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 = get_context_instance(CONTEXT_COURSE, $group->courseid);
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $group->courseid;
throw new moodle_exception(
get_string('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
*/
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
*/
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
* @return void
*/
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 = get_context_instance(CONTEXT_COURSE, $group->courseid);
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $group->courseid;
throw new moodle_exception(
get_string('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
*/
public static function add_group_members_returns() {
return null;
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
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
* @return void
*/
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 = get_context_instance(CONTEXT_COURSE, $group->courseid);
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $group->courseid;
throw new moodle_exception(
get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
}
require_capability('moodle/course:managegroups', $context);
groups_remove_member($group, $user);
}
$transaction->allow_commit();
}
/**
* Returns description of method result value
* @return null
*/
public static function delete_group_members_returns() {
return null;
}
}
/**
* Deprecated group functions
* @deprecated since Moodle 2.2 please use core_group_external instead
*/
class moodle_group_external extends external_api {
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::create_groups_parameters instead
* @return external_function_parameters
*/
public static function create_groups_parameters() {
return core_group_external::create_groups_parameters();
}
/**
* Create groups
* @deprecated since Moodle 2.2 please use core_group_external::create_groups instead
* @param array $groups array of group description arrays (with keys groupname and courseid)
* @return array of newly created groups
*/
public static function create_groups($groups) {
return core_group_external::create_groups($groups);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::create_groups_returns instead
* @return external_description
*/
public static function create_groups_returns() {
return core_group_external::create_groups_returns();
}
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::get_groups_parameters instead
* @return external_function_parameters
*/
public static function get_groups_parameters() {
return core_group_external::get_groups_parameters();
}
/**
* Get groups definition specified by ids
* @deprecated since Moodle 2.2 please use core_group_external::get_groups instead
* @param array $groupids arrays of group ids
* @return array of group objects (id, courseid, name, enrolmentkey)
*/
public static function get_groups($groupids) {
return core_group_external::get_groups($groupids);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::get_groups_returns instead
* @return external_description
*/
public static function get_groups_returns() {
return core_group_external::get_groups_returns();
}
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::get_course_groups_parameters instead
* @return external_function_parameters
*/
public static function get_course_groups_parameters() {
return core_group_external::get_course_groups_parameters();
}
/**
* Get all groups in the specified course
* @deprecated since Moodle 2.2 please use core_group_external::get_course_groups instead
* @param int $courseid id of course
* @return array of group objects (id, courseid, name, enrolmentkey)
*/
public static function get_course_groups($courseid) {
return core_group_external::get_course_groups($courseid);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::get_course_groups_returns instead
* @return external_description
*/
public static function get_course_groups_returns() {
return core_group_external::get_course_groups_returns();
}
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::delete_group_members_parameters instead
* @return external_function_parameters
*/
public static function delete_groups_parameters() {
return core_group_external::delete_group_members_parameters();
}
/**
* Delete groups
* @deprecated since Moodle 2.2 please use core_group_external::delete_groups instead
* @param array $groupids array of group ids
* @return void
*/
public static function delete_groups($groupids) {
return core_group_external::delete_groups($groupids);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::delete_group_members_returns instead
* @return external_description
*/
public static function delete_groups_returns() {
return core_group_external::delete_group_members_returns();
}
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::get_group_members_parameters instead
* @return external_function_parameters
*/
public static function get_groupmembers_parameters() {
return core_group_external::get_group_members_parameters();
}
/**
* Return all members for a group
* @deprecated since Moodle 2.2 please use core_group_external::get_group_members instead
* @param array $groupids array of group ids
* @return array with group id keys containing arrays of user ids
*/
public static function get_groupmembers($groupids) {
return core_group_external::get_group_members($groupids);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::get_group_members_returns instead
* @return external_description
*/
public static function get_groupmembers_returns() {
return core_group_external::get_group_members_returns();
}
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::add_group_members_parameters instead
* @return external_function_parameters
*/
public static function add_groupmembers_parameters() {
return core_group_external::add_group_members_parameters();
}
/**
* Add group members
* @deprecated since Moodle 2.2 please use core_group_external::add_group_members instead
* @param array $members of arrays with keys userid, groupid
* @return void
*/
public static function add_groupmembers($members) {
return core_group_external::add_group_members($members);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::add_group_members_returns instead
* @return external_description
*/
public static function add_groupmembers_returns() {
return core_group_external::add_group_members_returns();
}
/**
* Returns description of method parameters
* @deprecated since Moodle 2.2 please use core_group_external::delete_group_members_parameters instead
* @return external_function_parameters
*/
public static function delete_groupmembers_parameters() {
return core_group_external::delete_group_members_parameters();
}
/**
* Delete group members
* @deprecated since Moodle 2.2 please use core_group_external::delete_group_members instead
* @param array $members of arrays with keys userid, groupid
* @return void
*/
public static function delete_groupmembers($members) {
return core_group_external::delete_group_members($members);
}
/**
* Returns description of method result value
* @deprecated since Moodle 2.2 please use core_group_external::delete_group_members_returns instead
* @return external_description
*/
public static function delete_groupmembers_returns() {
return core_group_external::delete_group_members_returns();
}
}