Merge branch 'w13_MDL-37782_m25_testtrans' of git://github.com/skodak/moodle
[moodle.git] / 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/>.
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  */
25 defined('MOODLE_INTERNAL') || die();
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;
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     }
59     $cohort->id = $DB->insert_record('cohort', $cohort);
61     events_trigger('cohort_added', $cohort);
63     return $cohort->id;
64 }
66 /**
67  * Update existing cohort.
68  * @param  stdClass $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);
80     events_trigger('cohort_updated', $cohort);
81 }
83 /**
84  * Delete cohort.
85  * @param  stdClass $cohort
86  * @return void
87  */
88 function cohort_delete_cohort($cohort) {
89     global $DB;
91     if ($cohort->component) {
92         // TODO: add component delete callback
93     }
95     $DB->delete_records('cohort_members', array('cohortid'=>$cohort->id));
96     $DB->delete_records('cohort', array('id'=>$cohort->id));
98     events_trigger('cohort_deleted', $cohort);
99 }
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  stdClass|coursecat $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
112     $oldcontext = context_coursecat::instance($category->id);
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     }
124     $DB->execute($sql, $params);
127 /**
128  * Add 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     if ($DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid))) {
136         // No duplicates!
137         return;
138     }
139     $record = new stdClass();
140     $record->cohortid  = $cohortid;
141     $record->userid    = $userid;
142     $record->timeadded = time();
143     $DB->insert_record('cohort_members', $record);
145     events_trigger('cohort_member_added', (object)array('cohortid'=>$cohortid, 'userid'=>$userid));
148 /**
149  * Remove cohort member
150  * @param  int $cohortid
151  * @param  int $userid
152  * @return void
153  */
154 function cohort_remove_member($cohortid, $userid) {
155     global $DB;
156     $DB->delete_records('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
158     events_trigger('cohort_member_removed', (object)array('cohortid'=>$cohortid, 'userid'=>$userid));
161 /**
162  * Is this user a cohort member?
163  * @param int $cohortid
164  * @param int $userid
165  * @return bool
166  */
167 function cohort_is_member($cohortid, $userid) {
168     global $DB;
170     return $DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
173 /**
174  * Returns list of cohorts from course parent contexts.
175  *
176  * Note: this function does not implement any capability checks,
177  *       it means it may disclose existence of cohorts,
178  *       make sure it is displayed to users with appropriate rights only.
179  *
180  * @param  stdClass $course
181  * @param  bool $onlyenrolled true means include only cohorts with enrolled users
182  * @return array of cohort names with number of enrolled users
183  */
184 function cohort_get_visible_list($course, $onlyenrolled=true) {
185     global $DB;
187     $context = context_course::instance($course->id);
188     list($esql, $params) = get_enrolled_sql($context);
189     list($parentsql, $params2) = $DB->get_in_or_equal($context->get_parent_context_ids(), SQL_PARAMS_NAMED);
190     $params = array_merge($params, $params2);
192     if ($onlyenrolled) {
193         $left = "";
194         $having = "HAVING COUNT(u.id) > 0";
195     } else {
196         $left = "LEFT";
197         $having = "";
198     }
200     $sql = "SELECT c.id, c.name, c.contextid, c.idnumber, COUNT(u.id) AS cnt
201               FROM {cohort} c
202         $left JOIN ({cohort_members} cm
203                    JOIN ($esql) u ON u.id = cm.userid) ON cm.cohortid = c.id
204              WHERE c.contextid $parentsql
205           GROUP BY c.id, c.name, c.contextid, c.idnumber
206            $having
207           ORDER BY c.name, c.idnumber";
209     $cohorts = $DB->get_records_sql($sql, $params);
211     foreach ($cohorts as $cid=>$cohort) {
212         $cohorts[$cid] = format_string($cohort->name, true, array('context'=>$cohort->contextid));
213         if ($cohort->cnt) {
214             $cohorts[$cid] .= ' (' . $cohort->cnt . ')';
215         }
216     }
218     return $cohorts;
221 /**
222  * Get all the cohorts defined in given context.
223  *
224  * @param int $contextid
225  * @param int $page number of the current page
226  * @param int $perpage items per page
227  * @param string $search search string
228  * @return array    Array(totalcohorts => int, cohorts => array, allcohorts => int)
229  */
230 function cohort_get_cohorts($contextid, $page = 0, $perpage = 25, $search = '') {
231     global $DB;
233     // Add some additional sensible conditions
234     $tests = array('contextid = ?');
235     $params = array($contextid);
237     if (!empty($search)) {
238         $conditions = array('name', 'idnumber', 'description');
239         $searchparam = '%' . $DB->sql_like_escape($search) . '%';
240         foreach ($conditions as $key=>$condition) {
241             $conditions[$key] = $DB->sql_like($condition, "?", false);
242             $params[] = $searchparam;
243         }
244         $tests[] = '(' . implode(' OR ', $conditions) . ')';
245     }
246     $wherecondition = implode(' AND ', $tests);
248     $fields = "SELECT *";
249     $countfields = "SELECT COUNT(1)";
250     $sql = " FROM {cohort}
251              WHERE $wherecondition";
252     $order = " ORDER BY name ASC, idnumber ASC";
253     $allcohorts = $DB->count_records('cohort', array('contextid'=>$contextid));
254     $totalcohorts = $DB->count_records_sql($countfields . $sql, $params);
255     $cohorts = $DB->get_records_sql($fields . $sql . $order, $params, $page*$perpage, $perpage);
257     return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts, 'allcohorts'=>$allcohorts);