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