Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.7.x will end 11 May 2020 (12 months).
  • Bug fixes for security issues in 3.7.x will end 9 November 2020 (18 months) - Support has ended.
  • minimum PHP 7.1.0 Note: minimum PHP version has increased since Moodle 3.6. PHP 7.2.x and 7.3.x are supported too. PHP 7.x could have some engine limitations.
  • /calendar/ -> lib.php (source)

    Differences Between: [Versions 35 and 37] [Versions 36 and 37] [Versions 37 and 310] [Versions 37 and 311] [Versions 37 and 38] [Versions 37 and 39]

    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: 3881 lines (153 kb)
    Included or required:0 times
    Referenced: 38 times
    Includes or requires: 0 files

    Defines 2 classes

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

    calendar_information:: (62 methods):
      __construct()
      create()
      set_time()
      prepare_for_view()
      set_sources()
      checkdate()
      timestamp_today()
      timestamp_tomorrow()
      add_sidecalendar_blocks()
      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_view_event_allowed()
      calendar_edit_event_allowed()
      calendar_delete_event_allowed()
      calendar_get_default_courses()
      calendar_format_event_time()
      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_process_subscription_row()
      calendar_delete_subscription()
      calendar_get_icalendar()
      calendar_import_icalendar_events()
      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()


    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.

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

    __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.

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

    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.

    return: bool event updated
    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.

    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.

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

    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.

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

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

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

    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.

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

    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.

    return: calendar_event|bool The event object or false if it failed
    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.

    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.

    return: calendar_information
    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

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

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

    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

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

    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)

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

    return: array $events of selected events or an empty array if there aren't any (or there was an error)
    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

    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.

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

    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.

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

    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]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    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.

    return: moodle_url|null $linkbase
    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,

    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.

    return: string HTML string.
    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,

    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.

    return: string HTML string.
    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,

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

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

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

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

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

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

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

    return: void
    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: global, course, user, or group)
    param: array $courses list of courses

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

    return: array An array of courses, groups, and user to load calendar events for based upon filters
    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.

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

    return: boolean
    param: calendar_event $event event object

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

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

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

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

    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.

    return: array $courses Array of courses 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.

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

    return: string $eventtime link/string for event 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

    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.

    return: bool True if the tyep should be displayed false otherwise
    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

    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.

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

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

    return: bool has the capability to add event
    param: stdClass $event object of 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.

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

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

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

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

    return: int Code: CALENDAR_IMPORT_EVENT_UPDATED = updated,  CALENDAR_IMPORT_EVENT_INSERTED = inserted, 0 = error
    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

    calendar_process_subscription_row($subscriptionid, $pollinterval, $action)   X-Ref
    Update a subscription from the form data in one of the rows in the existing subscriptions table.

    return: string A log of the import progress, including errors
    param: int $subscriptionid The ID of the subscription we are acting upon.
    param: int $pollinterval The poll interval to use.
    param: int $action The action to be performed. One of update or remove.

    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.

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

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

    return: string A log of the import progress, including errors.
    param: iCalendar $ical The iCalendar object.
    param: int $unused Deprecated
    param: int $subscriptionid The subscription ID.

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

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

    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.

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

    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.

    return: context instance
    param: stdClass $subscription

    core_calendar_user_preferences()   X-Ref
    Implements callback user_preferences, whitelists 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

    return: array $events of selected events or an empty array if there aren't any (or there was an error)
    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.

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

    return: array[array, string]
    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.

    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.

    return: int     The timestamp
    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.

    calendar_get_footer_options($calendar)   X-Ref
    Get the calendar footer options.

    return: array The data for template and template name.
    param: calendar_information $calendar The calendar information object.

    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.

    return: bool
    param: string $type

    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.

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

    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