MDL-53026 cohorts: edit names and idnumbers in place
[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 define('COHORT_ALL', 0);
28 define('COHORT_COUNT_MEMBERS', 1);
29 define('COHORT_COUNT_ENROLLED_MEMBERS', 3);
30 define('COHORT_WITH_MEMBERS_ONLY', 5);
31 define('COHORT_WITH_ENROLLED_MEMBERS_ONLY', 17);
32 define('COHORT_WITH_NOTENROLLED_MEMBERS_ONLY', 23);
34 /**
35  * Add new cohort.
36  *
37  * @param  stdClass $cohort
38  * @return int new cohort id
39  */
40 function cohort_add_cohort($cohort) {
41     global $DB;
43     if (!isset($cohort->name)) {
44         throw new coding_exception('Missing cohort name in cohort_add_cohort().');
45     }
46     if (!isset($cohort->idnumber)) {
47         $cohort->idnumber = NULL;
48     }
49     if (!isset($cohort->description)) {
50         $cohort->description = '';
51     }
52     if (!isset($cohort->descriptionformat)) {
53         $cohort->descriptionformat = FORMAT_HTML;
54     }
55     if (!isset($cohort->visible)) {
56         $cohort->visible = 1;
57     }
58     if (empty($cohort->component)) {
59         $cohort->component = '';
60     }
61     if (!isset($cohort->timecreated)) {
62         $cohort->timecreated = time();
63     }
64     if (!isset($cohort->timemodified)) {
65         $cohort->timemodified = $cohort->timecreated;
66     }
68     $cohort->id = $DB->insert_record('cohort', $cohort);
70     $event = \core\event\cohort_created::create(array(
71         'context' => context::instance_by_id($cohort->contextid),
72         'objectid' => $cohort->id,
73     ));
74     $event->add_record_snapshot('cohort', $cohort);
75     $event->trigger();
77     return $cohort->id;
78 }
80 /**
81  * Update existing cohort.
82  * @param  stdClass $cohort
83  * @return void
84  */
85 function cohort_update_cohort($cohort) {
86     global $DB;
87     if (property_exists($cohort, 'component') and empty($cohort->component)) {
88         // prevent NULLs
89         $cohort->component = '';
90     }
91     $cohort->timemodified = time();
92     $DB->update_record('cohort', $cohort);
94     $event = \core\event\cohort_updated::create(array(
95         'context' => context::instance_by_id($cohort->contextid),
96         'objectid' => $cohort->id,
97     ));
98     $event->trigger();
99 }
101 /**
102  * Delete cohort.
103  * @param  stdClass $cohort
104  * @return void
105  */
106 function cohort_delete_cohort($cohort) {
107     global $DB;
109     if ($cohort->component) {
110         // TODO: add component delete callback
111     }
113     $DB->delete_records('cohort_members', array('cohortid'=>$cohort->id));
114     $DB->delete_records('cohort', array('id'=>$cohort->id));
116     $event = \core\event\cohort_deleted::create(array(
117         'context' => context::instance_by_id($cohort->contextid),
118         'objectid' => $cohort->id,
119     ));
120     $event->add_record_snapshot('cohort', $cohort);
121     $event->trigger();
124 /**
125  * Somehow deal with cohorts when deleting course category,
126  * we can not just delete them because they might be used in enrol
127  * plugins or referenced in external systems.
128  * @param  stdClass|coursecat $category
129  * @return void
130  */
131 function cohort_delete_category($category) {
132     global $DB;
133     // TODO: make sure that cohorts are really, really not used anywhere and delete, for now just move to parent or system context
135     $oldcontext = context_coursecat::instance($category->id);
137     if ($category->parent and $parent = $DB->get_record('course_categories', array('id'=>$category->parent))) {
138         $parentcontext = context_coursecat::instance($parent->id);
139         $sql = "UPDATE {cohort} SET contextid = :newcontext WHERE contextid = :oldcontext";
140         $params = array('oldcontext'=>$oldcontext->id, 'newcontext'=>$parentcontext->id);
141     } else {
142         $syscontext = context_system::instance();
143         $sql = "UPDATE {cohort} SET contextid = :newcontext WHERE contextid = :oldcontext";
144         $params = array('oldcontext'=>$oldcontext->id, 'newcontext'=>$syscontext->id);
145     }
147     $DB->execute($sql, $params);
150 /**
151  * Add cohort member
152  * @param  int $cohortid
153  * @param  int $userid
154  * @return void
155  */
156 function cohort_add_member($cohortid, $userid) {
157     global $DB;
158     if ($DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid))) {
159         // No duplicates!
160         return;
161     }
162     $record = new stdClass();
163     $record->cohortid  = $cohortid;
164     $record->userid    = $userid;
165     $record->timeadded = time();
166     $DB->insert_record('cohort_members', $record);
168     $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
170     $event = \core\event\cohort_member_added::create(array(
171         'context' => context::instance_by_id($cohort->contextid),
172         'objectid' => $cohortid,
173         'relateduserid' => $userid,
174     ));
175     $event->add_record_snapshot('cohort', $cohort);
176     $event->trigger();
179 /**
180  * Remove cohort member
181  * @param  int $cohortid
182  * @param  int $userid
183  * @return void
184  */
185 function cohort_remove_member($cohortid, $userid) {
186     global $DB;
187     $DB->delete_records('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
189     $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
191     $event = \core\event\cohort_member_removed::create(array(
192         'context' => context::instance_by_id($cohort->contextid),
193         'objectid' => $cohortid,
194         'relateduserid' => $userid,
195     ));
196     $event->add_record_snapshot('cohort', $cohort);
197     $event->trigger();
200 /**
201  * Is this user a cohort member?
202  * @param int $cohortid
203  * @param int $userid
204  * @return bool
205  */
206 function cohort_is_member($cohortid, $userid) {
207     global $DB;
209     return $DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
212 /**
213  * Returns the list of cohorts visible to the current user in the given course.
214  *
215  * The following fields are returned in each record: id, name, contextid, idnumber, visible
216  * Fields memberscnt and enrolledcnt will be also returned if requested
217  *
218  * @param context $currentcontext
219  * @param int $withmembers one of the COHORT_XXX constants that allows to return non empty cohorts only
220  *      or cohorts with enroled/not enroled users, or just return members count
221  * @param int $offset
222  * @param int $limit
223  * @param string $search
224  * @return array
225  */
226 function cohort_get_available_cohorts($currentcontext, $withmembers = 0, $offset = 0, $limit = 25, $search = '') {
227     global $DB;
229     $params = array();
231     // Build context subquery. Find the list of parent context where user is able to see any or visible-only cohorts.
232     // Since this method is normally called for the current course all parent contexts are already preloaded.
233     $contextsany = array_filter($currentcontext->get_parent_context_ids(),
234         create_function('$a', 'return has_capability("moodle/cohort:view", context::instance_by_id($a));'));
235     $contextsvisible = array_diff($currentcontext->get_parent_context_ids(), $contextsany);
236     if (empty($contextsany) && empty($contextsvisible)) {
237         // User does not have any permissions to view cohorts.
238         return array();
239     }
240     $subqueries = array();
241     if (!empty($contextsany)) {
242         list($parentsql, $params1) = $DB->get_in_or_equal($contextsany, SQL_PARAMS_NAMED, 'ctxa');
243         $subqueries[] = 'c.contextid ' . $parentsql;
244         $params = array_merge($params, $params1);
245     }
246     if (!empty($contextsvisible)) {
247         list($parentsql, $params1) = $DB->get_in_or_equal($contextsvisible, SQL_PARAMS_NAMED, 'ctxv');
248         $subqueries[] = '(c.visible = 1 AND c.contextid ' . $parentsql. ')';
249         $params = array_merge($params, $params1);
250     }
251     $wheresql = '(' . implode(' OR ', $subqueries) . ')';
253     // Build the rest of the query.
254     $fromsql = "";
255     $fieldssql = 'c.id, c.name, c.contextid, c.idnumber, c.visible';
256     $groupbysql = '';
257     $havingsql = '';
258     if ($withmembers) {
259         $fieldssql .= ', s.memberscnt';
260         $subfields = "c.id, COUNT(DISTINCT cm.userid) AS memberscnt";
261         $groupbysql = " GROUP BY c.id";
262         $fromsql = " LEFT JOIN {cohort_members} cm ON cm.cohortid = c.id ";
263         if (in_array($withmembers,
264                 array(COHORT_COUNT_ENROLLED_MEMBERS, COHORT_WITH_ENROLLED_MEMBERS_ONLY, COHORT_WITH_NOTENROLLED_MEMBERS_ONLY))) {
265             list($esql, $params2) = get_enrolled_sql($currentcontext);
266             $fromsql .= " LEFT JOIN ($esql) u ON u.id = cm.userid ";
267             $params = array_merge($params2, $params);
268             $fieldssql .= ', s.enrolledcnt';
269             $subfields .= ', COUNT(DISTINCT u.id) AS enrolledcnt';
270         }
271         if ($withmembers == COHORT_WITH_MEMBERS_ONLY) {
272             $havingsql = " HAVING COUNT(DISTINCT cm.userid) > 0";
273         } else if ($withmembers == COHORT_WITH_ENROLLED_MEMBERS_ONLY) {
274             $havingsql = " HAVING COUNT(DISTINCT u.id) > 0";
275         } else if ($withmembers == COHORT_WITH_NOTENROLLED_MEMBERS_ONLY) {
276             $havingsql = " HAVING COUNT(DISTINCT cm.userid) > COUNT(DISTINCT u.id)";
277         }
278     }
279     if ($search) {
280         list($searchsql, $searchparams) = cohort_get_search_query($search);
281         $wheresql .= ' AND ' . $searchsql;
282         $params = array_merge($params, $searchparams);
283     }
285     if ($withmembers) {
286         $sql = "SELECT " . str_replace('c.', 'cohort.', $fieldssql) . "
287                   FROM {cohort} cohort
288                   JOIN (SELECT $subfields
289                           FROM {cohort} c $fromsql
290                          WHERE $wheresql $groupbysql $havingsql
291                         ) s ON cohort.id = s.id
292               ORDER BY cohort.name, cohort.idnumber";
293     } else {
294         $sql = "SELECT $fieldssql
295                   FROM {cohort} c $fromsql
296                  WHERE $wheresql
297               ORDER BY c.name, c.idnumber";
298     }
300     return $DB->get_records_sql($sql, $params, $offset, $limit);
303 /**
304  * Check if cohort exists and user is allowed to access it from the given context.
305  *
306  * @param stdClass|int $cohortorid cohort object or id
307  * @param context $currentcontext current context (course) where visibility is checked
308  * @return boolean
309  */
310 function cohort_can_view_cohort($cohortorid, $currentcontext) {
311     global $DB;
312     if (is_numeric($cohortorid)) {
313         $cohort = $DB->get_record('cohort', array('id' => $cohortorid), 'id, contextid, visible');
314     } else {
315         $cohort = $cohortorid;
316     }
318     if ($cohort && in_array($cohort->contextid, $currentcontext->get_parent_context_ids())) {
319         if ($cohort->visible) {
320             return true;
321         }
322         $cohortcontext = context::instance_by_id($cohort->contextid);
323         if (has_capability('moodle/cohort:view', $cohortcontext)) {
324             return true;
325         }
326     }
327     return false;
330 /**
331  * Produces a part of SQL query to filter cohorts by the search string
332  *
333  * Called from {@link cohort_get_cohorts()}, {@link cohort_get_all_cohorts()} and {@link cohort_get_available_cohorts()}
334  *
335  * @access private
336  *
337  * @param string $search search string
338  * @param string $tablealias alias of cohort table in the SQL query (highly recommended if other tables are used in query)
339  * @return array of two elements - SQL condition and array of named parameters
340  */
341 function cohort_get_search_query($search, $tablealias = '') {
342     global $DB;
343     $params = array();
344     if (empty($search)) {
345         // This function should not be called if there is no search string, just in case return dummy query.
346         return array('1=1', $params);
347     }
348     if ($tablealias && substr($tablealias, -1) !== '.') {
349         $tablealias .= '.';
350     }
351     $searchparam = '%' . $DB->sql_like_escape($search) . '%';
352     $conditions = array();
353     $fields = array('name', 'idnumber', 'description');
354     $cnt = 0;
355     foreach ($fields as $field) {
356         $conditions[] = $DB->sql_like($tablealias . $field, ':csearch' . $cnt, false);
357         $params['csearch' . $cnt] = $searchparam;
358         $cnt++;
359     }
360     $sql = '(' . implode(' OR ', $conditions) . ')';
361     return array($sql, $params);
364 /**
365  * Get all the cohorts defined in given context.
366  *
367  * The function does not check user capability to view/manage cohorts in the given context
368  * assuming that it has been already verified.
369  *
370  * @param int $contextid
371  * @param int $page number of the current page
372  * @param int $perpage items per page
373  * @param string $search search string
374  * @return array    Array(totalcohorts => int, cohorts => array, allcohorts => int)
375  */
376 function cohort_get_cohorts($contextid, $page = 0, $perpage = 25, $search = '') {
377     global $DB;
379     $fields = "SELECT *";
380     $countfields = "SELECT COUNT(1)";
381     $sql = " FROM {cohort}
382              WHERE contextid = :contextid";
383     $params = array('contextid' => $contextid);
384     $order = " ORDER BY name ASC, idnumber ASC";
386     if (!empty($search)) {
387         list($searchcondition, $searchparams) = cohort_get_search_query($search);
388         $sql .= ' AND ' . $searchcondition;
389         $params = array_merge($params, $searchparams);
390     }
392     $totalcohorts = $allcohorts = $DB->count_records('cohort', array('contextid' => $contextid));
393     if (!empty($search)) {
394         $totalcohorts = $DB->count_records_sql($countfields . $sql, $params);
395     }
396     $cohorts = $DB->get_records_sql($fields . $sql . $order, $params, $page*$perpage, $perpage);
398     return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts, 'allcohorts' => $allcohorts);
401 /**
402  * Get all the cohorts defined anywhere in system.
403  *
404  * The function assumes that user capability to view/manage cohorts on system level
405  * has already been verified. This function only checks if such capabilities have been
406  * revoked in child (categories) contexts.
407  *
408  * @param int $page number of the current page
409  * @param int $perpage items per page
410  * @param string $search search string
411  * @return array    Array(totalcohorts => int, cohorts => array, allcohorts => int)
412  */
413 function cohort_get_all_cohorts($page = 0, $perpage = 25, $search = '') {
414     global $DB;
416     $fields = "SELECT c.*, ".context_helper::get_preload_record_columns_sql('ctx');
417     $countfields = "SELECT COUNT(*)";
418     $sql = " FROM {cohort} c
419              JOIN {context} ctx ON ctx.id = c.contextid ";
420     $params = array();
421     $wheresql = '';
423     if ($excludedcontexts = cohort_get_invisible_contexts()) {
424         list($excludedsql, $excludedparams) = $DB->get_in_or_equal($excludedcontexts, SQL_PARAMS_NAMED, 'excl', false);
425         $wheresql = ' WHERE c.contextid '.$excludedsql;
426         $params = array_merge($params, $excludedparams);
427     }
429     $totalcohorts = $allcohorts = $DB->count_records_sql($countfields . $sql . $wheresql, $params);
431     if (!empty($search)) {
432         list($searchcondition, $searchparams) = cohort_get_search_query($search, 'c');
433         $wheresql .= ($wheresql ? ' AND ' : ' WHERE ') . $searchcondition;
434         $params = array_merge($params, $searchparams);
435         $totalcohorts = $DB->count_records_sql($countfields . $sql . $wheresql, $params);
436     }
438     $order = " ORDER BY c.name ASC, c.idnumber ASC";
439     $cohorts = $DB->get_records_sql($fields . $sql . $wheresql . $order, $params, $page*$perpage, $perpage);
441     // Preload used contexts, they will be used to check view/manage/assign capabilities and display categories names.
442     foreach (array_keys($cohorts) as $key) {
443         context_helper::preload_from_record($cohorts[$key]);
444     }
446     return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts, 'allcohorts' => $allcohorts);
449 /**
450  * Returns list of contexts where cohorts are present but current user does not have capability to view/manage them.
451  *
452  * This function is called from {@link cohort_get_all_cohorts()} to ensure correct pagination in rare cases when user
453  * is revoked capability in child contexts. It assumes that user's capability to view/manage cohorts on system
454  * level has already been verified.
455  *
456  * @access private
457  *
458  * @return array array of context ids
459  */
460 function cohort_get_invisible_contexts() {
461     global $DB;
462     if (is_siteadmin()) {
463         // Shortcut, admin can do anything and can not be prohibited from any context.
464         return array();
465     }
466     $records = $DB->get_recordset_sql("SELECT DISTINCT ctx.id, ".context_helper::get_preload_record_columns_sql('ctx')." ".
467         "FROM {context} ctx JOIN {cohort} c ON ctx.id = c.contextid ");
468     $excludedcontexts = array();
469     foreach ($records as $ctx) {
470         context_helper::preload_from_record($ctx);
471         if (!has_any_capability(array('moodle/cohort:manage', 'moodle/cohort:view'), context::instance_by_id($ctx->id))) {
472             $excludedcontexts[] = $ctx->id;
473         }
474     }
475     return $excludedcontexts;
478 /**
479  * Returns navigation controls (tabtree) to be displayed on cohort management pages
480  *
481  * @param context $context system or category context where cohorts controls are about to be displayed
482  * @param moodle_url $currenturl
483  * @return null|renderable
484  */
485 function cohort_edit_controls(context $context, moodle_url $currenturl) {
486     $tabs = array();
487     $currenttab = 'view';
488     $viewurl = new moodle_url('/cohort/index.php', array('contextid' => $context->id));
489     if (($searchquery = $currenturl->get_param('search'))) {
490         $viewurl->param('search', $searchquery);
491     }
492     if ($context->contextlevel == CONTEXT_SYSTEM) {
493         $tabs[] = new tabobject('view', new moodle_url($viewurl, array('showall' => 0)), get_string('systemcohorts', 'cohort'));
494         $tabs[] = new tabobject('viewall', new moodle_url($viewurl, array('showall' => 1)), get_string('allcohorts', 'cohort'));
495         if ($currenturl->get_param('showall')) {
496             $currenttab = 'viewall';
497         }
498     } else {
499         $tabs[] = new tabobject('view', $viewurl, get_string('cohorts', 'cohort'));
500     }
501     if (has_capability('moodle/cohort:manage', $context)) {
502         $addurl = new moodle_url('/cohort/edit.php', array('contextid' => $context->id));
503         $tabs[] = new tabobject('addcohort', $addurl, get_string('addcohort', 'cohort'));
504         if ($currenturl->get_path() === $addurl->get_path() && !$currenturl->param('id')) {
505             $currenttab = 'addcohort';
506         }
508         $uploadurl = new moodle_url('/cohort/upload.php', array('contextid' => $context->id));
509         $tabs[] = new tabobject('uploadcohorts', $uploadurl, get_string('uploadcohorts', 'cohort'));
510         if ($currenturl->get_path() === $uploadurl->get_path()) {
511             $currenttab = 'uploadcohorts';
512         }
513     }
514     if (count($tabs) > 1) {
515         return new tabtree($tabs, $currenttab);
516     }
517     return null;
520 /**
521  * Implements callback inplace_editable() allowing to edit values in-place
522  *
523  * @param string $itemtype
524  * @param int $itemid
525  * @param mixed $newvalue
526  * @return \core\output\inplace_editable
527  */
528 function core_cohort_inplace_editable($itemtype, $itemid, $newvalue) {
529     if ($itemtype === 'cohortname') {
530         return \core_cohort\output\cohortname::update($itemid, $newvalue);
531     } else if ($itemtype === 'cohortidnumber') {
532         return \core_cohort\output\cohortidnumber::update($itemid, $newvalue);
533     }