Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

   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   * Create and allocate users to groups
  20   *
  21   * @package    core_group
  22   * @copyright  Matt Clarkson mattc@catalyst.net.nz
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  require_once('../config.php');
  27  require_once ('lib.php');
  28  require_once ('autogroup_form.php');
  29  
  30  if (!defined('AUTOGROUP_MIN_RATIO')) {
  31      define('AUTOGROUP_MIN_RATIO', 0.7); // means minimum member count is 70% in the smallest group
  32  }
  33  
  34  $courseid = required_param('courseid', PARAM_INT);
  35  $PAGE->set_url('/group/autogroup.php', array('courseid' => $courseid));
  36  
  37  if (!$course = $DB->get_record('course', array('id'=>$courseid))) {
  38      throw new \moodle_exception('invalidcourseid');
  39  }
  40  
  41  // Make sure that the user has permissions to manage groups.
  42  require_login($course);
  43  
  44  $context       = context_course::instance($courseid);
  45  require_capability('moodle/course:managegroups', $context);
  46  
  47  $returnurl = $CFG->wwwroot.'/group/index.php?id='.$course->id;
  48  
  49  $strgroups           = get_string('groups');
  50  $strparticipants     = get_string('participants');
  51  $strautocreategroups = get_string('autocreategroups', 'group');
  52  
  53  $PAGE->set_title($strgroups);
  54  $PAGE->set_heading($course->fullname. ': '.$strgroups);
  55  $PAGE->set_pagelayout('admin');
  56  navigation_node::override_active_url(new moodle_url('/group/index.php', array('id' => $courseid)));
  57  
  58  // Print the page and form
  59  $preview = '';
  60  $error = '';
  61  
  62  /// Get applicable roles - used in menus etc later on
  63  $rolenames = role_fix_names(get_profile_roles($context), $context, ROLENAME_BOTH, true);
  64  
  65  /// Create the form
  66  $editform = new autogroup_form(null, array('roles' => $rolenames));
  67  $editform->set_data(array('courseid' => $courseid, 'seed' => time()));
  68  
  69  /// Handle form submission
  70  if ($editform->is_cancelled()) {
  71      redirect($returnurl);
  72  
  73  } elseif ($data = $editform->get_data()) {
  74  
  75      /// Allocate members from the selected role to groups
  76      switch ($data->allocateby) {
  77          case 'no':
  78          case 'random':
  79          case 'lastname':
  80              $orderby = 'lastname, firstname'; break;
  81          case 'firstname':
  82              $orderby = 'firstname, lastname'; break;
  83          case 'idnumber':
  84              $orderby = 'idnumber'; break;
  85          default:
  86              throw new \moodle_exception('unknoworder');
  87      }
  88      $source = array();
  89      if ($data->cohortid) {
  90          $source['cohortid'] = $data->cohortid;
  91      }
  92      if ($data->groupingid) {
  93          $source['groupingid'] = $data->groupingid;
  94      }
  95      if ($data->groupid) {
  96          $source['groupid'] = $data->groupid;
  97      }
  98  
  99      // Display only active users if the option was selected or they do not have the capability to view suspended users.
 100      $onlyactive = !empty($data->includeonlyactiveenrol) || !has_capability('moodle/course:viewsuspendedusers', $context);
 101  
 102      // TODO Does not support custom user profile fields (MDL-70456).
 103      $extrafields = \core_user\fields::get_identity_fields($context, false);
 104      $users = groups_get_potential_members($data->courseid, $data->roleid, $source, $orderby, !empty($data->notingroup),
 105          $onlyactive, $extrafields);
 106      $usercnt = count($users);
 107  
 108      if ($data->allocateby == 'random') {
 109          srand($data->seed);
 110          shuffle($users);
 111      }
 112  
 113      $groups = array();
 114  
 115      // Plan the allocation
 116      if ($data->groupby == 'groups') {
 117          $numgrps    = $data->number;
 118          $userpergrp = floor($usercnt/$numgrps);
 119  
 120      } else { // members
 121          $numgrps    = ceil($usercnt/$data->number);
 122          $userpergrp = $data->number;
 123  
 124          if (!empty($data->nosmallgroups) and $usercnt % $data->number != 0) {
 125              // If there would be one group with a small number of member reduce the number of groups
 126              $missing = $userpergrp * $numgrps - $usercnt;
 127              if ($missing > $userpergrp * (1-AUTOGROUP_MIN_RATIO)) {
 128                  // spread the users from the last small group
 129                  $numgrps--;
 130                  $userpergrp = floor($usercnt/$numgrps);
 131              }
 132          }
 133      }
 134  
 135      // allocate the users - all groups equal count first
 136      for ($i=0; $i<$numgrps; $i++) {
 137          $groups[$i] = array();
 138          $groups[$i]['name']    = groups_parse_name(trim($data->namingscheme), $i);
 139          $groups[$i]['members'] = array();
 140          if ($data->allocateby == 'no') {
 141              continue; // do not allocate users
 142          }
 143          for ($j=0; $j<$userpergrp; $j++) {
 144              if (empty($users)) {
 145                  break 2;
 146              }
 147              $user = array_shift($users);
 148              $groups[$i]['members'][$user->id] = $user;
 149          }
 150      }
 151      // now distribute the rest
 152      if ($data->allocateby != 'no') {
 153          for ($i=0; $i<$numgrps; $i++) {
 154              if (empty($users)) {
 155                  break 1;
 156              }
 157              $user = array_shift($users);
 158              $groups[$i]['members'][$user->id] = $user;
 159          }
 160      }
 161  
 162      if (isset($data->preview)) {
 163          $table = new html_table();
 164          if ($data->allocateby == 'no') {
 165              $table->head  = array(get_string('groupscount', 'group', $numgrps));
 166              $table->size  = array('100%');
 167              $table->align = array('left');
 168              $table->width = '40%';
 169          } else {
 170              $table->head  = array(get_string('groupscount', 'group', $numgrps), get_string('groupmembers', 'group'), get_string('usercounttotal', 'group', $usercnt));
 171              $table->size  = array('20%', '70%', '10%');
 172              $table->align = array('left', 'left', 'center');
 173              $table->width = '90%';
 174          }
 175          $table->data  = array();
 176          $viewfullnames = has_capability('moodle/site:viewfullnames', $context);
 177          foreach ($groups as $group) {
 178              $line = array();
 179              if (groups_get_group_by_name($courseid, $group['name'])) {
 180                  $line[] = '<span class="notifyproblem">'.get_string('groupnameexists', 'group', $group['name']).'</span>';
 181                  $error = get_string('groupnameexists', 'group', $group['name']);
 182              } else {
 183                  $line[] = $group['name'];
 184              }
 185              if ($data->allocateby != 'no') {
 186                  $unames = array();
 187                  foreach ($group['members'] as $user) {
 188                      $fullname = fullname($user, $viewfullnames);
 189                      if ($extrafields) {
 190                          $extrafieldsdisplay = [];
 191                          foreach ($extrafields as $field) {
 192                              $extrafieldsdisplay[] = s($user->{$field});
 193                          }
 194                          $fullname .= ' (' . implode(', ', $extrafieldsdisplay) . ')';
 195                      }
 196  
 197                      $unames[] = $fullname;
 198                  }
 199                  $line[] = implode(', ', $unames);
 200                  $line[] = count($group['members']);
 201              }
 202              $table->data[] = $line;
 203          }
 204  
 205          $preview .= html_writer::table($table);
 206  
 207      } else {
 208          $grouping = null;
 209          $createdgrouping = null;
 210          $createdgroups = array();
 211          $failed = false;
 212  
 213          // prepare grouping
 214          if (!empty($data->grouping)) {
 215              if ($data->grouping < 0) {
 216                  $grouping = new stdClass();
 217                  $grouping->courseid = $COURSE->id;
 218                  $grouping->name     = trim($data->groupingname);
 219                  $grouping->id = groups_create_grouping($grouping);
 220                  $createdgrouping = $grouping->id;
 221              } else {
 222                  $grouping = groups_get_grouping($data->grouping);
 223              }
 224          }
 225  
 226          // Save the groups data
 227          foreach ($groups as $key=>$group) {
 228              if (groups_get_group_by_name($courseid, $group['name'])) {
 229                  $error = get_string('groupnameexists', 'group', $group['name']);
 230                  $failed = true;
 231                  break;
 232              }
 233              $newgroup = new stdClass();
 234              $newgroup->courseid = $data->courseid;
 235              $newgroup->name     = $group['name'];
 236              $newgroup->enablemessaging = $data->enablemessaging ?? 0;
 237              $groupid = groups_create_group($newgroup);
 238              $createdgroups[] = $groupid;
 239              foreach($group['members'] as $user) {
 240                  groups_add_member($groupid, $user->id);
 241              }
 242              if ($grouping) {
 243                  // Ask this function not to invalidate the cache, we'll do that manually once at the end.
 244                  groups_assign_grouping($grouping->id, $groupid, null, false);
 245              }
 246          }
 247  
 248          // Invalidate the course groups cache seeing as we've changed it.
 249          cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($courseid));
 250  
 251          if ($failed) {
 252              foreach ($createdgroups as $groupid) {
 253                  groups_delete_group($groupid);
 254              }
 255              if ($createdgrouping) {
 256                  groups_delete_grouping($createdgrouping);
 257              }
 258          } else {
 259              redirect($returnurl);
 260          }
 261      }
 262  }
 263  
 264  $PAGE->navbar->add($strparticipants, new moodle_url('/user/index.php', array('id'=>$courseid)));
 265  $PAGE->navbar->add($strgroups, new moodle_url('/group/index.php', array('id'=>$courseid)));
 266  $PAGE->navbar->add($strautocreategroups);
 267  
 268  echo $OUTPUT->header();
 269  echo $OUTPUT->heading($strautocreategroups);
 270  
 271  if ($error != '') {
 272      echo $OUTPUT->notification($error);
 273  }
 274  
 275  /// Display the form
 276  $editform->display();
 277  
 278  if($preview !== '') {
 279      echo $OUTPUT->heading(get_string('groupspreview', 'group'));
 280  
 281      echo $preview;
 282  }
 283  
 284  echo $OUTPUT->footer();