2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Contains class core_course_list_element
22 * @copyright 2018 Marina Glancy
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 defined('MOODLE_INTERNAL') ||
die();
29 * Class to store information about one course in a list of courses
31 * Not all information may be retrieved when object is created but
32 * it will be retrieved on demand when appropriate property or method is
35 * Instances of this class are usually returned by functions
36 * {@link core_course_category::search_courses()}
38 * {@link core_course_category::get_courses()}
40 * @property-read int $id
41 * @property-read int $category Category ID
42 * @property-read int $sortorder
43 * @property-read string $fullname
44 * @property-read string $shortname
45 * @property-read string $idnumber
46 * @property-read string $summary Course summary. Field is present if core_course_category::get_courses()
47 * was called with option 'summary'. Otherwise will be retrieved from DB on first request
48 * @property-read int $summaryformat Summary format. Field is present if core_course_category::get_courses()
49 * was called with option 'summary'. Otherwise will be retrieved from DB on first request
50 * @property-read string $format Course format. Retrieved from DB on first request
51 * @property-read int $showgrades Retrieved from DB on first request
52 * @property-read int $newsitems Retrieved from DB on first request
53 * @property-read int $startdate
54 * @property-read int $enddate
55 * @property-read int $marker Retrieved from DB on first request
56 * @property-read int $maxbytes Retrieved from DB on first request
57 * @property-read int $legacyfiles Retrieved from DB on first request
58 * @property-read int $showreports Retrieved from DB on first request
59 * @property-read int $visible
60 * @property-read int $visibleold Retrieved from DB on first request
61 * @property-read int $groupmode Retrieved from DB on first request
62 * @property-read int $groupmodeforce Retrieved from DB on first request
63 * @property-read int $defaultgroupingid Retrieved from DB on first request
64 * @property-read string $lang Retrieved from DB on first request
65 * @property-read string $theme Retrieved from DB on first request
66 * @property-read int $timecreated Retrieved from DB on first request
67 * @property-read int $timemodified Retrieved from DB on first request
68 * @property-read int $requested Retrieved from DB on first request
69 * @property-read int $enablecompletion Retrieved from DB on first request
70 * @property-read int $completionnotify Retrieved from DB on first request
71 * @property-read int $cacherev
75 * @copyright 2013 Marina Glancy
76 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
78 class core_course_list_element
implements IteratorAggregate
{
80 /** @var stdClass record retrieved from DB, may have additional calculated property such as managers and hassummary */
83 /** @var array array of course contacts - stores result of call to get_course_contacts() */
84 protected $coursecontacts;
86 /** @var bool true if the current user can access the course, false otherwise. */
87 protected $canaccess = null;
90 * Creates an instance of the class from record
92 * @param stdClass $record except fields from course table it may contain
93 * field hassummary indicating that summary field is not empty.
94 * Also it is recommended to have context fields here ready for
97 public function __construct(stdClass
$record) {
98 context_helper
::preload_from_record($record);
99 $this->record
= new stdClass();
100 foreach ($record as $key => $value) {
101 $this->record
->$key = $value;
106 * Indicates if the course has non-empty summary field
110 public function has_summary() {
111 if (isset($this->record
->hassummary
)) {
112 return !empty($this->record
->hassummary
);
114 if (!isset($this->record
->summary
)) {
115 // We need to retrieve summary.
116 $this->__get('summary');
118 return !empty($this->record
->summary
);
122 * Indicates if the course have course contacts to display
126 public function has_course_contacts() {
127 if (!isset($this->record
->managers
)) {
128 $courses = array($this->id
=> &$this->record
);
129 core_course_category
::preload_course_contacts($courses);
131 return !empty($this->record
->managers
);
135 * Returns list of course contacts (usually teachers) to display in course link
137 * Roles to display are set up in $CFG->coursecontact
139 * The result is the list of users where user id is the key and the value
140 * is an array with elements:
141 * - 'user' - object containing basic user information
142 * - 'role' - object containing basic role information (id, name, shortname, coursealias)
143 * - 'rolename' => role_get_name($role, $context, ROLENAME_ALIAS)
144 * - 'username' => fullname($user, $canviewfullnames)
148 public function get_course_contacts() {
150 if (empty($CFG->coursecontact
)) {
151 // No roles are configured to be displayed as course contacts.
155 if (!$this->has_course_contacts()) {
156 // No course contacts exist.
160 if ($this->coursecontacts
=== null) {
161 $this->coursecontacts
= array();
163 $context = context_course
::instance($this->id
);
165 $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
167 $displayall = get_config('core', 'coursecontactduplicates');
169 foreach ($this->record
->managers
as $ruser) {
170 $processed = array_key_exists($ruser->id
, $this->coursecontacts
);
171 if (!$displayall && $processed) {
176 'id' => $ruser->roleid
,
177 'name' => $ruser->rolename
,
178 'shortname' => $ruser->roleshortname
,
179 'coursealias' => $ruser->rolecoursealias
,
181 $role->displayname
= role_get_name($role, $context, ROLENAME_ALIAS
);
184 $user = username_load_fields_from_object((object)[], $ruser, null, ['id', 'username']);
185 $this->coursecontacts
[$ruser->id
] = [
187 'username' => fullname($user, $canviewfullnames),
189 // List of all roles.
192 // Primary role of this user.
194 'rolename' => $role->displayname
,
197 $this->coursecontacts
[$ruser->id
]['roles'][$ruser->roleid
] = $role;
200 return $this->coursecontacts
;
204 * Checks if course has any associated overview files
208 public function has_course_overviewfiles() {
210 if (empty($CFG->courseoverviewfileslimit
)) {
213 $fs = get_file_storage();
214 $context = context_course
::instance($this->id
);
215 return !$fs->is_area_empty($context->id
, 'course', 'overviewfiles');
219 * Returns all course overview files
221 * @return array array of stored_file objects
223 public function get_course_overviewfiles() {
225 if (empty($CFG->courseoverviewfileslimit
)) {
228 require_once($CFG->libdir
. '/filestorage/file_storage.php');
229 require_once($CFG->dirroot
. '/course/lib.php');
230 $fs = get_file_storage();
231 $context = context_course
::instance($this->id
);
232 $files = $fs->get_area_files($context->id
, 'course', 'overviewfiles', false, 'filename', false);
234 $overviewfilesoptions = course_overviewfiles_options($this->id
);
235 $acceptedtypes = $overviewfilesoptions['accepted_types'];
236 if ($acceptedtypes !== '*') {
237 // Filter only files with allowed extensions.
238 require_once($CFG->libdir
. '/filelib.php');
239 foreach ($files as $key => $file) {
240 if (!file_extension_in_typegroup($file->get_filename(), $acceptedtypes)) {
245 if (count($files) > $CFG->courseoverviewfileslimit
) {
246 // Return no more than $CFG->courseoverviewfileslimit files.
247 $files = array_slice($files, 0, $CFG->courseoverviewfileslimit
, true);
254 * Magic method to check if property is set
256 * @param string $name
259 public function __isset($name) {
260 return isset($this->record
->$name);
264 * Magic method to get a course property
266 * Returns any field from table course (retrieves it from DB if it was not retrieved before)
268 * @param string $name
271 public function __get($name) {
273 if (property_exists($this->record
, $name)) {
274 return $this->record
->$name;
275 } else if ($name === 'summary' ||
$name === 'summaryformat') {
276 // Retrieve fields summary and summaryformat together because they are most likely to be used together.
277 $record = $DB->get_record('course', array('id' => $this->record
->id
), 'summary, summaryformat', MUST_EXIST
);
278 $this->record
->summary
= $record->summary
;
279 $this->record
->summaryformat
= $record->summaryformat
;
280 return $this->record
->$name;
281 } else if (array_key_exists($name, $DB->get_columns('course'))) {
282 // Another field from table 'course' that was not retrieved.
283 $this->record
->$name = $DB->get_field('course', $name, array('id' => $this->record
->id
), MUST_EXIST
);
284 return $this->record
->$name;
286 debugging('Invalid course property accessed! '.$name);
291 * All properties are read only, sorry.
293 * @param string $name
295 public function __unset($name) {
296 debugging('Can not unset '.get_class($this).' instance properties!');
300 * Magic setter method, we do not want anybody to modify properties from the outside
302 * @param string $name
303 * @param mixed $value
305 public function __set($name, $value) {
306 debugging('Can not change '.get_class($this).' instance properties!');
310 * Create an iterator because magic vars can't be seen by 'foreach'.
311 * Exclude context fields
313 * Implementing method from interface IteratorAggregate
315 * @return ArrayIterator
317 public function getIterator() {
318 $ret = array('id' => $this->record
->id
);
319 foreach ($this->record
as $property => $value) {
320 $ret[$property] = $value;
322 return new ArrayIterator($ret);
326 * Returns the name of this course as it should be displayed within a list.
329 public function get_formatted_name() {
330 return format_string(get_course_display_name_for_list($this), true, $this->get_context());
334 * Returns the formatted fullname for this course.
337 public function get_formatted_fullname() {
338 return format_string($this->__get('fullname'), true, $this->get_context());
342 * Returns the formatted shortname for this course.
345 public function get_formatted_shortname() {
346 return format_string($this->__get('shortname'), true, $this->get_context());
350 * Returns true if the current user can access this course.
353 public function can_access() {
354 if ($this->canaccess
=== null) {
355 $this->canaccess
= can_access_course($this->record
);
357 return $this->canaccess
;
361 * Returns true if the user can edit this courses settings.
363 * Note: this function does not check that the current user can access the course.
364 * To do that please call require_login with the course, or if not possible call
365 * {@link core_course_list_element::can_access()}
369 public function can_edit() {
370 return has_capability('moodle/course:update', $this->get_context());
374 * Returns true if the user can change the visibility of this course.
376 * Note: this function does not check that the current user can access the course.
377 * To do that please call require_login with the course, or if not possible call
378 * {@link core_course_list_element::can_access()}
382 public function can_change_visibility() {
383 // You must be able to both hide a course and view the hidden course.
384 return has_all_capabilities(array('moodle/course:visibility', 'moodle/course:viewhiddencourses'),
385 $this->get_context());
389 * Returns the context for this course.
390 * @return context_course
392 public function get_context() {
393 return context_course
::instance($this->__get('id'));
397 * Returns true if this course is visible to the current user.
400 public function is_uservisible() {
401 return $this->visible ||
has_capability('moodle/course:viewhiddencourses', $this->get_context());
405 * Returns true if the current user can review enrolments for this course.
407 * Note: this function does not check that the current user can access the course.
408 * To do that please call require_login with the course, or if not possible call
409 * {@link core_course_list_element::can_access()}
413 public function can_review_enrolments() {
414 return has_capability('moodle/course:enrolreview', $this->get_context());
418 * Returns true if the current user can delete this course.
420 * Note: this function does not check that the current user can access the course.
421 * To do that please call require_login with the course, or if not possible call
422 * {@link core_course_list_element::can_access()}
426 public function can_delete() {
427 return can_delete_course($this->id
);
431 * Returns true if the current user can backup this course.
433 * Note: this function does not check that the current user can access the course.
434 * To do that please call require_login with the course, or if not possible call
435 * {@link core_course_list_element::can_access()}
439 public function can_backup() {
440 return has_capability('moodle/backup:backupcourse', $this->get_context());
444 * Returns true if the current user can restore this course.
446 * Note: this function does not check that the current user can access the course.
447 * To do that please call require_login with the course, or if not possible call
448 * {@link core_course_list_element::can_access()}
452 public function can_restore() {
453 return has_capability('moodle/restore:restorecourse', $this->get_context());