Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
- Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
- PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/calendar/ -> externallib.php (source)
Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]
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 * External calendar API 19 * 20 * @package core_calendar 21 * @category external 22 * @copyright 2012 Ankit Agarwal 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 * @since Moodle 2.5 25 */ 26 27 defined('MOODLE_INTERNAL') || die; 28 29 require_once($CFG->dirroot . '/calendar/lib.php'); 30 31 use core_calendar\local\api as local_api; 32 use core_calendar\local\event\container as event_container; 33 use core_calendar\local\event\forms\create as create_event_form; 34 use core_calendar\local\event\forms\update as update_event_form; 35 use core_calendar\local\event\mappers\create_update_form_mapper; 36 use core_calendar\external\event_exporter; 37 use core_calendar\external\events_exporter; 38 use core_calendar\external\events_grouped_by_course_exporter; 39 use core_calendar\external\events_related_objects_cache; 40 use core_external\external_api; 41 use core_external\external_format_value; 42 use core_external\external_function_parameters; 43 use core_external\external_multiple_structure; 44 use core_external\external_single_structure; 45 use core_external\external_value; 46 use core_external\external_warnings; 47 use core_external\util as external_util; 48 49 /** 50 * Calendar external functions 51 * 52 * @package core_calendar 53 * @category external 54 * @copyright 2012 Ankit Agarwal 55 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 56 * @since Moodle 2.5 57 */ 58 class core_calendar_external extends external_api { 59 /** 60 * Returns description of method parameters 61 * 62 * @return external_function_parameters 63 * @since Moodle 2.5 64 */ 65 public static function delete_calendar_events_parameters() { 66 return new external_function_parameters( 67 array('events' => new external_multiple_structure( 68 new external_single_structure( 69 array( 70 'eventid' => new external_value(PARAM_INT, 'Event ID', VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 71 'repeat' => new external_value(PARAM_BOOL, 'Delete comeplete series if repeated event') 72 ), 'List of events to delete' 73 ) 74 ) 75 ) 76 ); 77 } 78 79 /** 80 * Delete Calendar events 81 * 82 * @param array $eventids A list of event ids with repeat flag to delete 83 * @return null 84 * @since Moodle 2.5 85 */ 86 public static function delete_calendar_events($events) { 87 global $DB; 88 89 // Parameter validation. 90 $params = self::validate_parameters(self:: delete_calendar_events_parameters(), array('events' => $events)); 91 92 $transaction = $DB->start_delegated_transaction(); 93 94 foreach ($params['events'] as $event) { 95 $eventobj = calendar_event::load($event['eventid']); 96 97 // Let's check if the user is allowed to delete an event. 98 if (!calendar_delete_event_allowed($eventobj)) { 99 throw new moodle_exception('nopermissions', 'error', '', get_string('deleteevent', 'calendar')); 100 } 101 // Time to do the magic. 102 $eventobj->delete($event['repeat']); 103 } 104 105 // Everything done smoothly, let's commit. 106 $transaction->allow_commit(); 107 108 return null; 109 } 110 111 /** 112 * Returns description of method result value 113 * 114 * @return \core_external\external_description 115 * @since Moodle 2.5 116 */ 117 public static function delete_calendar_events_returns() { 118 return null; 119 } 120 121 /** 122 * Returns description of method parameters 123 * 124 * @return external_function_parameters 125 * @since Moodle 2.5 126 */ 127 public static function get_calendar_events_parameters() { 128 return new external_function_parameters( 129 array('events' => new external_single_structure( 130 array( 131 'eventids' => new external_multiple_structure( 132 new external_value(PARAM_INT, 'event ids') 133 , 'List of event ids', 134 VALUE_DEFAULT, array()), 135 'courseids' => new external_multiple_structure( 136 new external_value(PARAM_INT, 'course ids') 137 , 'List of course ids for which events will be returned', 138 VALUE_DEFAULT, array()), 139 'groupids' => new external_multiple_structure( 140 new external_value(PARAM_INT, 'group ids') 141 , 'List of group ids for which events should be returned', 142 VALUE_DEFAULT, array()), 143 'categoryids' => new external_multiple_structure( 144 new external_value(PARAM_INT, 'Category ids'), 145 'List of category ids for which events will be returned', 146 VALUE_DEFAULT, array()), 147 ), 'Event details', VALUE_DEFAULT, array()), 148 'options' => new external_single_structure( 149 array( 150 'userevents' => new external_value(PARAM_BOOL, 151 "Set to true to return current user's user events", 152 VALUE_DEFAULT, true, NULL_ALLOWED), 153 'siteevents' => new external_value(PARAM_BOOL, 154 "Set to true to return site events", 155 VALUE_DEFAULT, true, NULL_ALLOWED), 156 'timestart' => new external_value(PARAM_INT, 157 "Time from which events should be returned", 158 VALUE_DEFAULT, 0, NULL_ALLOWED), 159 'timeend' => new external_value(PARAM_INT, 160 "Time to which the events should be returned. We treat 0 and null as no end", 161 VALUE_DEFAULT, 0, NULL_ALLOWED), 162 'ignorehidden' => new external_value(PARAM_BOOL, 163 "Ignore hidden events or not", 164 VALUE_DEFAULT, true, NULL_ALLOWED), 165 166 ), 'Options', VALUE_DEFAULT, array()) 167 ) 168 ); 169 } 170 171 /** 172 * Get Calendar events 173 * 174 * @param array $events A list of events 175 * @param array $options various options 176 * @return array Array of event details 177 * @since Moodle 2.5 178 */ 179 public static function get_calendar_events($events = array(), $options = array()) { 180 global $SITE, $DB, $USER; 181 182 // Parameter validation. 183 $params = self::validate_parameters(self::get_calendar_events_parameters(), array('events' => $events, 'options' => $options)); 184 $funcparam = array('courses' => array(), 'groups' => array(), 'categories' => array()); 185 $hassystemcap = has_capability('moodle/calendar:manageentries', context_system::instance()); 186 $warnings = array(); 187 $coursecategories = array(); 188 189 // Let us find out courses and their categories that we can return events from. 190 if (!$hassystemcap) { 191 $courseobjs = enrol_get_my_courses(); 192 $courses = array_keys($courseobjs); 193 194 $coursecategories = array_flip(array_map(function($course) { 195 return $course->category; 196 }, $courseobjs)); 197 198 foreach ($params['events']['courseids'] as $id) { 199 try { 200 $context = context_course::instance($id); 201 self::validate_context($context); 202 $funcparam['courses'][] = $id; 203 } catch (Exception $e) { 204 $warnings[] = array( 205 'item' => 'course', 206 'itemid' => $id, 207 'warningcode' => 'nopermissions', 208 'message' => 'No access rights in course context '.$e->getMessage().$e->getTraceAsString() 209 ); 210 } 211 } 212 } else { 213 $courses = $params['events']['courseids']; 214 $funcparam['courses'] = $courses; 215 216 if (!empty($courses)) { 217 list($wheresql, $sqlparams) = $DB->get_in_or_equal($courses); 218 $wheresql = "id $wheresql"; 219 $coursecategories = array_flip(array_map(function($course) { 220 return $course->category; 221 }, $DB->get_records_select('course', $wheresql, $sqlparams, '', 'category'))); 222 } 223 } 224 225 // Let us findout groups that we can return events from. 226 if (!$hassystemcap) { 227 $groups = groups_get_my_groups(); 228 $groups = array_keys($groups); 229 foreach ($params['events']['groupids'] as $id) { 230 if (in_array($id, $groups)) { 231 $funcparam['groups'][] = $id; 232 } else { 233 $warnings[] = array('item' => $id, 'warningcode' => 'nopermissions', 'message' => 'you do not have permissions to access this group'); 234 } 235 } 236 } else { 237 $groups = $params['events']['groupids']; 238 $funcparam['groups'] = $groups; 239 } 240 241 $categories = array(); 242 if ($hassystemcap || !empty($courses)) { 243 // Use the category id as the key in the following array. That way we do not have to remove duplicates and 244 // have a faster lookup later. 245 $categories = []; 246 247 if (!empty($params['events']['categoryids'])) { 248 $catobjs = \core_course_category::get_many( 249 array_merge($params['events']['categoryids'], array_keys($coursecategories))); 250 foreach ($catobjs as $catobj) { 251 if (isset($coursecategories[$catobj->id]) || 252 has_capability('moodle/category:manage', $catobj->get_context())) { 253 // If the user has access to a course in this category or can manage the category, 254 // then they can see all parent categories too. 255 $categories[$catobj->id] = true; 256 foreach ($catobj->get_parents() as $catid) { 257 $categories[$catid] = true; 258 } 259 } 260 } 261 $funcparam['categories'] = array_keys($categories); 262 } else { 263 // Fetch all categories where this user has any enrolment, and all categories that this user can manage. 264 $calcatcache = cache::make('core', 'calendar_categories'); 265 // Do not use cache if the user has the system capability as $coursecategories might not represent the 266 // courses the user is enrolled in. 267 $categories = (!$hassystemcap) ? $calcatcache->get('site') : false; 268 if ($categories !== false) { 269 // The ids are stored in a list in the cache. 270 $funcparam['categories'] = $categories; 271 $categories = array_flip($categories); 272 } else { 273 $categories = []; 274 foreach (\core_course_category::get_all() as $category) { 275 if (isset($coursecategories[$category->id]) || 276 has_capability('moodle/category:manage', $category->get_context(), $USER, false)) { 277 // If the user has access to a course in this category or can manage the category, 278 // then they can see all parent categories too. 279 $categories[$category->id] = true; 280 foreach ($category->get_parents() as $catid) { 281 $categories[$catid] = true; 282 } 283 } 284 } 285 $funcparam['categories'] = array_keys($categories); 286 if (!$hassystemcap) { 287 $calcatcache->set('site', $funcparam['categories']); 288 } 289 } 290 } 291 } 292 293 // Do we need user events? 294 if (!empty($params['options']['userevents'])) { 295 $funcparam['users'] = array($USER->id); 296 } else { 297 $funcparam['users'] = false; 298 } 299 300 // Do we need site events? 301 if (!empty($params['options']['siteevents'])) { 302 $funcparam['courses'][] = $SITE->id; 303 } 304 305 // We treat 0 and null as no end. 306 if (empty($params['options']['timeend'])) { 307 $params['options']['timeend'] = PHP_INT_MAX; 308 } 309 310 // Event list does not check visibility and permissions, we'll check that later. 311 $eventlist = calendar_get_legacy_events($params['options']['timestart'], $params['options']['timeend'], 312 $funcparam['users'], $funcparam['groups'], $funcparam['courses'], true, 313 $params['options']['ignorehidden'], $funcparam['categories']); 314 315 // WS expects arrays. 316 $events = array(); 317 318 // We need to get events asked for eventids. 319 if ($eventsbyid = calendar_get_events_by_id($params['events']['eventids'])) { 320 $eventlist += $eventsbyid; 321 } 322 foreach ($eventlist as $eventid => $eventobj) { 323 $event = (array) $eventobj; 324 // Description formatting. 325 $calendareventobj = new calendar_event($event); 326 $event['name'] = $calendareventobj->format_external_name(); 327 list($event['description'], $event['format']) = $calendareventobj->format_external_text(); 328 329 if ($hassystemcap) { 330 // User can see everything, no further check is needed. 331 $events[$eventid] = $event; 332 } else if (!empty($eventobj->modulename)) { 333 $courseid = $eventobj->courseid; 334 if (!$courseid) { 335 if (!$calendareventobj->context || !($context = $calendareventobj->context->get_course_context(false))) { 336 continue; 337 } 338 $courseid = $context->instanceid; 339 } 340 $instances = get_fast_modinfo($courseid)->get_instances_of($eventobj->modulename); 341 if (!empty($instances[$eventobj->instance]->uservisible)) { 342 $events[$eventid] = $event; 343 } 344 } else { 345 // Can the user actually see this event? 346 $eventobj = calendar_event::load($eventobj); 347 if ((($eventobj->courseid == $SITE->id) && (empty($eventobj->categoryid))) || 348 (!empty($eventobj->categoryid) && isset($categories[$eventobj->categoryid])) || 349 (!empty($eventobj->groupid) && in_array($eventobj->groupid, $groups)) || 350 (!empty($eventobj->courseid) && in_array($eventobj->courseid, $courses)) || 351 ($USER->id == $eventobj->userid) || 352 (calendar_edit_event_allowed($eventobj))) { 353 $events[$eventid] = $event; 354 } else { 355 $warnings[] = array('item' => $eventid, 'warningcode' => 'nopermissions', 'message' => 'you do not have permissions to view this event'); 356 } 357 } 358 } 359 return array('events' => $events, 'warnings' => $warnings); 360 } 361 362 /** 363 * Returns description of method result value 364 * 365 * @return \core_external\external_description 366 * @since Moodle 2.5 367 */ 368 public static function get_calendar_events_returns() { 369 return new external_single_structure(array( 370 'events' => new external_multiple_structure( new external_single_structure( 371 array( 372 'id' => new external_value(PARAM_INT, 'event id'), 373 'name' => new external_value(PARAM_RAW, 'event name'), 374 'description' => new external_value(PARAM_RAW, 'Description', VALUE_OPTIONAL, null, NULL_ALLOWED), 375 'format' => new external_format_value('description'), 376 'courseid' => new external_value(PARAM_INT, 'course id'), 377 'categoryid' => new external_value(PARAM_INT, 'Category id (only for category events).', 378 VALUE_OPTIONAL), 379 'groupid' => new external_value(PARAM_INT, 'group id'), 380 'userid' => new external_value(PARAM_INT, 'user id'), 381 'repeatid' => new external_value(PARAM_INT, 'repeat id'), 382 'modulename' => new external_value(PARAM_TEXT, 'module name', VALUE_OPTIONAL, null, NULL_ALLOWED), 383 'instance' => new external_value(PARAM_INT, 'instance id'), 384 'eventtype' => new external_value(PARAM_TEXT, 'Event type'), 385 'timestart' => new external_value(PARAM_INT, 'timestart'), 386 'timeduration' => new external_value(PARAM_INT, 'time duration'), 387 'visible' => new external_value(PARAM_INT, 'visible'), 388 'uuid' => new external_value(PARAM_TEXT, 'unique id of ical events', VALUE_OPTIONAL, null, NULL_NOT_ALLOWED), 389 'sequence' => new external_value(PARAM_INT, 'sequence'), 390 'timemodified' => new external_value(PARAM_INT, 'time modified'), 391 'subscriptionid' => new external_value(PARAM_INT, 'Subscription id', VALUE_OPTIONAL, null, NULL_ALLOWED), 392 ), 'event') 393 ), 394 'warnings' => new external_warnings() 395 ) 396 ); 397 } 398 399 /** 400 * Returns description of method parameters. 401 * 402 * @since Moodle 3.3 403 * @return external_function_parameters 404 */ 405 public static function get_calendar_action_events_by_timesort_parameters() { 406 return new external_function_parameters( 407 array( 408 'timesortfrom' => new external_value(PARAM_INT, 'Time sort from', VALUE_DEFAULT, 0), 409 'timesortto' => new external_value(PARAM_INT, 'Time sort to', VALUE_DEFAULT, null), 410 'aftereventid' => new external_value(PARAM_INT, 'The last seen event id', VALUE_DEFAULT, 0), 411 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 20), 412 'limittononsuspendedevents' => new external_value(PARAM_BOOL, 413 'Limit the events to courses the user is not suspended in', VALUE_DEFAULT, false), 414 'userid' => new external_value(PARAM_INT, 'The user id', VALUE_DEFAULT, null), 415 'searchvalue' => new external_value(PARAM_RAW, 'The value a user wishes to search against', VALUE_DEFAULT, null) 416 ) 417 ); 418 } 419 420 /** 421 * Get calendar action events based on the timesort value. 422 * 423 * @since Moodle 3.3 424 * @param null|int $timesortfrom Events after this time (inclusive) 425 * @param null|int $timesortto Events before this time (inclusive) 426 * @param null|int $aftereventid Get events with ids greater than this one 427 * @param int $limitnum Limit the number of results to this value 428 * @param null|int $userid The user id 429 * @param string|null $searchvalue The value a user wishes to search against 430 * @return array 431 */ 432 public static function get_calendar_action_events_by_timesort($timesortfrom = 0, $timesortto = null, 433 $aftereventid = 0, $limitnum = 20, $limittononsuspendedevents = false, 434 $userid = null, ?string $searchvalue = null) { 435 global $PAGE, $USER; 436 437 $params = self::validate_parameters( 438 self::get_calendar_action_events_by_timesort_parameters(), 439 [ 440 'timesortfrom' => $timesortfrom, 441 'timesortto' => $timesortto, 442 'aftereventid' => $aftereventid, 443 'limitnum' => $limitnum, 444 'limittononsuspendedevents' => $limittononsuspendedevents, 445 'userid' => $userid, 446 'searchvalue' => $searchvalue 447 ] 448 ); 449 if ($params['userid']) { 450 $user = \core_user::get_user($params['userid']); 451 } else { 452 $user = $USER; 453 } 454 455 $context = \context_user::instance($user->id); 456 self::validate_context($context); 457 458 if ($params['userid'] && $USER->id !== $params['userid'] && !has_capability('moodle/calendar:manageentries', $context)) { 459 throw new \required_capability_exception($context, 'moodle/calendar:manageentries', 'nopermission', ''); 460 } 461 462 if (empty($params['aftereventid'])) { 463 $params['aftereventid'] = null; 464 } 465 466 $renderer = $PAGE->get_renderer('core_calendar'); 467 $events = local_api::get_action_events_by_timesort( 468 $params['timesortfrom'], 469 $params['timesortto'], 470 $params['aftereventid'], 471 $params['limitnum'], 472 $params['limittononsuspendedevents'], 473 $user, 474 clean_param($params['searchvalue'], PARAM_TEXT) 475 ); 476 477 $exportercache = new events_related_objects_cache($events); 478 $exporter = new events_exporter($events, ['cache' => $exportercache]); 479 480 return $exporter->export($renderer); 481 } 482 483 /** 484 * Returns description of method result value. 485 * 486 * @since Moodle 3.3 487 * @return \core_external\external_description 488 */ 489 public static function get_calendar_action_events_by_timesort_returns() { 490 return events_exporter::get_read_structure(); 491 } 492 493 /** 494 * Returns description of method parameters. 495 * 496 * @return external_function_parameters 497 */ 498 public static function get_calendar_action_events_by_course_parameters() { 499 return new external_function_parameters( 500 array( 501 'courseid' => new external_value(PARAM_INT, 'Course id'), 502 'timesortfrom' => new external_value(PARAM_INT, 'Time sort from', VALUE_DEFAULT, null), 503 'timesortto' => new external_value(PARAM_INT, 'Time sort to', VALUE_DEFAULT, null), 504 'aftereventid' => new external_value(PARAM_INT, 'The last seen event id', VALUE_DEFAULT, 0), 505 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 20), 506 'searchvalue' => new external_value(PARAM_RAW, 'The value a user wishes to search against', VALUE_DEFAULT, null) 507 ) 508 ); 509 } 510 511 /** 512 * Get calendar action events for the given course. 513 * 514 * @since Moodle 3.3 515 * @param int $courseid Only events in this course 516 * @param null|int $timesortfrom Events after this time (inclusive) 517 * @param null|int $timesortto Events before this time (inclusive) 518 * @param null|int $aftereventid Get events with ids greater than this one 519 * @param int $limitnum Limit the number of results to this value 520 * @param string|null $searchvalue The value a user wishes to search against 521 * @return array 522 */ 523 public static function get_calendar_action_events_by_course( 524 $courseid, $timesortfrom = null, $timesortto = null, $aftereventid = 0, $limitnum = 20, ?string $searchvalue = null) { 525 526 global $PAGE, $USER; 527 528 $user = null; 529 $params = self::validate_parameters( 530 self::get_calendar_action_events_by_course_parameters(), 531 [ 532 'courseid' => $courseid, 533 'timesortfrom' => $timesortfrom, 534 'timesortto' => $timesortto, 535 'aftereventid' => $aftereventid, 536 'limitnum' => $limitnum, 537 'searchvalue' => $searchvalue 538 ] 539 ); 540 $context = \context_user::instance($USER->id); 541 self::validate_context($context); 542 543 if (empty($params['aftereventid'])) { 544 $params['aftereventid'] = null; 545 } 546 547 $courses = enrol_get_my_courses('*', null, 0, [$courseid]); 548 $courses = array_values($courses); 549 550 if (empty($courses)) { 551 return []; 552 } 553 554 $course = $courses[0]; 555 $renderer = $PAGE->get_renderer('core_calendar'); 556 $events = local_api::get_action_events_by_course( 557 $course, 558 $params['timesortfrom'], 559 $params['timesortto'], 560 $params['aftereventid'], 561 $params['limitnum'], 562 clean_param($params['searchvalue'], PARAM_TEXT) 563 ); 564 565 $exportercache = new events_related_objects_cache($events, $courses); 566 $exporter = new events_exporter($events, ['cache' => $exportercache]); 567 568 return $exporter->export($renderer); 569 } 570 571 /** 572 * Returns description of method result value. 573 * 574 * @return \core_external\external_description 575 */ 576 public static function get_calendar_action_events_by_course_returns() { 577 return events_exporter::get_read_structure(); 578 } 579 580 /** 581 * Returns description of method parameters. 582 * 583 * @return external_function_parameters 584 */ 585 public static function get_calendar_action_events_by_courses_parameters() { 586 return new external_function_parameters( 587 array( 588 'courseids' => new external_multiple_structure( 589 new external_value(PARAM_INT, 'Course id') 590 ), 591 'timesortfrom' => new external_value(PARAM_INT, 'Time sort from', VALUE_DEFAULT, null), 592 'timesortto' => new external_value(PARAM_INT, 'Time sort to', VALUE_DEFAULT, null), 593 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 10), 594 'searchvalue' => new external_value(PARAM_RAW, 'The value a user wishes to search against', VALUE_DEFAULT, null) 595 ) 596 ); 597 } 598 599 /** 600 * Get calendar action events for a given list of courses. 601 * 602 * @since Moodle 3.3 603 * @param array $courseids Only include events for these courses 604 * @param null|int $timesortfrom Events after this time (inclusive) 605 * @param null|int $timesortto Events before this time (inclusive) 606 * @param int $limitnum Limit the number of results per course to this value 607 * @param string|null $searchvalue The value a user wishes to search against 608 * @return array 609 */ 610 public static function get_calendar_action_events_by_courses( 611 array $courseids, $timesortfrom = null, $timesortto = null, $limitnum = 10, ?string $searchvalue = null) { 612 613 global $PAGE, $USER; 614 615 $user = null; 616 $params = self::validate_parameters( 617 self::get_calendar_action_events_by_courses_parameters(), 618 [ 619 'courseids' => $courseids, 620 'timesortfrom' => $timesortfrom, 621 'timesortto' => $timesortto, 622 'limitnum' => $limitnum, 623 'searchvalue' => $searchvalue 624 ] 625 ); 626 $context = \context_user::instance($USER->id); 627 self::validate_context($context); 628 629 if (empty($params['courseids'])) { 630 return ['groupedbycourse' => []]; 631 } 632 633 $renderer = $PAGE->get_renderer('core_calendar'); 634 $courses = enrol_get_my_courses('*', null, 0, $params['courseids']); 635 $courses = array_values($courses); 636 637 if (empty($courses)) { 638 return ['groupedbycourse' => []]; 639 } 640 641 $events = local_api::get_action_events_by_courses( 642 $courses, 643 $params['timesortfrom'], 644 $params['timesortto'], 645 $params['limitnum'], 646 clean_param($params['searchvalue'], PARAM_TEXT) 647 ); 648 649 if (empty($events)) { 650 return ['groupedbycourse' => []]; 651 } 652 653 $exportercache = new events_related_objects_cache($events, $courses); 654 $exporter = new events_grouped_by_course_exporter($events, ['cache' => $exportercache]); 655 656 return $exporter->export($renderer); 657 } 658 659 /** 660 * Returns description of method result value. 661 * 662 * @return \core_external\external_description 663 */ 664 public static function get_calendar_action_events_by_courses_returns() { 665 return events_grouped_by_course_exporter::get_read_structure(); 666 } 667 668 /** 669 * Returns description of method parameters. 670 * 671 * @return external_function_parameters. 672 * @since Moodle 2.5 673 */ 674 public static function create_calendar_events_parameters() { 675 // Userid is always current user, so no need to get it from client. 676 // Module based calendar events are not allowed here. Hence no need of instance and modulename. 677 // subscription id and uuid is not allowed as this is not an ical api. 678 return new external_function_parameters( 679 array('events' => new external_multiple_structure( 680 new external_single_structure( 681 array( 682 'name' => new external_value(PARAM_TEXT, 'event name', VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 683 'description' => new external_value(PARAM_RAW, 'Description', VALUE_DEFAULT, null, NULL_ALLOWED), 684 'format' => new external_format_value('description', VALUE_DEFAULT), 685 'courseid' => new external_value(PARAM_INT, 'course id', VALUE_DEFAULT, 0, NULL_NOT_ALLOWED), 686 'groupid' => new external_value(PARAM_INT, 'group id', VALUE_DEFAULT, 0, NULL_NOT_ALLOWED), 687 'repeats' => new external_value(PARAM_INT, 'number of repeats', VALUE_DEFAULT, 0, NULL_NOT_ALLOWED), 688 'eventtype' => new external_value(PARAM_TEXT, 'Event type', VALUE_DEFAULT, 'user', NULL_NOT_ALLOWED), 689 'timestart' => new external_value(PARAM_INT, 'timestart', VALUE_DEFAULT, time(), NULL_NOT_ALLOWED), 690 'timeduration' => new external_value(PARAM_INT, 'time duration', VALUE_DEFAULT, 0, NULL_NOT_ALLOWED), 691 'visible' => new external_value(PARAM_INT, 'visible', VALUE_DEFAULT, 1, NULL_NOT_ALLOWED), 692 'sequence' => new external_value(PARAM_INT, 'sequence', VALUE_DEFAULT, 1, NULL_NOT_ALLOWED), 693 ), 'event') 694 ) 695 ) 696 ); 697 } 698 699 /** 700 * Create calendar events. 701 * 702 * @param array $events A list of events to create. 703 * @return array array of events created. 704 * @since Moodle 2.5 705 * @throws moodle_exception if user doesnt have the permission to create events. 706 */ 707 public static function create_calendar_events($events) { 708 global $DB, $USER; 709 710 // Parameter validation. 711 $params = self::validate_parameters(self::create_calendar_events_parameters(), array('events' => $events)); 712 713 $transaction = $DB->start_delegated_transaction(); 714 $return = array(); 715 $warnings = array(); 716 717 foreach ($params['events'] as $event) { 718 719 // Let us set some defaults. 720 $event['userid'] = $USER->id; 721 $event['modulename'] = ''; 722 $event['instance'] = 0; 723 $event['subscriptionid'] = null; 724 $event['uuid']= ''; 725 $event['format'] = external_util::validate_format($event['format']); 726 if ($event['repeats'] > 0) { 727 $event['repeat'] = 1; 728 } else { 729 $event['repeat'] = 0; 730 } 731 732 $eventobj = new calendar_event($event); 733 734 // Let's check if the user is allowed to delete an event. 735 if (!calendar_add_event_allowed($eventobj)) { 736 $warnings [] = array('item' => $event['name'], 'warningcode' => 'nopermissions', 'message' => 'you do not have permissions to create this event'); 737 continue; 738 } 739 // Let's create the event. 740 $var = $eventobj->create($event); 741 $var = (array)$var->properties(); 742 if ($event['repeat']) { 743 $children = $DB->get_records('event', array('repeatid' => $var['id'])); 744 foreach ($children as $child) { 745 $return[] = (array) $child; 746 } 747 } else { 748 $return[] = $var; 749 } 750 } 751 752 // Everything done smoothly, let's commit. 753 $transaction->allow_commit(); 754 return array('events' => $return, 'warnings' => $warnings); 755 } 756 757 /** 758 * Returns description of method result value. 759 * 760 * @return \core_external\external_description. 761 * @since Moodle 2.5 762 */ 763 public static function create_calendar_events_returns() { 764 return new external_single_structure( 765 array( 766 'events' => new external_multiple_structure( new external_single_structure( 767 array( 768 'id' => new external_value(PARAM_INT, 'event id'), 769 'name' => new external_value(PARAM_RAW, 'event name'), 770 'description' => new external_value(PARAM_RAW, 'Description', VALUE_OPTIONAL), 771 'format' => new external_format_value('description'), 772 'courseid' => new external_value(PARAM_INT, 'course id'), 773 'groupid' => new external_value(PARAM_INT, 'group id'), 774 'userid' => new external_value(PARAM_INT, 'user id'), 775 'repeatid' => new external_value(PARAM_INT, 'repeat id', VALUE_OPTIONAL), 776 'modulename' => new external_value(PARAM_TEXT, 'module name', VALUE_OPTIONAL), 777 'instance' => new external_value(PARAM_INT, 'instance id'), 778 'eventtype' => new external_value(PARAM_TEXT, 'Event type'), 779 'timestart' => new external_value(PARAM_INT, 'timestart'), 780 'timeduration' => new external_value(PARAM_INT, 'time duration'), 781 'visible' => new external_value(PARAM_INT, 'visible'), 782 'uuid' => new external_value(PARAM_TEXT, 'unique id of ical events', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED), 783 'sequence' => new external_value(PARAM_INT, 'sequence'), 784 'timemodified' => new external_value(PARAM_INT, 'time modified'), 785 'subscriptionid' => new external_value(PARAM_INT, 'Subscription id', VALUE_OPTIONAL), 786 ), 'event') 787 ), 788 'warnings' => new external_warnings() 789 ) 790 ); 791 } 792 793 /** 794 * Returns description of method parameters. 795 * 796 * @return external_function_parameters 797 */ 798 public static function get_calendar_event_by_id_parameters() { 799 return new external_function_parameters( 800 array( 801 'eventid' => new external_value(PARAM_INT, 'The event id to be retrieved'), 802 ) 803 ); 804 } 805 806 /** 807 * Get calendar event by id. 808 * 809 * @param int $eventid The calendar event id to be retrieved. 810 * @return array Array of event details 811 */ 812 public static function get_calendar_event_by_id($eventid) { 813 global $PAGE, $USER; 814 815 $params = self::validate_parameters(self::get_calendar_event_by_id_parameters(), ['eventid' => $eventid]); 816 $context = \context_user::instance($USER->id); 817 818 self::validate_context($context); 819 $warnings = array(); 820 821 $eventvault = event_container::get_event_vault(); 822 if ($event = $eventvault->get_event_by_id($params['eventid'])) { 823 $mapper = event_container::get_event_mapper(); 824 if (!calendar_view_event_allowed($mapper->from_event_to_legacy_event($event))) { 825 throw new moodle_exception('nopermissiontoviewcalendar', 'error'); 826 } 827 } 828 829 if (!$event) { 830 // We can't return a warning in this case because the event is not optional. 831 // We don't know the context for the event and it's not worth loading it. 832 $syscontext = context_system::instance(); 833 throw new \required_capability_exception($syscontext, 'moodle/course:view', 'nopermissions', 'error'); 834 } 835 836 $cache = new events_related_objects_cache([$event]); 837 $relatedobjects = [ 838 'context' => $cache->get_context($event), 839 'course' => $cache->get_course($event), 840 ]; 841 842 $exporter = new event_exporter($event, $relatedobjects); 843 $renderer = $PAGE->get_renderer('core_calendar'); 844 845 return array('event' => $exporter->export($renderer), 'warnings' => $warnings); 846 } 847 848 /** 849 * Returns description of method result value 850 * 851 * @return \core_external\external_description 852 */ 853 public static function get_calendar_event_by_id_returns() { 854 $eventstructure = event_exporter::get_read_structure(); 855 856 return new external_single_structure(array( 857 'event' => $eventstructure, 858 'warnings' => new external_warnings() 859 ) 860 ); 861 } 862 863 /** 864 * Returns description of method parameters. 865 * 866 * @return external_function_parameters. 867 */ 868 public static function submit_create_update_form_parameters() { 869 return new external_function_parameters( 870 [ 871 'formdata' => new external_value(PARAM_RAW, 'The data from the event form'), 872 ] 873 ); 874 } 875 876 /** 877 * Handles the event form submission. 878 * 879 * @param string $formdata The event form data in a URI encoded param string 880 * @return array The created or modified event 881 * @throws moodle_exception 882 */ 883 public static function submit_create_update_form($formdata) { 884 global $USER, $PAGE, $CFG; 885 require_once($CFG->libdir."/filelib.php"); 886 887 // Parameter validation. 888 $params = self::validate_parameters(self::submit_create_update_form_parameters(), ['formdata' => $formdata]); 889 $context = \context_user::instance($USER->id); 890 $data = []; 891 892 self::validate_context($context); 893 parse_str($params['formdata'], $data); 894 895 if (WS_SERVER) { 896 // Request via WS, ignore sesskey checks in form library. 897 $USER->ignoresesskey = true; 898 } 899 900 $eventtype = isset($data['eventtype']) ? $data['eventtype'] : null; 901 $coursekey = ($eventtype == 'group') ? 'groupcourseid' : 'courseid'; 902 $courseid = (!empty($data[$coursekey])) ? $data[$coursekey] : null; 903 $editoroptions = \core_calendar\local\event\forms\create::build_editor_options($context); 904 $formoptions = ['editoroptions' => $editoroptions, 'courseid' => $courseid]; 905 $formoptions['eventtypes'] = calendar_get_allowed_event_types($courseid); 906 if ($courseid) { 907 require_once($CFG->libdir . '/grouplib.php'); 908 $groupcoursedata = groups_get_course_data($courseid); 909 if (!empty($groupcoursedata->groups)) { 910 $formoptions['groups'] = []; 911 foreach ($groupcoursedata->groups as $groupid => $groupdata) { 912 $formoptions['groups'][$groupid] = $groupdata->name; 913 } 914 } 915 } 916 917 if (!empty($data['id'])) { 918 $eventid = clean_param($data['id'], PARAM_INT); 919 $legacyevent = calendar_event::load($eventid); 920 $legacyevent->count_repeats(); 921 $formoptions['event'] = $legacyevent; 922 $mform = new update_event_form(null, $formoptions, 'post', '', null, true, $data); 923 } else { 924 $legacyevent = null; 925 $mform = new create_event_form(null, $formoptions, 'post', '', null, true, $data); 926 } 927 928 if ($validateddata = $mform->get_data()) { 929 $formmapper = new create_update_form_mapper(); 930 $properties = $formmapper->from_data_to_event_properties($validateddata); 931 932 if (is_null($legacyevent)) { 933 $legacyevent = new \calendar_event($properties); 934 // Need to do this in order to initialise the description 935 // property which then triggers the update function below 936 // to set the appropriate default properties on the event. 937 $properties = $legacyevent->properties(true); 938 } 939 940 if (!calendar_edit_event_allowed($legacyevent, true)) { 941 throw new \moodle_exception('nopermissiontoupdatecalendar'); 942 } 943 944 $legacyevent->update($properties); 945 $eventcontext = $legacyevent->context; 946 947 file_remove_editor_orphaned_files($validateddata->description); 948 949 // Take any files added to the description draft file area and 950 // convert them into the proper event description file area. Also 951 // parse the description text and replace the URLs to the draft files 952 // with the @@PLUGIN_FILE@@ placeholder to be persisted in the DB. 953 $description = file_save_draft_area_files( 954 $validateddata->description['itemid'], 955 $eventcontext->id, 956 'calendar', 957 'event_description', 958 $legacyevent->id, 959 create_event_form::build_editor_options($eventcontext), 960 $validateddata->description['text'] 961 ); 962 963 // If draft files were found then we need to save the new 964 // description value. 965 if ($description != $validateddata->description['text']) { 966 $properties->id = $legacyevent->id; 967 $properties->description = $description; 968 $legacyevent->update($properties); 969 } 970 971 $eventmapper = event_container::get_event_mapper(); 972 $event = $eventmapper->from_legacy_event_to_event($legacyevent); 973 $cache = new events_related_objects_cache([$event]); 974 $relatedobjects = [ 975 'context' => $cache->get_context($event), 976 'course' => $cache->get_course($event), 977 ]; 978 $exporter = new event_exporter($event, $relatedobjects); 979 $renderer = $PAGE->get_renderer('core_calendar'); 980 981 return [ 'event' => $exporter->export($renderer) ]; 982 } else { 983 return [ 'validationerror' => true ]; 984 } 985 } 986 987 /** 988 * Returns description of method result value. 989 * 990 * @return \core_external\external_description. 991 */ 992 public static function submit_create_update_form_returns() { 993 $eventstructure = event_exporter::get_read_structure(); 994 $eventstructure->required = VALUE_OPTIONAL; 995 996 return new external_single_structure( 997 array( 998 'event' => $eventstructure, 999 'validationerror' => new external_value(PARAM_BOOL, 'Invalid form data', VALUE_DEFAULT, false), 1000 ) 1001 ); 1002 } 1003 1004 /** 1005 * Get data for the monthly calendar view. 1006 * 1007 * @param int $year The year to be shown 1008 * @param int $month The month to be shown 1009 * @param int $courseid The course to be included 1010 * @param int $categoryid The category to be included 1011 * @param bool $includenavigation Whether to include navigation 1012 * @param bool $mini Whether to return the mini month view or not 1013 * @param int $day The day we want to keep as the current day 1014 * @param string|null $view The view mode for the calendar. 1015 * @return array 1016 */ 1017 public static function get_calendar_monthly_view($year, $month, $courseid, $categoryid, $includenavigation, $mini, $day, 1018 ?string $view = null) { 1019 global $USER, $PAGE; 1020 1021 // Parameter validation. 1022 $params = self::validate_parameters(self::get_calendar_monthly_view_parameters(), [ 1023 'year' => $year, 1024 'month' => $month, 1025 'courseid' => $courseid, 1026 'categoryid' => $categoryid, 1027 'includenavigation' => $includenavigation, 1028 'mini' => $mini, 1029 'day' => $day, 1030 'view' => $view, 1031 ]); 1032 1033 $context = \context_user::instance($USER->id); 1034 self::validate_context($context); 1035 $PAGE->set_url('/calendar/'); 1036 1037 $type = \core_calendar\type_factory::get_calendar_instance(); 1038 1039 $time = $type->convert_to_timestamp($params['year'], $params['month'], $params['day']); 1040 $calendar = \calendar_information::create($time, $params['courseid'], $params['categoryid']); 1041 self::validate_context($calendar->context); 1042 1043 $view = $params['view'] ?? ($params['mini'] ? 'mini' : 'month'); 1044 list($data, $template) = calendar_get_view($calendar, $view, $params['includenavigation']); 1045 1046 return $data; 1047 } 1048 1049 /** 1050 * Returns description of method parameters. 1051 * 1052 * @return external_function_parameters 1053 */ 1054 public static function get_calendar_monthly_view_parameters() { 1055 return new external_function_parameters( 1056 [ 1057 'year' => new external_value(PARAM_INT, 'Year to be viewed', VALUE_REQUIRED), 1058 'month' => new external_value(PARAM_INT, 'Month to be viewed', VALUE_REQUIRED), 1059 'courseid' => new external_value(PARAM_INT, 'Course being viewed', VALUE_DEFAULT, SITEID, NULL_ALLOWED), 1060 'categoryid' => new external_value(PARAM_INT, 'Category being viewed', VALUE_DEFAULT, null, NULL_ALLOWED), 1061 'includenavigation' => new external_value( 1062 PARAM_BOOL, 1063 'Whether to show course navigation', 1064 VALUE_DEFAULT, 1065 true, 1066 NULL_ALLOWED 1067 ), 1068 'mini' => new external_value( 1069 PARAM_BOOL, 1070 'Whether to return the mini month view or not', 1071 VALUE_DEFAULT, 1072 false, 1073 NULL_ALLOWED 1074 ), 1075 'day' => new external_value(PARAM_INT, 'Day to be viewed', VALUE_DEFAULT, 1), 1076 'view' => new external_value(PARAM_ALPHA, 'The view mode of the calendar', VALUE_DEFAULT, 'month', NULL_ALLOWED), 1077 ] 1078 ); 1079 } 1080 1081 /** 1082 * Returns description of method result value. 1083 * 1084 * @return \core_external\external_description 1085 */ 1086 public static function get_calendar_monthly_view_returns() { 1087 return \core_calendar\external\month_exporter::get_read_structure(); 1088 } 1089 1090 /** 1091 * Get data for the daily calendar view. 1092 * 1093 * @param int $year The year to be shown 1094 * @param int $month The month to be shown 1095 * @param int $day The day to be shown 1096 * @param int $courseid The course to be included 1097 * @return array 1098 */ 1099 public static function get_calendar_day_view($year, $month, $day, $courseid, $categoryid) { 1100 global $DB, $USER, $PAGE; 1101 1102 // Parameter validation. 1103 $params = self::validate_parameters(self::get_calendar_day_view_parameters(), [ 1104 'year' => $year, 1105 'month' => $month, 1106 'day' => $day, 1107 'courseid' => $courseid, 1108 'categoryid' => $categoryid, 1109 ]); 1110 1111 $context = \context_user::instance($USER->id); 1112 self::validate_context($context); 1113 1114 $type = \core_calendar\type_factory::get_calendar_instance(); 1115 1116 $time = $type->convert_to_timestamp($params['year'], $params['month'], $params['day']); 1117 $calendar = \calendar_information::create($time, $params['courseid'], $params['categoryid']); 1118 self::validate_context($calendar->context); 1119 1120 list($data, $template) = calendar_get_view($calendar, 'day'); 1121 1122 return $data; 1123 } 1124 1125 /** 1126 * Returns description of method parameters. 1127 * 1128 * @return external_function_parameters 1129 */ 1130 public static function get_calendar_day_view_parameters() { 1131 return new external_function_parameters( 1132 [ 1133 'year' => new external_value(PARAM_INT, 'Year to be viewed', VALUE_REQUIRED), 1134 'month' => new external_value(PARAM_INT, 'Month to be viewed', VALUE_REQUIRED), 1135 'day' => new external_value(PARAM_INT, 'Day to be viewed', VALUE_REQUIRED), 1136 'courseid' => new external_value(PARAM_INT, 'Course being viewed', VALUE_DEFAULT, SITEID, NULL_ALLOWED), 1137 'categoryid' => new external_value(PARAM_INT, 'Category being viewed', VALUE_DEFAULT, null, NULL_ALLOWED), 1138 ] 1139 ); 1140 } 1141 1142 /** 1143 * Returns description of method result value. 1144 * 1145 * @return \core_external\external_description 1146 */ 1147 public static function get_calendar_day_view_returns() { 1148 return \core_calendar\external\calendar_day_exporter::get_read_structure(); 1149 } 1150 1151 1152 /** 1153 * Returns description of method parameters. 1154 * 1155 * @return external_function_parameters 1156 */ 1157 public static function update_event_start_day_parameters() { 1158 return new external_function_parameters( 1159 [ 1160 'eventid' => new external_value(PARAM_INT, 'Id of event to be updated', VALUE_REQUIRED), 1161 'daytimestamp' => new external_value(PARAM_INT, 'Timestamp for the new start day', VALUE_REQUIRED), 1162 ] 1163 ); 1164 } 1165 1166 /** 1167 * Change the start day for the given calendar event to the day that 1168 * corresponds with the provided timestamp. 1169 * 1170 * The timestamp only needs to be anytime within the desired day as only 1171 * the date data is extracted from it. 1172 * 1173 * The event's original time of day is maintained, only the date is shifted. 1174 * 1175 * @param int $eventid Id of event to be updated 1176 * @param int $daytimestamp Timestamp for the new start day 1177 * @return array 1178 */ 1179 public static function update_event_start_day($eventid, $daytimestamp) { 1180 global $USER, $PAGE; 1181 1182 // Parameter validation. 1183 $params = self::validate_parameters(self::update_event_start_day_parameters(), [ 1184 'eventid' => $eventid, 1185 'daytimestamp' => $daytimestamp, 1186 ]); 1187 1188 $vault = event_container::get_event_vault(); 1189 $mapper = event_container::get_event_mapper(); 1190 $event = $vault->get_event_by_id($eventid); 1191 1192 if (!$event) { 1193 throw new \moodle_exception('Unable to find event with id ' . $eventid); 1194 } 1195 1196 $legacyevent = $mapper->from_event_to_legacy_event($event); 1197 1198 if (!calendar_edit_event_allowed($legacyevent, true)) { 1199 throw new \moodle_exception('nopermissiontoupdatecalendar'); 1200 } 1201 1202 self::validate_context($legacyevent->context); 1203 1204 $newdate = usergetdate($daytimestamp); 1205 $startdatestring = implode('-', [$newdate['year'], $newdate['mon'], $newdate['mday']]); 1206 $startdate = new DateTimeImmutable($startdatestring); 1207 $event = local_api::update_event_start_day($event, $startdate); 1208 $cache = new events_related_objects_cache([$event]); 1209 $relatedobjects = [ 1210 'context' => $cache->get_context($event), 1211 'course' => $cache->get_course($event), 1212 ]; 1213 $exporter = new event_exporter($event, $relatedobjects); 1214 $renderer = $PAGE->get_renderer('core_calendar'); 1215 1216 return array('event' => $exporter->export($renderer)); 1217 } 1218 1219 /** 1220 * Returns description of method result value. 1221 * 1222 * @return \core_external\external_description 1223 */ 1224 public static function update_event_start_day_returns() { 1225 return new external_single_structure( 1226 array( 1227 'event' => event_exporter::get_read_structure() 1228 ) 1229 ); 1230 } 1231 1232 /** 1233 * Get data for the monthly calendar view. 1234 * 1235 * @param int $courseid The course to be included 1236 * @param int $categoryid The category to be included 1237 * @return array 1238 */ 1239 public static function get_calendar_upcoming_view($courseid, $categoryid) { 1240 global $DB, $USER, $PAGE; 1241 1242 // Parameter validation. 1243 $params = self::validate_parameters(self::get_calendar_upcoming_view_parameters(), [ 1244 'courseid' => $courseid, 1245 'categoryid' => $categoryid, 1246 ]); 1247 1248 $context = \context_user::instance($USER->id); 1249 self::validate_context($context); 1250 $PAGE->set_url('/calendar/'); 1251 1252 $calendar = \calendar_information::create(time(), $params['courseid'], $params['categoryid']); 1253 self::validate_context($calendar->context); 1254 1255 list($data, $template) = calendar_get_view($calendar, 'upcoming'); 1256 1257 return $data; 1258 } 1259 1260 /** 1261 * Returns description of method parameters. 1262 * 1263 * @return external_function_parameters 1264 */ 1265 public static function get_calendar_upcoming_view_parameters() { 1266 return new external_function_parameters( 1267 [ 1268 'courseid' => new external_value(PARAM_INT, 'Course being viewed', VALUE_DEFAULT, SITEID, NULL_ALLOWED), 1269 'categoryid' => new external_value(PARAM_INT, 'Category being viewed', VALUE_DEFAULT, null, NULL_ALLOWED), 1270 ] 1271 ); 1272 } 1273 1274 /** 1275 * Returns description of method result value. 1276 * 1277 * @return \core_external\external_description 1278 */ 1279 public static function get_calendar_upcoming_view_returns() { 1280 return \core_calendar\external\calendar_upcoming_exporter::get_read_structure(); 1281 } 1282 1283 1284 /** 1285 * Returns description of method parameters. 1286 * 1287 * @return external_function_parameters. 1288 * @since Moodle 3.7 1289 */ 1290 public static function get_calendar_access_information_parameters() { 1291 return new external_function_parameters( 1292 [ 1293 'courseid' => new external_value(PARAM_INT, 'Course to check, empty for site calendar events.', VALUE_DEFAULT, 0), 1294 ] 1295 ); 1296 } 1297 1298 /** 1299 * Convenience function to retrieve some permissions information for the given course calendar. 1300 * 1301 * @param int $courseid Course to check, empty for site. 1302 * @return array The access information 1303 * @throws moodle_exception 1304 * @since Moodle 3.7 1305 */ 1306 public static function get_calendar_access_information($courseid = 0) { 1307 1308 $params = self::validate_parameters(self::get_calendar_access_information_parameters(), ['courseid' => $courseid]); 1309 1310 if (empty($params['courseid']) || $params['courseid'] == SITEID) { 1311 $context = \context_system::instance(); 1312 } else { 1313 $context = \context_course::instance($params['courseid']); 1314 } 1315 1316 self::validate_context($context); 1317 1318 return [ 1319 'canmanageentries' => has_capability('moodle/calendar:manageentries', $context), 1320 'canmanageownentries' => has_capability('moodle/calendar:manageownentries', $context), 1321 'canmanagegroupentries' => has_capability('moodle/calendar:managegroupentries', $context), 1322 'warnings' => [], 1323 ]; 1324 } 1325 1326 /** 1327 * Returns description of method result value. 1328 * 1329 * @return \core_external\external_description. 1330 * @since Moodle 3.7 1331 */ 1332 public static function get_calendar_access_information_returns() { 1333 1334 return new external_single_structure( 1335 [ 1336 'canmanageentries' => new external_value(PARAM_BOOL, 'Whether the user can manage entries.'), 1337 'canmanageownentries' => new external_value(PARAM_BOOL, 'Whether the user can manage its own entries.'), 1338 'canmanagegroupentries' => new external_value(PARAM_BOOL, 'Whether the user can manage group entries.'), 1339 'warnings' => new external_warnings(), 1340 ] 1341 ); 1342 } 1343 1344 /** 1345 * Returns description of method parameters. 1346 * 1347 * @return external_function_parameters. 1348 * @since Moodle 3.7 1349 */ 1350 public static function get_allowed_event_types_parameters() { 1351 return new external_function_parameters( 1352 [ 1353 'courseid' => new external_value(PARAM_INT, 'Course to check, empty for site.', VALUE_DEFAULT, 0), 1354 ] 1355 ); 1356 } 1357 1358 /** 1359 * Get the type of events a user can create in the given course. 1360 * 1361 * @param int $courseid Course to check, empty for site. 1362 * @return array The types allowed 1363 * @throws moodle_exception 1364 * @since Moodle 3.7 1365 */ 1366 public static function get_allowed_event_types($courseid = 0) { 1367 1368 $params = self::validate_parameters(self::get_allowed_event_types_parameters(), ['courseid' => $courseid]); 1369 1370 if (empty($params['courseid']) || $params['courseid'] == SITEID) { 1371 $context = \context_system::instance(); 1372 } else { 1373 $context = \context_course::instance($params['courseid']); 1374 } 1375 1376 self::validate_context($context); 1377 1378 $allowedeventtypes = array_filter(calendar_get_allowed_event_types($params['courseid'])); 1379 1380 return [ 1381 'allowedeventtypes' => array_keys($allowedeventtypes), 1382 'warnings' => [], 1383 ]; 1384 } 1385 1386 /** 1387 * Returns description of method result value. 1388 * 1389 * @return \core_external\external_description. 1390 * @since Moodle 3.7 1391 */ 1392 public static function get_allowed_event_types_returns() { 1393 1394 return new external_single_structure( 1395 [ 1396 'allowedeventtypes' => new external_multiple_structure( 1397 new external_value(PARAM_NOTAGS, 'Allowed event types to be created in the given course.') 1398 ), 1399 'warnings' => new external_warnings(), 1400 ] 1401 ); 1402 } 1403 1404 /** 1405 * Convert the specified dates into unix timestamps. 1406 * 1407 * @param array $datetimes Array of arrays containing date time details, each in the format: 1408 * ['year' => a, 'month' => b, 'day' => c, 1409 * 'hour' => d (optional), 'minute' => e (optional), 'key' => 'x' (optional)] 1410 * @return array Provided array of dates converted to unix timestamps 1411 * @throws moodle_exception If one or more of the dates provided does not convert to a valid timestamp. 1412 */ 1413 public static function get_timestamps($datetimes) { 1414 $params = self::validate_parameters(self::get_timestamps_parameters(), ['data' => $datetimes]); 1415 1416 $type = \core_calendar\type_factory::get_calendar_instance(); 1417 $timestamps = ['timestamps' => []]; 1418 1419 foreach ($params['data'] as $key => $datetime) { 1420 $hour = $datetime['hour'] ?? 0; 1421 $minute = $datetime['minute'] ?? 0; 1422 1423 try { 1424 $timestamp = $type->convert_to_timestamp( 1425 $datetime['year'], $datetime['month'], $datetime['day'], $hour, $minute); 1426 1427 $timestamps['timestamps'][] = [ 1428 'key' => $datetime['key'] ?? $key, 1429 'timestamp' => $timestamp, 1430 ]; 1431 1432 } catch (Exception $e) { 1433 throw new moodle_exception('One or more of the dates provided were invalid'); 1434 } 1435 } 1436 1437 return $timestamps; 1438 } 1439 1440 /** 1441 * Describes the parameters for get_timestamps. 1442 * 1443 * @return external_function_parameters 1444 */ 1445 public static function get_timestamps_parameters() { 1446 return new external_function_parameters ([ 1447 'data' => new external_multiple_structure( 1448 new external_single_structure( 1449 [ 1450 'key' => new external_value(PARAM_ALPHANUMEXT, 'key', VALUE_OPTIONAL), 1451 'year' => new external_value(PARAM_INT, 'year'), 1452 'month' => new external_value(PARAM_INT, 'month'), 1453 'day' => new external_value(PARAM_INT, 'day'), 1454 'hour' => new external_value(PARAM_INT, 'hour', VALUE_OPTIONAL), 1455 'minute' => new external_value(PARAM_INT, 'minute', VALUE_OPTIONAL), 1456 ] 1457 ) 1458 ) 1459 ]); 1460 } 1461 1462 /** 1463 * Describes the timestamps return format. 1464 * 1465 * @return external_single_structure 1466 */ 1467 public static function get_timestamps_returns() { 1468 return new external_single_structure( 1469 [ 1470 'timestamps' => new external_multiple_structure( 1471 new external_single_structure( 1472 [ 1473 'key' => new external_value(PARAM_ALPHANUMEXT, 'Timestamp key'), 1474 'timestamp' => new external_value(PARAM_INT, 'Unix timestamp'), 1475 ] 1476 ) 1477 ) 1478 ] 1479 ); 1480 } 1481 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
