Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
<?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/>.

> use core_external\external_api; /** > use core_external\external_format_value; * External cohort API > use core_external\external_function_parameters; * > use core_external\external_multiple_structure; * @package core_cohort > use core_external\external_single_structure; * @category external > use core_external\external_value; * @copyright MediaTouch 2000 srl > use core_external\external_warnings; * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later > use core_external\util; */ > > defined('MOODLE_INTERNAL') || die(); defined('MOODLE_INTERNAL') || die(); > > require_once($CFG->dirroot . '/cohort/lib.php'); require_once("$CFG->libdir/externallib.php"); >
< < defined('MOODLE_INTERNAL') || die(); < < require_once("$CFG->libdir/externallib.php"); <
* * @return external_function_parameters * @since Moodle 2.5 */ public static function create_cohorts_parameters() { return new external_function_parameters( array( 'cohorts' => new external_multiple_structure( new external_single_structure( array( 'categorytype' => new external_single_structure( array( 'type' => new external_value(PARAM_TEXT, 'the name of the field: id (numeric value of course category id) or idnumber (alphanumeric value of idnumber course category) or system (value ignored)'), 'value' => new external_value(PARAM_RAW, 'the value of the categorytype') ) ), 'name' => new external_value(PARAM_RAW, 'cohort name'), 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'), 'description' => new external_value(PARAM_RAW, 'cohort description', VALUE_OPTIONAL), 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT), 'visible' => new external_value(PARAM_BOOL, 'cohort visible', VALUE_OPTIONAL, true), 'theme' => new external_value(PARAM_THEME, 'the cohort theme. The allowcohortthemes setting must be enabled on Moodle', VALUE_OPTIONAL ),
> 'customfields' => self::build_custom_fields_parameters_structure(),
) ) ) ) ); } /** * Create one or more cohorts * * @param array $cohorts An array of cohorts to create. * @return array An array of arrays * @since Moodle 2.5 */ public static function create_cohorts($cohorts) { global $CFG, $DB; require_once("$CFG->dirroot/cohort/lib.php"); $params = self::validate_parameters(self::create_cohorts_parameters(), array('cohorts' => $cohorts)); $availablethemes = cohort_get_list_of_themes(); $transaction = $DB->start_delegated_transaction(); $syscontext = context_system::instance(); $cohortids = array(); foreach ($params['cohorts'] as $cohort) { $cohort = (object)$cohort; // Category type (context id). $categorytype = $cohort->categorytype; if (!in_array($categorytype['type'], array('idnumber', 'id', 'system'))) { throw new invalid_parameter_exception('category type must be id, idnumber or system:' . $categorytype['type']); } if ($categorytype['type'] === 'system') { $cohort->contextid = $syscontext->id; } else if ($catid = $DB->get_field('course_categories', 'id', array($categorytype['type'] => $categorytype['value']))) { $catcontext = context_coursecat::instance($catid); $cohort->contextid = $catcontext->id; } else { throw new invalid_parameter_exception('category not exists: category ' .$categorytype['type'].' = '.$categorytype['value']); } // Make sure that the idnumber doesn't already exist. if ($DB->record_exists('cohort', array('idnumber' => $cohort->idnumber))) { throw new invalid_parameter_exception('record already exists: idnumber='.$cohort->idnumber); } $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { throw new invalid_parameter_exception('Invalid context'); } self::validate_context($context); require_capability('moodle/cohort:manage', $context); // Make sure theme is valid. if (isset($cohort->theme)) { if (!empty($CFG->allowcohortthemes)) { if (empty($availablethemes[$cohort->theme])) { throw new moodle_exception('errorinvalidparam', 'webservice', '', 'theme'); } } } // Validate format.
< $cohort->descriptionformat = external_validate_format($cohort->descriptionformat);
> $cohort->descriptionformat = util::validate_format($cohort->descriptionformat); > > // Custom fields. > if (!empty($cohort->customfields)) { > foreach ($cohort->customfields as $field) { > $fieldname = self::build_custom_field_name($field['shortname']); > $cohort->{$fieldname} = $field['value']; > } > unset($cohort->customfields); > } >
$cohort->id = cohort_add_cohort($cohort); list($cohort->description, $cohort->descriptionformat) =
< external_format_text($cohort->description, $cohort->descriptionformat, < $context->id, 'cohort', 'description', $cohort->id);
> \core_external\util::format_text($cohort->description, $cohort->descriptionformat, > $context, 'cohort', 'description', $cohort->id);
$cohortids[] = (array)$cohort; } $transaction->allow_commit(); return $cohortids; } /** * Returns description of method result value *
< * @return external_description
> * @return \core_external\external_description
* @since Moodle 2.5 */ public static function create_cohorts_returns() { return new external_multiple_structure( new external_single_structure( array( 'id' => new external_value(PARAM_INT, 'cohort id'), 'name' => new external_value(PARAM_RAW, 'cohort name'), 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'), 'description' => new external_value(PARAM_RAW, 'cohort description'), 'descriptionformat' => new external_format_value('description'), 'visible' => new external_value(PARAM_BOOL, 'cohort visible'), 'theme' => new external_value(PARAM_THEME, 'cohort theme', VALUE_OPTIONAL), ) ) ); } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.5 */ public static function delete_cohorts_parameters() { return new external_function_parameters( array( 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'cohort ID')), ) ); } /** * Delete cohorts * * @param array $cohortids * @return null * @since Moodle 2.5 */ public static function delete_cohorts($cohortids) { global $CFG, $DB; require_once("$CFG->dirroot/cohort/lib.php"); $params = self::validate_parameters(self::delete_cohorts_parameters(), array('cohortids' => $cohortids)); $transaction = $DB->start_delegated_transaction(); foreach ($params['cohortids'] as $cohortid) { // Validate params. $cohortid = validate_param($cohortid, PARAM_INT); $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST); // Now security checks. $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { throw new invalid_parameter_exception('Invalid context'); } self::validate_context($context); require_capability('moodle/cohort:manage', $context); cohort_delete_cohort($cohort); } $transaction->allow_commit(); return null; } /** * Returns description of method result value * * @return null * @since Moodle 2.5 */ public static function delete_cohorts_returns() { return null; } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.5 */ public static function get_cohorts_parameters() { return new external_function_parameters( array( 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'Cohort ID') , 'List of cohort id. A cohort id is an integer.', VALUE_DEFAULT, array()), ) ); } /** * Get cohorts definition specified by ids * * @param array $cohortids array of cohort ids * @return array of cohort objects (id, courseid, name) * @since Moodle 2.5 */ public static function get_cohorts($cohortids = array()) { global $DB, $CFG; $params = self::validate_parameters(self::get_cohorts_parameters(), array('cohortids' => $cohortids)); if (empty($cohortids)) { $cohorts = $DB->get_records('cohort');
> if (!empty($cohorts)) { } else { > $cohortids = array_keys($cohorts); $cohorts = $DB->get_records_list('cohort', 'id', $params['cohortids']); > }
}
> $customfieldsdata = self::get_custom_fields_data($cohortids);
$cohortsinfo = array(); foreach ($cohorts as $cohort) { // Now security checks. $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { throw new invalid_parameter_exception('Invalid context'); } self::validate_context($context); if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) { throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', ''); } // Only return theme when $CFG->allowcohortthemes is enabled. if (!empty($cohort->theme) && empty($CFG->allowcohortthemes)) { $cohort->theme = null; } list($cohort->description, $cohort->descriptionformat) =
< external_format_text($cohort->description, $cohort->descriptionformat, < $context->id, 'cohort', 'description', $cohort->id);
> \core_external\util::format_text($cohort->description, $cohort->descriptionformat, > $context, 'cohort', 'description', $cohort->id);
> $cohort->customfields = !empty($customfieldsdata[$cohort->id]) ? $customfieldsdata[$cohort->id] : [];
$cohortsinfo[] = (array) $cohort; } return $cohortsinfo; } /** * Returns description of method result value *
< * @return external_description
> * @return \core_external\external_description
* @since Moodle 2.5 */ public static function get_cohorts_returns() { return new external_multiple_structure( new external_single_structure( array( 'id' => new external_value(PARAM_INT, 'ID of the cohort'), 'name' => new external_value(PARAM_RAW, 'cohort name'), 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'), 'description' => new external_value(PARAM_RAW, 'cohort description'), 'descriptionformat' => new external_format_value('description'), 'visible' => new external_value(PARAM_BOOL, 'cohort visible'), 'theme' => new external_value(PARAM_THEME, 'cohort theme', VALUE_OPTIONAL),
> 'customfields' => self::build_custom_fields_returns_structure(),
) ) ); } /** * Returns the description of external function parameters. * * @return external_function_parameters */ public static function search_cohorts_parameters() { $query = new external_value( PARAM_RAW, 'Query string' ); $includes = new external_value( PARAM_ALPHA, 'What other contexts to fetch the frameworks from. (all, parents, self)', VALUE_DEFAULT, 'parents' ); $limitfrom = new external_value( PARAM_INT, 'limitfrom we are fetching the records from', VALUE_DEFAULT, 0 ); $limitnum = new external_value( PARAM_INT, 'Number of records to fetch', VALUE_DEFAULT, 25 ); return new external_function_parameters(array( 'query' => $query, 'context' => self::get_context_parameters(), 'includes' => $includes, 'limitfrom' => $limitfrom, 'limitnum' => $limitnum )); } /** * Search cohorts. * * @param string $query * @param array $context * @param string $includes * @param int $limitfrom * @param int $limitnum * @return array */ public static function search_cohorts($query, $context, $includes = 'parents', $limitfrom = 0, $limitnum = 25) { global $CFG; require_once($CFG->dirroot . '/cohort/lib.php'); $params = self::validate_parameters(self::search_cohorts_parameters(), array( 'query' => $query, 'context' => $context, 'includes' => $includes, 'limitfrom' => $limitfrom, 'limitnum' => $limitnum, )); $query = $params['query']; $includes = $params['includes']; $context = self::get_context_from_params($params['context']); $limitfrom = $params['limitfrom']; $limitnum = $params['limitnum']; self::validate_context($context); $manager = has_capability('moodle/cohort:manage', $context); if (!$manager) { require_capability('moodle/cohort:view', $context); } // TODO Make this more efficient. if ($includes == 'self') { $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query); $results = $results['cohorts']; } else if ($includes == 'parents') { $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query); $results = $results['cohorts']; if (!$context instanceof context_system) { $results = array_merge($results, cohort_get_available_cohorts($context, COHORT_ALL, $limitfrom, $limitnum, $query)); } } else if ($includes == 'all') { $results = cohort_get_all_cohorts($limitfrom, $limitnum, $query); $results = $results['cohorts']; } else { throw new coding_exception('Invalid parameter value for \'includes\'.'); } $cohorts = array();
> foreach ($results as $key => $cohort) { > if (!empty($results)) { $cohortcontext = context::instance_by_id($cohort->contextid); > $cohortids = array_keys($results); > $customfieldsdata = self::get_custom_fields_data($cohortids); // Only return theme when $CFG->allowcohortthemes is enabled. > } if (!empty($cohort->theme) && empty($CFG->allowcohortthemes)) { >
$cohort->theme = null; } if (!isset($cohort->description)) { $cohort->description = ''; } if (!isset($cohort->descriptionformat)) { $cohort->descriptionformat = FORMAT_PLAIN; } list($cohort->description, $cohort->descriptionformat) =
< external_format_text($cohort->description, $cohort->descriptionformat, < $cohortcontext->id, 'cohort', 'description', $cohort->id);
> \core_external\util::format_text($cohort->description, $cohort->descriptionformat, > $cohortcontext, 'cohort', 'description', $cohort->id); > > $cohort->customfields = !empty($customfieldsdata[$cohort->id]) ? $customfieldsdata[$cohort->id] : [];
$cohorts[$key] = $cohort; } return array('cohorts' => $cohorts); } /** * Returns description of external function result value. *
< * @return external_description
> * @return \core_external\external_description
*/ public static function search_cohorts_returns() { return new external_single_structure(array( 'cohorts' => new external_multiple_structure( new external_single_structure(array( 'id' => new external_value(PARAM_INT, 'ID of the cohort'), 'name' => new external_value(PARAM_RAW, 'cohort name'), 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'), 'description' => new external_value(PARAM_RAW, 'cohort description'), 'descriptionformat' => new external_format_value('description'), 'visible' => new external_value(PARAM_BOOL, 'cohort visible'), 'theme' => new external_value(PARAM_THEME, 'cohort theme', VALUE_OPTIONAL),
> 'customfields' => self::build_custom_fields_returns_structure(),
)) ) )); } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.5 */ public static function update_cohorts_parameters() { return new external_function_parameters( array( 'cohorts' => new external_multiple_structure( new external_single_structure( array( 'id' => new external_value(PARAM_INT, 'ID of the cohort'), 'categorytype' => new external_single_structure( array( 'type' => new external_value(PARAM_TEXT, 'the name of the field: id (numeric value of course category id) or idnumber (alphanumeric value of idnumber course category) or system (value ignored)'), 'value' => new external_value(PARAM_RAW, 'the value of the categorytype') ) ), 'name' => new external_value(PARAM_RAW, 'cohort name'), 'idnumber' => new external_value(PARAM_RAW, 'cohort idnumber'), 'description' => new external_value(PARAM_RAW, 'cohort description', VALUE_OPTIONAL), 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT), 'visible' => new external_value(PARAM_BOOL, 'cohort visible', VALUE_OPTIONAL), 'theme' => new external_value(PARAM_THEME, 'the cohort theme. The allowcohortthemes setting must be enabled on Moodle', VALUE_OPTIONAL ),
> 'customfields' => self::build_custom_fields_parameters_structure(),
) ) ) ) ); } /** * Update cohorts * * @param array $cohorts * @return null * @since Moodle 2.5 */ public static function update_cohorts($cohorts) { global $CFG, $DB; require_once("$CFG->dirroot/cohort/lib.php"); $params = self::validate_parameters(self::update_cohorts_parameters(), array('cohorts' => $cohorts)); $availablethemes = cohort_get_list_of_themes(); $transaction = $DB->start_delegated_transaction(); $syscontext = context_system::instance(); foreach ($params['cohorts'] as $cohort) { $cohort = (object) $cohort; if (trim($cohort->name) == '') { throw new invalid_parameter_exception('Invalid cohort name'); } $oldcohort = $DB->get_record('cohort', array('id' => $cohort->id), '*', MUST_EXIST); $oldcontext = context::instance_by_id($oldcohort->contextid, MUST_EXIST); require_capability('moodle/cohort:manage', $oldcontext); // Category type (context id). $categorytype = $cohort->categorytype; if (!in_array($categorytype['type'], array('idnumber', 'id', 'system'))) { throw new invalid_parameter_exception('category type must be id, idnumber or system:' . $categorytype['type']); } if ($categorytype['type'] === 'system') { $cohort->contextid = $syscontext->id; } else if ($catid = $DB->get_field('course_categories', 'id', array($categorytype['type'] => $categorytype['value']))) { $cohort->contextid = $DB->get_field('context', 'id', array('instanceid' => $catid, 'contextlevel' => CONTEXT_COURSECAT)); } else { throw new invalid_parameter_exception('category not exists: category='.$categorytype['value']); } if ($cohort->contextid != $oldcohort->contextid) { $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { throw new invalid_parameter_exception('Invalid context'); } self::validate_context($context); require_capability('moodle/cohort:manage', $context); } // Make sure theme is valid. if (!empty($cohort->theme) && !empty($CFG->allowcohortthemes)) { if (empty($availablethemes[$cohort->theme])) { $debuginfo = 'The following cohort theme is not installed on this site: '.$cohort->theme; throw new moodle_exception('errorinvalidparam', 'webservice', '', 'theme', $debuginfo); } } if (!empty($cohort->description)) {
< $cohort->descriptionformat = external_validate_format($cohort->descriptionformat);
> $cohort->descriptionformat = util::validate_format($cohort->descriptionformat); > } > > // Custom fields. > if (!empty($cohort->customfields)) { > foreach ($cohort->customfields as $field) { > $fieldname = self::build_custom_field_name($field['shortname']); > $cohort->{$fieldname} = $field['value']; > } > unset($cohort->customfields);
} cohort_update_cohort($cohort); } $transaction->allow_commit(); return null; } /** * Returns description of method result value * * @return null * @since Moodle 2.5 */ public static function update_cohorts_returns() { return null; } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.5 */ public static function add_cohort_members_parameters() { return new external_function_parameters ( array( 'members' => new external_multiple_structure ( new external_single_structure ( array ( 'cohorttype' => new external_single_structure ( array( 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the field: id (numeric value of cohortid) or idnumber (alphanumeric value of idnumber) '), 'value' => new external_value(PARAM_RAW, 'The value of the cohort') ) ), 'usertype' => new external_single_structure ( array( 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the field: id (numeric value of id) or username (alphanumeric value of username) '), 'value' => new external_value(PARAM_RAW, 'The value of the cohort') ) ) ) ) ) ) ); } /** * Add cohort members * * @param array $members of arrays with keys userid, cohortid * @since Moodle 2.5 */ public static function add_cohort_members($members) { global $CFG, $DB; require_once($CFG->dirroot."/cohort/lib.php"); $params = self::validate_parameters(self::add_cohort_members_parameters(), array('members' => $members)); $transaction = $DB->start_delegated_transaction(); $warnings = array(); foreach ($params['members'] as $member) { // Cohort parameters. $cohorttype = $member['cohorttype']; $cohortparam = array($cohorttype['type'] => $cohorttype['value']); // User parameters. $usertype = $member['usertype']; $userparam = array($usertype['type'] => $usertype['value']); try { // Check parameters. if ($cohorttype['type'] != 'id' && $cohorttype['type'] != 'idnumber') { $warning = array(); $warning['warningcode'] = '1'; $warning['message'] = 'invalid parameter: cohortype='.$cohorttype['type']; $warnings[] = $warning; continue; } if ($usertype['type'] != 'id' && $usertype['type'] != 'username') { $warning = array(); $warning['warningcode'] = '1'; $warning['message'] = 'invalid parameter: usertype='.$usertype['type']; $warnings[] = $warning; continue; } // Extract parameters. if (!$cohortid = $DB->get_field('cohort', 'id', $cohortparam)) { $warning = array(); $warning['warningcode'] = '2'; $warning['message'] = 'cohort '.$cohorttype['type'].'='.$cohorttype['value'].' not exists'; $warnings[] = $warning; continue; } if (!$userid = $DB->get_field('user', 'id', array_merge($userparam, array('deleted' => 0, 'mnethostid' => $CFG->mnet_localhost_id)))) { $warning = array(); $warning['warningcode'] = '2'; $warning['message'] = 'user '.$usertype['type'].'='.$usertype['value'].' not exists'; $warnings[] = $warning; continue; } if ($DB->record_exists('cohort_members', array('cohortid' => $cohortid, 'userid' => $userid))) { $warning = array(); $warning['warningcode'] = '3'; $warning['message'] = 'record already exists: cohort('.$cohorttype['type'].'='.$cohorttype['value'].' '. $usertype['type'].'='.$usertype['value'].')'; $warnings[] = $warning; continue; } $cohort = $DB->get_record('cohort', array('id'=>$cohortid), '*', MUST_EXIST); $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { $warning = array(); $warning['warningcode'] = '1'; $warning['message'] = 'Invalid context: '.$context->contextlevel; $warnings[] = $warning; continue; } self::validate_context($context); } catch (Exception $e) { throw new moodle_exception('Error', 'cohort', '', $e->getMessage()); } if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) { throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', ''); } cohort_add_member($cohortid, $userid); } $transaction->allow_commit(); // Return. $result = array(); $result['warnings'] = $warnings; return $result; } /** * Returns description of method result value * * @return null * @since Moodle 2.5 */ public static function add_cohort_members_returns() { return new external_single_structure( array( 'warnings' => new external_warnings() ) ); } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.5 */ public static function delete_cohort_members_parameters() { return new external_function_parameters( array( 'members' => new external_multiple_structure( new external_single_structure( array( 'cohortid' => new external_value(PARAM_INT, 'cohort record id'), 'userid' => new external_value(PARAM_INT, 'user id'), ) ) ) ) ); } /** * Delete cohort members * * @param array $members of arrays with keys userid, cohortid * @since Moodle 2.5 */ public static function delete_cohort_members($members) { global $CFG, $DB; require_once("$CFG->dirroot/cohort/lib.php"); // Validate parameters. $params = self::validate_parameters(self::delete_cohort_members_parameters(), array('members' => $members)); $transaction = $DB->start_delegated_transaction(); foreach ($params['members'] as $member) { $cohortid = $member['cohortid']; $userid = $member['userid']; $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST); $user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0, 'mnethostid' => $CFG->mnet_localhost_id), '*', MUST_EXIST); // Now security checks. $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { throw new invalid_parameter_exception('Invalid context'); } self::validate_context($context); if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:assign'), $context)) { throw new required_capability_exception($context, 'moodle/cohort:assign', 'nopermissions', ''); } cohort_remove_member($cohort->id, $user->id); } $transaction->allow_commit(); } /** * Returns description of method result value * * @return null * @since Moodle 2.5 */ public static function delete_cohort_members_returns() { return null; } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.5 */ public static function get_cohort_members_parameters() { return new external_function_parameters( array( 'cohortids' => new external_multiple_structure(new external_value(PARAM_INT, 'Cohort ID')), ) ); } /** * Return all members for a cohort * * @param array $cohortids array of cohort ids * @return array with cohort id keys containing arrays of user ids * @since Moodle 2.5 */ public static function get_cohort_members($cohortids) { global $DB; $params = self::validate_parameters(self::get_cohort_members_parameters(), array('cohortids' => $cohortids)); $members = array(); foreach ($params['cohortids'] as $cohortid) { // Validate params. $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST); // Now security checks. $context = context::instance_by_id($cohort->contextid, MUST_EXIST); if ($context->contextlevel != CONTEXT_COURSECAT and $context->contextlevel != CONTEXT_SYSTEM) { throw new invalid_parameter_exception('Invalid context'); } self::validate_context($context); if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), $context)) { throw new required_capability_exception($context, 'moodle/cohort:view', 'nopermissions', ''); } $cohortmembers = $DB->get_records_sql("SELECT u.id FROM {user} u, {cohort_members} cm WHERE u.id = cm.userid AND cm.cohortid = ? ORDER BY lastname ASC, firstname ASC", array($cohort->id)); $members[] = array('cohortid' => $cohortid, 'userids' => array_keys($cohortmembers)); } return $members; } /** * Returns description of method result value *
< * @return external_description
> * @return \core_external\external_description
* @since Moodle 2.5 */ public static function get_cohort_members_returns() { return new external_multiple_structure( new external_single_structure( array( 'cohortid' => new external_value(PARAM_INT, 'cohort record id'), 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')), ) ) );
> } } > } > /** > * Builds a structure for custom fields parameters. > * > * @return \core_external\external_multiple_structure > */ > protected static function build_custom_fields_parameters_structure(): external_multiple_structure { > return new external_multiple_structure( > new external_single_structure( > array( > 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'The shortname of the custom field'), > 'value' => new external_value(PARAM_RAW, 'The value of the custom field'), > ) > ), 'Custom fields for the cohort', VALUE_OPTIONAL > ); > } > > /** > * Builds a structure for custom fields returns. > * > * @return \core_external\external_multiple_structure > */ > protected static function build_custom_fields_returns_structure(): external_multiple_structure { > return new external_multiple_structure( > new external_single_structure( > array( > 'name' => new external_value(PARAM_RAW, 'The name of the custom field'), > 'shortname' => new external_value(PARAM_RAW, > 'The shortname of the custom field - to be able to build the field class in the code'), > 'type' => new external_value(PARAM_ALPHANUMEXT, > 'The type of the custom field - text field, checkbox...'), > 'valueraw' => new external_value(PARAM_RAW, 'The raw value of the custom field'), > 'value' => new external_value(PARAM_RAW, 'The value of the custom field'), > ) > ), 'Custom fields', VALUE_OPTIONAL > ); > } > > /** > * Returns custom fields data for provided cohorts. > * > * @param array $cohortids a list of cohort IDs to provide data for. > * @return array > */ > protected static function get_custom_fields_data(array $cohortids): array { > $result = []; > > $customfieldsdata = cohort_get_custom_fields_data($cohortids); > > foreach ($customfieldsdata as $cohortid => $fieldcontrollers) { > foreach ($fieldcontrollers as $fieldcontroller) { > $result[$cohortid][] = [ > 'type' => $fieldcontroller->get_field()->get('type'), > 'value' => $fieldcontroller->export_value(), > 'valueraw' => $fieldcontroller->get_value(), > 'name' => $fieldcontroller->get_field()->get('name'), > 'shortname' => $fieldcontroller->get_field()->get('shortname'), > ]; > } > } > > return $result; > } > > /** > * Builds a suitable name of a custom field for a custom field handler based on provided shortname. > * > * @param string $shortname shortname to use. > * @return string > */ > protected static function build_custom_field_name(string $shortname): string { > return 'customfield_' . $shortname;