group/externallib.php

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