cohort/lib.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  * Cohort related management functions, this file needs to be included manually.
  19  *
  20  * @package    core_cohort
  21  * @copyright  2010 Petr Skoda  {@link http://skodak.org}
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * Add new cohort.
  29  *
  30  * @param  stdClass $cohort
  31  * @return int new cohort id
  32  */
  33 function cohort_add_cohort($cohort) {
  34     global $DB;
  35
  36     if (!isset($cohort->name)) {
  37         throw new coding_exception('Missing cohort name in cohort_add_cohort().');
  38     }
  39     if (!isset($cohort->idnumber)) {
  40         $cohort->idnumber = NULL;
  41     }
  42     if (!isset($cohort->description)) {
  43         $cohort->description = '';
  44     }
  45     if (!isset($cohort->descriptionformat)) {
  46         $cohort->descriptionformat = FORMAT_HTML;
  47     }
  48     if (empty($cohort->component)) {
  49         $cohort->component = '';
  50     }
  51     if (!isset($cohort->timecreated)) {
  52         $cohort->timecreated = time();
  53     }
  54     if (!isset($cohort->timemodified)) {
  55         $cohort->timemodified = $cohort->timecreated;
  56     }
  57
  58     $cohort->id = $DB->insert_record('cohort', $cohort);
  59
  60     $event = \core\event\cohort_created::create(array(
  61         'context' => context::instance_by_id($cohort->contextid),
  62         'objectid' => $cohort->id,
  63     ));
  64     $event->add_record_snapshot('cohort', $cohort);
  65     $event->trigger();
  66
  67     return $cohort->id;
  68 }
  69
  70 /**
  71  * Update existing cohort.
  72  * @param  stdClass $cohort
  73  * @return void
  74  */
  75 function cohort_update_cohort($cohort) {
  76     global $DB;
  77     if (property_exists($cohort, 'component') and empty($cohort->component)) {
  78         // prevent NULLs
  79         $cohort->component = '';
  80     }
  81     $cohort->timemodified = time();
  82     $DB->update_record('cohort', $cohort);
  83
  84     $event = \core\event\cohort_updated::create(array(
  85         'context' => context::instance_by_id($cohort->contextid),
  86         'objectid' => $cohort->id,
  87     ));
  88     $event->add_record_snapshot('cohort', $cohort);
  89     $event->trigger();
  90 }
  91
  92 /**
  93  * Delete cohort.
  94  * @param  stdClass $cohort
  95  * @return void
  96  */
  97 function cohort_delete_cohort($cohort) {
  98     global $DB;
  99
 100     if ($cohort->component) {
 101         // TODO: add component delete callback
 102     }
 103
 104     $DB->delete_records('cohort_members', array('cohortid'=>$cohort->id));
 105     $DB->delete_records('cohort', array('id'=>$cohort->id));
 106
 107     $event = \core\event\cohort_deleted::create(array(
 108         'context' => context::instance_by_id($cohort->contextid),
 109         'objectid' => $cohort->id,
 110     ));
 111     $event->add_record_snapshot('cohort', $cohort);
 112     $event->trigger();
 113 }
 114
 115 /**
 116  * Somehow deal with cohorts when deleting course category,
 117  * we can not just delete them because they might be used in enrol
 118  * plugins or referenced in external systems.
 119  * @param  stdClass|coursecat $category
 120  * @return void
 121  */
 122 function cohort_delete_category($category) {
 123     global $DB;
 124     // TODO: make sure that cohorts are really, really not used anywhere and delete, for now just move to parent or system context
 125
 126     $oldcontext = context_coursecat::instance($category->id);
 127
 128     if ($category->parent and $parent = $DB->get_record('course_categories', array('id'=>$category->parent))) {
 129         $parentcontext = context_coursecat::instance($parent->id);
 130         $sql = "UPDATE {cohort} SET contextid = :newcontext WHERE contextid = :oldcontext";
 131         $params = array('oldcontext'=>$oldcontext->id, 'newcontext'=>$parentcontext->id);
 132     } else {
 133         $syscontext = context_system::instance();
 134         $sql = "UPDATE {cohort} SET contextid = :newcontext WHERE contextid = :oldcontext";
 135         $params = array('oldcontext'=>$oldcontext->id, 'newcontext'=>$syscontext->id);
 136     }
 137
 138     $DB->execute($sql, $params);
 139 }
 140
 141 /**
 142  * Add cohort member
 143  * @param  int $cohortid
 144  * @param  int $userid
 145  * @return void
 146  */
 147 function cohort_add_member($cohortid, $userid) {
 148     global $DB;
 149     if ($DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid))) {
 150         // No duplicates!
 151         return;
 152     }
 153     $record = new stdClass();
 154     $record->cohortid  = $cohortid;
 155     $record->userid    = $userid;
 156     $record->timeadded = time();
 157     $DB->insert_record('cohort_members', $record);
 158
 159     $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
 160
 161     $event = \core\event\cohort_member_added::create(array(
 162         'context' => context::instance_by_id($cohort->contextid),
 163         'objectid' => $cohortid,
 164         'relateduserid' => $userid,
 165     ));
 166     $event->add_record_snapshot('cohort', $cohort);
 167     $event->trigger();
 168 }
 169
 170 /**
 171  * Remove cohort member
 172  * @param  int $cohortid
 173  * @param  int $userid
 174  * @return void
 175  */
 176 function cohort_remove_member($cohortid, $userid) {
 177     global $DB;
 178     $DB->delete_records('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
 179
 180     $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
 181
 182     $event = \core\event\cohort_member_removed::create(array(
 183         'context' => context::instance_by_id($cohort->contextid),
 184         'objectid' => $cohortid,
 185         'relateduserid' => $userid,
 186     ));
 187     $event->add_record_snapshot('cohort', $cohort);
 188     $event->trigger();
 189 }
 190
 191 /**
 192  * Is this user a cohort member?
 193  * @param int $cohortid
 194  * @param int $userid
 195  * @return bool
 196  */
 197 function cohort_is_member($cohortid, $userid) {
 198     global $DB;
 199
 200     return $DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
 201 }
 202
 203 /**
 204  * Returns list of cohorts from course parent contexts.
 205  *
 206  * Note: this function does not implement any capability checks,
 207  *       it means it may disclose existence of cohorts,
 208  *       make sure it is displayed to users with appropriate rights only.
 209  *
 210  * @param  stdClass $course
 211  * @param  bool $onlyenrolled true means include only cohorts with enrolled users
 212  * @return array of cohort names with number of enrolled users
 213  */
 214 function cohort_get_visible_list($course, $onlyenrolled=true) {
 215     global $DB;
 216
 217     $context = context_course::instance($course->id);
 218     list($esql, $params) = get_enrolled_sql($context);
 219     list($parentsql, $params2) = $DB->get_in_or_equal($context->get_parent_context_ids(), SQL_PARAMS_NAMED);
 220     $params = array_merge($params, $params2);
 221
 222     if ($onlyenrolled) {
 223         $left = "";
 224         $having = "HAVING COUNT(u.id) > 0";
 225     } else {
 226         $left = "LEFT";
 227         $having = "";
 228     }
 229
 230     $sql = "SELECT c.id, c.name, c.contextid, c.idnumber, COUNT(u.id) AS cnt
 231               FROM {cohort} c
 232         $left JOIN ({cohort_members} cm
 233                    JOIN ($esql) u ON u.id = cm.userid) ON cm.cohortid = c.id
 234              WHERE c.contextid $parentsql
 235           GROUP BY c.id, c.name, c.contextid, c.idnumber
 236            $having
 237           ORDER BY c.name, c.idnumber";
 238
 239     $cohorts = $DB->get_records_sql($sql, $params);
 240
 241     foreach ($cohorts as $cid=>$cohort) {
 242         $cohorts[$cid] = format_string($cohort->name, true, array('context'=>$cohort->contextid));
 243         if ($cohort->cnt) {
 244             $cohorts[$cid] .= ' (' . $cohort->cnt . ')';
 245         }
 246     }
 247
 248     return $cohorts;
 249 }
 250
 251 /**
 252  * Get all the cohorts defined in given context.
 253  *
 254  * @param int $contextid
 255  * @param int $page number of the current page
 256  * @param int $perpage items per page
 257  * @param string $search search string
 258  * @return array    Array(totalcohorts => int, cohorts => array, allcohorts => int)
 259  */
 260 function cohort_get_cohorts($contextid, $page = 0, $perpage = 25, $search = '') {
 261     global $DB;
 262
 263     // Add some additional sensible conditions
 264     $tests = array('contextid = ?');
 265     $params = array($contextid);
 266
 267     if (!empty($search)) {
 268         $conditions = array('name', 'idnumber', 'description');
 269         $searchparam = '%' . $DB->sql_like_escape($search) . '%';
 270         foreach ($conditions as $key=>$condition) {
 271             $conditions[$key] = $DB->sql_like($condition, "?", false);
 272             $params[] = $searchparam;
 273         }
 274         $tests[] = '(' . implode(' OR ', $conditions) . ')';
 275     }
 276     $wherecondition = implode(' AND ', $tests);
 277
 278     $fields = "SELECT *";
 279     $countfields = "SELECT COUNT(1)";
 280     $sql = " FROM {cohort}
 281              WHERE $wherecondition";
 282     $order = " ORDER BY name ASC, idnumber ASC";
 283     $allcohorts = $DB->count_records('cohort', array('contextid'=>$contextid));
 284     $totalcohorts = $DB->count_records_sql($countfields . $sql, $params);
 285     $cohorts = $DB->get_records_sql($fields . $sql . $order, $params, $page*$perpage, $perpage);
 286
 287     return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts, 'allcohorts'=>$allcohorts);
 288 }