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  object $cohort
  31  * @return int
  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         // sql_empty() does not belong here, this crazy Oracle hack is implemented in insert_record()!
  44         $cohort->description = '';
  45     }
  46     if (!isset($cohort->descriptionformat)) {
  47         $cohort->descriptionformat = FORMAT_HTML;
  48     }
  49     if (empty($cohort->component)) {
  50         $cohort->component = '';
  51     }
  52     if (!isset($cohort->timecreated)) {
  53         $cohort->timecreated = time();
  54     }
  55     if (!isset($cohort->timemodified)) {
  56         $cohort->timemodified = $cohort->timecreated;
  57     }
  58
  59     $cohort->id = $DB->insert_record('cohort', $cohort);
  60
  61     events_trigger('cohort_added', $cohort);
  62
  63     return $cohort->id;
  64 }
  65
  66 /**
  67  * Update existing cohort.
  68  * @param  object $cohort
  69  * @return void
  70  */
  71 function cohort_update_cohort($cohort) {
  72     global $DB;
  73     if (property_exists($cohort, 'component') and empty($cohort->component)) {
  74         // prevent NULLs
  75         $cohort->component = '';
  76     }
  77     $cohort->timemodified = time();
  78     $DB->update_record('cohort', $cohort);
  79
  80     events_trigger('cohort_updated', $cohort);
  81 }
  82
  83 /**
  84  * Delete cohort.
  85  * @param  object $cohort
  86  * @return void
  87  */
  88 function cohort_delete_cohort($cohort) {
  89     global $DB;
  90
  91     if ($cohort->component) {
  92         // TODO: add component delete callback
  93     }
  94
  95     $DB->delete_records('cohort_members', array('cohortid'=>$cohort->id));
  96     $DB->delete_records('cohort', array('id'=>$cohort->id));
  97
  98     events_trigger('cohort_deleted', $cohort);
  99 }
 100
 101 /**
 102  * Somehow deal with cohorts when deleting course category,
 103  * we can not just delete them because they might be used in enrol
 104  * plugins or referenced in external systems.
 105  * @param  object $category
 106  * @return void
 107  */
 108 function cohort_delete_category($category) {
 109     global $DB;
 110     // TODO: make sure that cohorts are really, really not used anywhere and delete, for now just move to parent or system context
 111
 112     $oldcontext = context_coursecat::instance($category->id);
 113
 114     if ($category->parent and $parent = $DB->get_record('course_categories', array('id'=>$category->parent))) {
 115         $parentcontext = context_coursecat::instance($parent->id);
 116         $sql = "UPDATE {cohort} SET contextid = :newcontext WHERE contextid = :oldcontext";
 117         $params = array('oldcontext'=>$oldcontext->id, 'newcontext'=>$parentcontext->id);
 118     } else {
 119         $syscontext = context_system::instance();
 120         $sql = "UPDATE {cohort} SET contextid = :newcontext WHERE contextid = :oldcontext";
 121         $params = array('oldcontext'=>$oldcontext->id, 'newcontext'=>$syscontext->id);
 122     }
 123
 124     $DB->execute($sql, $params);
 125 }
 126
 127 /**
 128  * Remove cohort member
 129  * @param  int $cohortid
 130  * @param  int $userid
 131  * @return void
 132  */
 133 function cohort_add_member($cohortid, $userid) {
 134     global $DB;
 135     $record = new stdClass();
 136     $record->cohortid  = $cohortid;
 137     $record->userid    = $userid;
 138     $record->timeadded = time();
 139     $DB->insert_record('cohort_members', $record);
 140
 141     events_trigger('cohort_member_added', (object)array('cohortid'=>$cohortid, 'userid'=>$userid));
 142 }
 143
 144 /**
 145  * Add cohort member
 146  * @param  int $cohortid
 147  * @param  int $userid
 148  * @return void
 149  */
 150 function cohort_remove_member($cohortid, $userid) {
 151     global $DB;
 152     $DB->delete_records('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
 153
 154     events_trigger('cohort_member_removed', (object)array('cohortid'=>$cohortid, 'userid'=>$userid));
 155 }
 156
 157 /**
 158  * Is this user a cohort member?
 159  * @param int $cohortid
 160  * @param int $userid
 161  * @return bool
 162  */
 163 function cohort_is_member($cohortid, $userid) {
 164     global $DB;
 165
 166     return $DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
 167 }
 168
 169 /**
 170  * Returns list of visible cohorts in course.
 171  *
 172  * @param  object $course
 173  * @param  bool $enrolled true means include only cohorts with enrolled users
 174  * @return array
 175  */
 176 function cohort_get_visible_list($course) {
 177     global $DB, $USER;
 178
 179     $context = context_course::instance($course->id);
 180     list($esql, $params) = get_enrolled_sql($context);
 181     $parentsql = get_related_contexts_string($context);
 182
 183     $sql = "SELECT c.id, c.name, c.idnumber, COUNT(u.id) AS cnt
 184               FROM {cohort} c
 185               JOIN {cohort_members} cm ON cm.cohortid = c.id
 186               JOIN ($esql) u ON u.id = cm.userid
 187              WHERE c.contextid $parentsql
 188           GROUP BY c.id, c.name, c.idnumber
 189             HAVING COUNT(u.id) > 0
 190           ORDER BY c.name, c.idnumber";
 191     $params['ctx'] = $context->id;
 192
 193     $cohorts = $DB->get_records_sql($sql, $params);
 194
 195     foreach ($cohorts as $cid=>$cohort) {
 196         $cohorts[$cid] = format_string($cohort->name);
 197         if ($cohort->idnumber) {
 198             $cohorts[$cid] .= ' (' . $cohort->cnt . ')';
 199         }
 200     }
 201
 202     return $cohorts;
 203 }
 204
 205 /**
 206  * Get all the cohorts.
 207  *
 208  * @global moodle_database $DB
 209  * @param int $contextid
 210  * @param int $page number of the current page
 211  * @param int $perpage items per page
 212  * @param string $search search string
 213  * @return array    Array(totalcohorts => int, cohorts => array)
 214  */
 215 function cohort_get_cohorts($contextid, $page = 0, $perpage = 25, $search = '') {
 216     global $DB;
 217
 218     $cohorts = array();
 219
 220     // Add some additional sensible conditions
 221     $tests = array('contextid = ?');
 222     $params = array($contextid);
 223
 224     if (!empty($search)) {
 225         $conditions = array(
 226             'name',
 227             'idnumber',
 228             'description',
 229         );
 230         $searchparam = '%' . $search . '%';
 231         foreach ($conditions as $key=>$condition) {
 232             $conditions[$key] = $DB->sql_like($condition,"?", false);
 233             $params[] = $searchparam;
 234         }
 235         $tests[] = '(' . implode(' OR ', $conditions) . ')';
 236     }
 237     $wherecondition = implode(' AND ', $tests);
 238
 239     $fields = 'SELECT *';
 240     $countfields = 'SELECT COUNT(1)';
 241     $sql = " FROM {cohort}
 242              WHERE $wherecondition";
 243     $order = ' ORDER BY name ASC';
 244     $totalcohorts = $DB->count_records_sql($countfields . $sql, $params);
 245     $cohorts = $DB->get_records_sql($fields . $sql . $order, $params, $page*$perpage, $perpage);
 246
 247     return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts);
 248 }