Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/calendar/ -> lib.php (source)

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Calendar extension

Copyright: 2004 Greek School Network (http://www.sch.gr), Jon Papaioannou,
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 4029 lines (157 kb)
Included or required:0 times
Referenced: 32 times
Includes or requires: 0 files

Defines 2 classes

calendar_event:: (17 methods):
  __construct()
  __set()
  __get()
  __isset()
  calculate_context()
  get_context()
  get_editoroptions()
  get_description()
  count_repeats()
  update()
  delete()
  properties()
  toggle_visibility()
  load()
  create()
  format_external_name()
  format_external_text()

calendar_information:: (69 methods):
  __construct()
  create()
  set_time()
  prepare_for_view()
  set_sources()
  checkdate()
  timestamp_today()
  timestamp_tomorrow()
  add_sidecalendar_blocks()
  get_viewmode()
  set_viewmode()
  calendar_get_events()
  calendar_get_days()
  calendar_get_subscription()
  calendar_get_starting_weekday()
  calendar_get_courselink()
  calendar_get_module_cached()
  calendar_get_course_cached()
  calendar_get_group_cached()
  calendar_add_event_metadata()
  calendar_get_events_by_id()
  calendar_top_controls()
  calendar_day_representation()
  calendar_time_representation()
  calendar_get_link_href()
  calendar_get_link_previous()
  calendar_get_link_next()
  calendar_days_in_month()
  calendar_add_month()
  calendar_sub_month()
  calendar_events_by_day()
  calendar_set_filters()
  calendar_can_manage_non_user_event_in_system()
  calendar_view_event_allowed()
  calendar_edit_event_allowed()
  calendar_can_manage_user_event()
  calendar_delete_event_allowed()
  calendar_get_default_courses()
  calendar_format_event_time()
  calendar_format_event_location()
  calendar_show_event_type()
  calendar_set_event_type_display()
  calendar_get_allowed_types()
  calendar_user_can_add_event()
  calendar_add_event_allowed()
  calendar_get_pollinterval_choices()
  calendar_get_eventtype_choices()
  calendar_add_subscription()
  calendar_add_icalendar_event()
  calendar_delete_subscription()
  calendar_get_icalendar()
  calendar_import_events_from_ical()
  calendar_update_subscription_events()
  calendar_update_subscription()
  calendar_can_edit_subscription()
  calendar_get_calendar_context()
  core_calendar_user_preferences()
  calendar_get_legacy_events()
  calendar_get_view()
  calendar_output_fragment_event_form()
  calendar_get_timestamp()
  calendar_get_footer_options()
  calendar_get_filter_types()
  calendar_is_valid_eventtype()
  calendar_get_allowed_event_types()
  calendar_internal_update_course_and_group_permission()
  calendar_get_export_token()
  calendar_get_export_import_link_params()
  calendar_inplace_editable()


Class: calendar_event  - X-Ref

Manage calendar events.

This class provides the required functionality in order to manage calendar events.
It was introduced as part of Moodle 2.0 and was created in order to provide a
better framework for dealing with calendar events in particular regard to file
handling through the new file API.

__construct($data = null)   X-Ref
Instantiates a new event and optionally populates its properties with the data provided.

param: \stdClass $data Optional. An object containing the properties to for

__set($key, $value)   X-Ref
Magic set method.

Attempts to call a set_$key method if one exists otherwise falls back
to simply set the property.

param: string $key property name
param: mixed $value value of the property

__get($key)   X-Ref
Magic get method.

Attempts to call a get_$key method to return the property and ralls over
to return the raw property.

param: string $key property name
return: mixed property value

__isset($key)   X-Ref
Magic isset method.

PHP needs an isset magic method if you use the get magic method and
still want empty calls to work.

param: string $key $key property name
return: bool|mixed property value, false if property is not exist

calculate_context()   X-Ref
Calculate the context value needed for an event.

Event's type can be determine by the available value store in $data
It is important to check for the existence of course/courseid to determine
the course event.
Default value is set to CONTEXT_USER

return: \stdClass The context object.

get_context()   X-Ref
Returns the context for this event. The context is calculated
the first time is is requested and then stored in a member
variable to be returned each subsequent time.

This is a magical getter function that will be called when
ever the context property is accessed, e.g. $event->context.

return: context

get_editoroptions()   X-Ref
Returns an array of editoroptions for this event.

return: array event editor options

get_description()   X-Ref
Returns an event description: Called by __get
Please use $blah = $event->description;

return: string event description

count_repeats()   X-Ref
Return the number of repeat events there are in this events series.

return: int number of event repeated

update($data, $checkcapability=true)   X-Ref
Update or create an event within the database

Pass in a object containing the event properties and this function will
insert it into the database and deal with any associated files

Capability checking should be performed if the user is directly manipulating the event
and no other capability has been tested. However if the event is not being manipulated
directly by the user and another capability has been checked for them to do this then
capabilites should not be checked.

For example if a user is editing an event in the calendar the check should be true,
but if you are updating an event in an activities settings are changed then the calendar
capabilites should not be checked.

param: \stdClass $data object of event
param: bool $checkcapability If Moodle should check the user can manage the calendar events for this call or not.
return: bool event updated

delete($deleterepeated = false)   X-Ref
Deletes an event and if selected an repeated events in the same series

This function deletes an event, any associated events if $deleterepeated=true,
and cleans up any files associated with the events.

param: bool $deleterepeated  delete event repeatedly
return: bool succession of deleting event

properties($prepareeditor = false)   X-Ref
Fetch all event properties.

This function returns all of the events properties as an object and optionally
can prepare an editor for the description field at the same time. This is
designed to work when the properties are going to be used to set the default
values of a moodle forms form.

param: bool $prepareeditor If set to true a editor is prepared for use with
return: \stdClass Object containing event properties

toggle_visibility($force = null)   X-Ref
Toggles the visibility of an event

param: null|bool $force If it is left null the events visibility is flipped,
return: bool if event is successfully updated, toggle will be visible

load($param)   X-Ref
Returns an event object when provided with an event id.

This function makes use of MUST_EXIST, if the event id passed in is invalid
it will result in an exception being thrown.

param: int|object $param event object or event id
return: calendar_event

create($properties, $checkcapability = true)   X-Ref
Creates a new event and returns an event object.

Capability checking should be performed if the user is directly creating the event
and no other capability has been tested. However if the event is not being created
directly by the user and another capability has been checked for them to do this then
capabilites should not be checked.

For example if a user is creating an event in the calendar the check should be true,
but if you are creating an event in an activity when it is created then the calendar
capabilites should not be checked.

param: \stdClass|array $properties An object containing event properties
param: bool $checkcapability If Moodle should check the user can manage the calendar events for this call or not.
return: calendar_event|bool The event object or false if it failed

format_external_name()   X-Ref
Format the event name using the external API.

This function should we used when text formatting is required in external functions.

return: string Formatted name.

format_external_text()   X-Ref
Format the text using the external API.

This function should we used when text formatting is required in external functions.

return: array an array containing the text formatted and the text format

Class: calendar_information  - X-Ref

Calendar information class

This class is used simply to organise the information pertaining to a calendar
and is used primarily to make information easily available.

__construct($day = 0, $month = 0, $year = 0, $time = 0)   X-Ref
Creates a new instance

param: int $day the number of the day
param: int $month the number of the month
param: int $year the number of the year
param: int $time the unixtimestamp representing the date we want to view, this is used instead of $calmonth

create($time, int $courseid, int $categoryid = null)   X-Ref
Creates and set up a instance.

param: int                     $time the unixtimestamp representing the date we want to view.
param: int                     $courseid The ID of the course the user wishes to view.
param: int                     $categoryid The ID of the category the user wishes to view
return: calendar_information

set_time($time = null)   X-Ref
Set the time period of this instance.

param: int $time the unixtimestamp representing the date we want to view.
return: $this

prepare_for_view(stdClass $course, array $coursestoload, $ignorefilters = false)   X-Ref
Initialize calendar information

param: stdClass $course object
param: array $coursestoload An array of courses [$course->id => $course]
param: bool $ignorefilters options to use filter

set_sources(stdClass $course, array $courses, stdClass $category = null)   X-Ref
Set the sources for events within the calendar.

If no category is provided, then the category path for the current
course will be used.

param: stdClass    $course The current course being viewed.
param: stdClass[]  $courses The list of all courses currently accessible.
param: stdClass    $category The current category to show.

checkdate($defaultonow = true)   X-Ref
Ensures the date for the calendar is correct and either sets it to now
or throws a moodle_exception if not

param: bool $defaultonow use current time
return: bool validation of checkdate

timestamp_today()   X-Ref
Gets todays timestamp for the calendar

return: int today timestamp

timestamp_tomorrow()   X-Ref
Gets tomorrows timestamp for the calendar

return: int tomorrow timestamp

add_sidecalendar_blocks(core_calendar_renderer $renderer, $showfilters=false, $view=null)   X-Ref
Adds the pretend blocks for the calendar

param: core_calendar_renderer $renderer
param: bool $showfilters display filters, false is set as default
param: string|null $view preference view options (eg: day, month, upcoming)

get_viewmode()   X-Ref
Getter method for the calendar's view mode.

return: string

set_viewmode(string $viewmode)   X-Ref
Setter method for the calendar's view mode.

param: string $viewmode

calendar_get_events($tstart, $tend, $users, $groups, $courses,$withduration = true, $ignorehidden = true, $categories = [])   X-Ref
Get calendar events.

param: int $tstart Start time of time range for events
param: int $tend End time of time range for events
param: array|int|boolean $users array of users, user id or boolean for all/no user events
param: array|int|boolean $groups array of groups, group id or boolean for all/no group events
param: array|int|boolean $courses array of courses, course id or boolean for all/no course events
param: boolean $withduration whether only events starting within time range selected
param: boolean $ignorehidden whether to select only visible events or all events
param: array|int|boolean $categories array of categories, category id or boolean for all/no course events
return: array $events of selected events or an empty array if there aren't any (or there was an error)

calendar_get_days()   X-Ref
Return the days of the week.

return: array array of days

calendar_get_subscription($id)   X-Ref
Get the subscription from a given id.

param: int $id id of the subscription
return: stdClass Subscription record from DB

calendar_get_starting_weekday()   X-Ref
Gets the first day of the week.

Used to be define('CALENDAR_STARTING_WEEKDAY', blah);

return: int

calendar_get_courselink($course)   X-Ref
Get a HTML link to a course.

param: int|stdClass $course the course id or course object
return: string a link to the course (as HTML); empty if the course id is invalid

calendar_get_module_cached(&$modulecache, $modulename, $instance)   X-Ref
Get current module cache.

Only use this method if you do not know courseid. Otherwise use:
get_fast_modinfo($courseid)->instances[$modulename][$instance]

param: array $modulecache in memory module cache
param: string $modulename name of the module
param: int $instance module instance number
return: stdClass|bool $module information

calendar_get_course_cached(&$coursecache, $courseid)   X-Ref
Get current course cache.

param: array $coursecache list of course cache
param: int $courseid id of the course
return: stdClass $coursecache[$courseid] return the specific course cache

calendar_get_group_cached($groupid)   X-Ref
Get group from groupid for calendar display

param: int $groupid
return: stdClass group object with fields 'id', 'name' and 'courseid'

calendar_add_event_metadata($event)   X-Ref
Add calendar event metadata

param: stdClass $event event info
return: stdClass $event metadata

calendar_get_events_by_id($eventids)   X-Ref
Get calendar events by id.

param: array $eventids list of event ids
return: array Array of event entries, empty array if nothing found

calendar_top_controls($type, $data)   X-Ref
Get control options for calendar.

param: string $type of calendar
param: array $data calendar information
return: string $content return available control for the calender in html

calendar_day_representation($tstamp, $now = false, $usecommonwords = true)   X-Ref
Return the representation day.

param: int $tstamp Timestamp in GMT
param: int|bool $now current Unix timestamp
param: bool $usecommonwords
return: string the formatted date/time

calendar_time_representation($time)   X-Ref
return the formatted representation time.

param: int $time the timestamp in UTC, as obtained from the database
return: string the formatted date/time

calendar_get_link_href($linkbase, $d, $m, $y, $time = 0)   X-Ref
Adds day, month, year arguments to a URL and returns a moodle_url object.

param: string|moodle_url $linkbase
param: int $d The number of the day.
param: int $m The number of the month.
param: int $y The number of the year.
param: int $time the unixtime, used for multiple calendar support. The values $d,
return: moodle_url|null $linkbase

calendar_get_link_previous($text, $linkbase, $d, $m, $y, $accesshide = false, $time = 0)   X-Ref
Build and return a previous month HTML link, with an arrow.

param: string $text The text label.
param: string|moodle_url $linkbase The URL stub.
param: int $d The number of the date.
param: int $m The number of the month.
param: int $y year The number of the year.
param: bool $accesshide Default visible, or hide from all except screenreaders.
param: int $time the unixtime, used for multiple calendar support. The values $d,
return: string HTML string.

calendar_get_link_next($text, $linkbase, $d, $m, $y, $accesshide = false, $time = 0)   X-Ref
Build and return a next month HTML link, with an arrow.

param: string $text The text label.
param: string|moodle_url $linkbase The URL stub.
param: int $d the number of the Day
param: int $m The number of the month.
param: int $y The number of the year.
param: bool $accesshide Default visible, or hide from all except screenreaders.
param: int $time the unixtime, used for multiple calendar support. The values $d,
return: string HTML string.

calendar_days_in_month($month, $year)   X-Ref
Return the number of days in month.

param: int $month the number of the month.
param: int $year the number of the year
return: int

calendar_add_month($month, $year)   X-Ref
Get the next following month.

param: int $month the number of the month.
param: int $year the number of the year.
return: array the following month

calendar_sub_month($month, $year)   X-Ref
Get the previous month.

param: int $month the number of the month.
param: int $year the number of the year.
return: array previous month

calendar_events_by_day($events, $month, $year, &$eventsbyday, &$durationbyday, &$typesbyday, &$courses)   X-Ref
Get per-day basis events

param: array $events list of events
param: int $month the number of the month
param: int $year the number of the year
param: array $eventsbyday event on specific day
param: array $durationbyday duration of the event in days
param: array $typesbyday event type (eg: site, course, user, or group)
param: array $courses list of courses
return: void

calendar_set_filters(array $courseeventsfrom, $ignorefilters = false, stdClass $user = null)   X-Ref
Returns the courses to load events for.

param: array $courseeventsfrom An array of courses to load calendar events for
param: bool $ignorefilters specify the use of filters, false is set as default
param: stdClass $user The user object. This defaults to the global $USER object.
return: array An array of courses, groups, and user to load calendar events for based upon filters

calendar_can_manage_non_user_event_in_system($event)   X-Ref
Can current user manage a non user event in system context.

param: calendar_event|stdClass $event event object
return: boolean

calendar_view_event_allowed(calendar_event $event)   X-Ref
Return the capability for viewing a calendar event.

param: calendar_event $event event object
return: boolean

calendar_edit_event_allowed($event, $manualedit = false)   X-Ref
Return the capability for editing calendar event.

param: calendar_event $event event object
param: bool $manualedit is the event being edited manually by the user
return: bool capability to edit event

calendar_can_manage_user_event($event)   X-Ref
Can current user edit/delete/add an user event?

param: calendar_event|stdClass $event event object
return: bool

calendar_delete_event_allowed($event)   X-Ref
Return the capability for deleting a calendar event.

param: calendar_event $event The event object
return: bool Whether the user has permission to delete the event or not.

calendar_get_default_courses($courseid = null, $fields = '*', $canmanage = false, int $userid = null)   X-Ref
Returns the default courses to display on the calendar when there isn't a specific
course to display.

param: int $courseid (optional) If passed, an additional course can be returned for admins (the current course).
param: string $fields Comma separated list of course fields to return.
param: bool $canmanage If true, this will return the list of courses the user can create events in, rather
param: int $userid (optional) The user which this function returns the default courses for.
return: array $courses Array of courses to display

calendar_format_event_time($event, $now, $linkparams = null, $usecommonwords = true, $showtime = 0)   X-Ref
Get event format time.

param: calendar_event $event event object
param: int $now current time in gmt
param: array $linkparams list of params for event link
param: bool $usecommonwords the words as formatted date/time.
param: int $showtime determine the show time GMT timestamp
return: string $eventtime link/string for event time

calendar_format_event_location(calendar_event $event)   X-Ref
Format event location property

param: calendar_event $event
return: string

calendar_show_event_type($type, $user = null)   X-Ref
Checks to see if the requested type of event should be shown for the given user.

param: int $type The type to check the display for (default is to display all)
param: stdClass|int|null $user The user to check for - by default the current user
return: bool True if the tyep should be displayed false otherwise

calendar_set_event_type_display($type, $display = null, $user = null)   X-Ref
Sets the display of the event type given $display.

If $display = true the event type will be shown.
If $display = false the event type will NOT be shown.
If $display = null the current value will be toggled and saved.

param: int $type object of CALENDAR_EVENT_XXX
param: bool $display option to display event type
param: stdClass|int $user moodle user object or id, null means current user

calendar_get_allowed_types(&$allowed, $course = null, $groups = null, $category = null)   X-Ref
Get calendar's allowed types.

param: stdClass $allowed list of allowed edit for event  type
param: stdClass|int $course object of a course or course id
param: array $groups array of groups for the given course
param: stdClass|int $category object of a category

calendar_user_can_add_event($course)   X-Ref
See if user can add calendar entries at all used to print the "New Event" button.

param: stdClass $course object of a course or course id
return: bool has the capability to add at least one event type

calendar_add_event_allowed($event)   X-Ref
Check wether the current user is permitted to add events.

param: stdClass $event object of event
return: bool has the capability to add event

calendar_get_pollinterval_choices()   X-Ref
Returns option list for the poll interval setting.

return: array An array of poll interval options. Interval => description.

calendar_get_eventtype_choices($courseid)   X-Ref
Returns option list of available options for the calendar event type, given the current user and course.

param: int $courseid The id of the course
return: array An array containing the event types the user can create.

calendar_add_subscription($sub)   X-Ref
Add an iCalendar subscription to the database.

param: stdClass $sub The subscription object (e.g. from the form)
return: int The insert ID, if any.

calendar_add_icalendar_event($event, $unused, $subscriptionid, $timezone='UTC')   X-Ref
Add an iCalendar event to the Moodle calendar.

param: stdClass $event The RFC-2445 iCalendar event
param: int $unused Deprecated
param: int $subscriptionid The iCalendar subscription ID
param: string $timezone The X-WR-TIMEZONE iCalendar property if provided
return: int Code: CALENDAR_IMPORT_EVENT_UPDATED = updated,  CALENDAR_IMPORT_EVENT_INSERTED = inserted, 0 = error

calendar_delete_subscription($subscription)   X-Ref
Delete subscription and all related events.

param: int|stdClass $subscription subscription or it's id, which needs to be deleted.

calendar_get_icalendar($url)   X-Ref
From a URL, fetch the calendar and return an iCalendar object.

param: string $url The iCalendar URL
return: iCalendar The iCalendar object

calendar_import_events_from_ical(iCalendar $ical, int $subscriptionid = null)   X-Ref
Import events from an iCalendar object into a course calendar.

param: iCalendar $ical The iCalendar object.
param: int|null $subscriptionid The subscription ID.
return: array A log of the import progress, including errors.

calendar_update_subscription_events($subscriptionid)   X-Ref
Fetch a calendar subscription and update the events in the calendar.

param: int $subscriptionid The course ID for the calendar.
return: string A log of the import progress, including errors.

calendar_update_subscription($subscription)   X-Ref
Update a calendar subscription. Also updates the associated cache.

param: stdClass|array $subscription Subscription record.

calendar_can_edit_subscription($subscriptionorid)   X-Ref
Checks to see if the user can edit a given subscription feed.

param: mixed $subscriptionorid Subscription object or id
return: bool true if current user can edit the subscription else false

calendar_get_calendar_context($subscription)   X-Ref
Helper function to determine the context of a calendar subscription.
Subscriptions can be created in two contexts COURSE, or USER.

param: stdClass $subscription
return: context instance

core_calendar_user_preferences()   X-Ref
Implements callback user_preferences, lists preferences that users are allowed to update directly

Used in {@see core_user::fill_preferences_cache()}, see also {@see useredit_update_user_preference()}

return: array

calendar_get_legacy_events($tstart, $tend, $users, $groups, $courses,$withduration = true, $ignorehidden = true, $categories = [], $limitnum = 0)   X-Ref
Get legacy calendar events

param: int $tstart Start time of time range for events
param: int $tend End time of time range for events
param: array|int|boolean $users array of users, user id or boolean for all/no user events
param: array|int|boolean $groups array of groups, group id or boolean for all/no group events
param: array|int|boolean $courses array of courses, course id or boolean for all/no course events
param: boolean $withduration whether only events starting within time range selected
param: boolean $ignorehidden whether to select only visible events or all events
param: array $categories array of category ids and/or objects.
param: int $limitnum Number of events to fetch or zero to fetch all.
return: array $events of selected events or an empty array if there aren't any (or there was an error)

calendar_get_view(\calendar_information $calendar, $view, $includenavigation = true, bool $skipevents = false,?int $lookahead = null)   X-Ref
Get the calendar view output.

param: \calendar_information $calendar The calendar being represented
param: string  $view The type of calendar to have displayed
param: bool    $includenavigation Whether to include navigation
param: bool    $skipevents Whether to load the events or not
param: int     $lookahead Overwrites site and users's lookahead setting.
return: array[array, string]

calendar_output_fragment_event_form($args)   X-Ref
No description

calendar_get_timestamp($d, $m, $y, $time = 0)   X-Ref
Calculate the timestamp from the supplied Gregorian Year, Month, and Day.

param: int     $d The day
param: int     $m The month
param: int     $y The year
param: int     $time The timestamp to use instead of a separate y/m/d.
return: int     The timestamp

calendar_get_footer_options($calendar, array $options = [])   X-Ref
Get the calendar footer options.

param: calendar_information $calendar The calendar information object.
param: array $options Display options for the footer. If an option is not set, a default value will be provided.
return: array The data for template and template name.

calendar_get_filter_types()   X-Ref
Get the list of potential calendar filter types as a type => name
combination.

return: array

calendar_is_valid_eventtype($type)   X-Ref
Check whether the specified event type is valid.

param: string $type
return: bool

calendar_get_allowed_event_types(int $courseid = null)   X-Ref
Get event types the user can create event based on categories, courses and groups
the logged in user belongs to.

param: int|null $courseid The course id.
return: array The array of allowed types.

calendar_internal_update_course_and_group_permission(int $courseid, context $context, array &$types)   X-Ref
Given a course id, and context, updates the permission types array to add the 'course' or 'group'
permission if it is relevant for that course.

For efficiency, if they already have 'course' or 'group' then it skips checks.

Do not call this function directly, it is only for use by calendar_get_allowed_event_types().

param: int $courseid Course id
param: context $context Context for that course
param: array $types Current permissions

calendar_get_export_token(stdClass $user)   X-Ref
Get the auth token for exporting the given user calendar.

param: stdClass $user The user to export the calendar for
return: string The export token.

calendar_get_export_import_link_params()   X-Ref
Get the list of URL parameters for calendar expport and import links.

return: array

calendar_inplace_editable(string $itemtype, int $itemid, int $newvalue)   X-Ref
Implements the inplace editable feature.

param: string $itemtype Type of the inplace editable element
param: int $itemid Id of the item to edit
param: int $newvalue New value of the item
return: \core\output\inplace_editable