Search moodle.org's
Developer Documentation


  • Bug fixes for general core bugs in 2.8.x ended 9 November 2015 (12 months).
  • Bug fixes for security issues in 2.8.x ended 9 May 2016 (18 months).
  • minimum PHP 5.4.4 (always use latest PHP 5.4.x or 5.5.x on Windows - http://windows.php.net/download/), PHP 7 is NOT supported
  • /cohort/ -> lib.php (source)

    Differences Between: [Versions 28 and 31] [Versions 28 and 32] [Versions 28 and 33] [Versions 28 and 34] [Versions 28 and 35] [Versions 28 and 36] [Versions 28 and 37]

       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  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);
      33  
      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;
      42  
      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      }
      67  
      68      $cohort->id = $DB->insert_record('cohort', $cohort);
      69  
      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();
      76  
      77      return $cohort->id;
      78  }
      79  
      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);
      93  
      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  }
     100  
     101  /**
     102   * Delete cohort.
     103   * @param  stdClass $cohort
     104   * @return void
     105   */
     106  function cohort_delete_cohort($cohort) {
     107      global $DB;
     108  
     109      if ($cohort->component) {
     110          // TODO: add component delete callback
     111      }
     112  
     113      $DB->delete_records('cohort_members', array('cohortid'=>$cohort->id));
     114      $DB->delete_records('cohort', array('id'=>$cohort->id));
     115  
     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();
     122  }
     123  
     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
     134  
     135      $oldcontext = context_coursecat::instance($category->id);
     136  
     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      }
     146  
     147      $DB->execute($sql, $params);
     148  }
     149  
     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);
     167  
     168      $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
     169  
     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();
     177  }
     178  
     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));
     188  
     189      $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST);
     190  
     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();
     198  }
     199  
     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;
     208  
     209      return $DB->record_exists('cohort_members', array('cohortid'=>$cohortid, 'userid'=>$userid));
     210  }
     211  
     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;
     228  
     229      $params = array();
     230  
     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) . ')';
     252  
     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      }
     284  
     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      }
     299  
     300      return $DB->get_records_sql($sql, $params, $offset, $limit);
     301  }
     302  
     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      }
     317  
     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;
     328  }
     329  
     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);
     362  }
     363  
     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;
     378  
     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";
     385  
     386      if (!empty($search)) {
     387          list($searchcondition, $searchparams) = cohort_get_search_query($search);
     388          $sql .= ' AND ' . $searchcondition;
     389          $params = array_merge($params, $searchparams);
     390      }
     391  
     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);
     397  
     398      return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts, 'allcohorts' => $allcohorts);
     399  }
     400  
     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;
     415  
     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 = '';
     422  
     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      }
     428  
     429      $totalcohorts = $allcohorts = $DB->count_records_sql($countfields . $sql . $wheresql, $params);
     430  
     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      }
     437  
     438      $order = " ORDER BY c.name ASC, c.idnumber ASC";
     439      $cohorts = $DB->get_records_sql($fields . $sql . $wheresql . $order, $params, $page*$perpage, $perpage);
     440  
     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      }
     445  
     446      return array('totalcohorts' => $totalcohorts, 'cohorts' => $cohorts, 'allcohorts' => $allcohorts);
     447  }
     448  
     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;
     476  }
     477  
     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          }
     507  
     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;
     518  }
    

    Search This Site: