WebSVN – Moodle – /calendar/classes/local/api.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Contains class containing the internal calendar API.
 *
 * @package    core_calendar
 * @copyright  2017 Ryan Wyllie <ryan@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core_calendar\local;

defined('MOODLE_INTERNAL') || die();

use core_calendar\local\event\container;
use core_calendar\local\event\entities\event_interface;
use core_calendar\local\event\exceptions\limit_invalid_parameter_exception;

/**
 * Class containing the local calendar API.
 *
 * This should not be used outside of core_calendar.
 *
 * @package    core_calendar
 * @copyright  2017 Ryan Wyllie <ryan@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class api {
    /**
     * Get all events restricted by various parameters, taking in to account user and group overrides.
     *
     * @param int|null      $timestartfrom         Events with timestart from this value (inclusive).
     * @param int|null      $timestartto           Events with timestart until this value (inclusive).
     * @param int|null      $timesortfrom          Events with timesort from this value (inclusive).
     * @param int|null      $timesortto            Events with timesort until this value (inclusive).
     * @param int|null      $timestartaftereventid Restrict the events in the timestart range to ones after this ID.
     * @param int|null      $timesortaftereventid  Restrict the events in the timesort range to ones after this ID.
     * @param int           $limitnum              Return at most this number of events.
     * @param int|null      $type                  Return only events of this type.
     * @param array|null    $usersfilter           Return only events for these users.
     * @param array|null    $groupsfilter          Return only events for these groups.
     * @param array|null    $coursesfilter         Return only events for these courses.
     * @param bool          $withduration          If true return only events starting within specified
     *                                             timestart otherwise return in progress events as well.
     * @param bool          $ignorehidden          If true don't return hidden events.
     * @return \core_calendar\local\event\entities\event_interface[] Array of event_interfaces.
     */
    public static function get_events(
        $timestartfrom = null,
        $timestartto = null,
        $timesortfrom = null,
        $timesortto = null,
        $timestartaftereventid = null,
        $timesortaftereventid = null,
        $limitnum = 20,
        $type = null,
        array $usersfilter = null,
        array $groupsfilter = null,
        array $coursesfilter = null,
        array $categoriesfilter = null,
        $withduration = true,
        $ignorehidden = true,
        callable $filter = null
    ) {
        global $USER;

        $vault = \core_calendar\local\event\container::get_event_vault();

        $timestartafterevent = null;
        $timesortafterevent = null;

        if ($timestartaftereventid && $event = $vault->get_event_by_id($timestartaftereventid)) {
            $timestartafterevent = $event;
        }

        if ($timesortaftereventid && $event = $vault->get_event_by_id($timesortaftereventid)) {
            $timesortafterevent = $event;
        }

        return $vault->get_events(
            $timestartfrom,
            $timestartto,
            $timesortfrom,
            $timesortto,
            $timestartafterevent,
            $timesortafterevent,
            $limitnum,
            $type,
            $usersfilter,
            $groupsfilter,
            $coursesfilter,
            $categoriesfilter,
            $withduration,
            $ignorehidden,
            $filter
        );
    }

    /**
     * Get a list of action events for the logged in user by the given
     * timesort values.
     *
     * @param int|null $timesortfrom The start timesort value (inclusive)
     * @param int|null $timesortto The end timesort value (inclusive)
     * @param int|null $aftereventid Only return events after this one
     * @param int $limitnum Limit results to this amount (between 1 and 50)
     * @param bool $lmittononsuspendedevents Limit course events to courses the user is active in (not suspended).
     * @param \stdClass|null $user The user id or false for $USER
     * @param string|null $searchvalue The value a user wishes to search against
     * @return array A list of action_event_interface objects
     * @throws \moodle_exception
     */
    public static function get_action_events_by_timesort(
        $timesortfrom = null,
        $timesortto = null,
        $aftereventid = null,
        $limitnum = 20,
        $limittononsuspendedevents = false,
        ?\stdClass $user = null,
        ?string $searchvalue = null
    ) {
        global $USER;

        if (!$user) {
            $user = $USER;
        }

        if (is_null($timesortfrom) && is_null($timesortto)) {
            throw new \moodle_exception("Must provide a timesort to and/or from value");
        }

        if ($limitnum < 1 || $limitnum > 50) {
            throw new \moodle_exception("Limit must be between 1 and 50 (inclusive)");
        }

        \core_calendar\local\event\container::set_requesting_user($user->id);
        $vault = \core_calendar\local\event\container::get_event_vault();

        $afterevent = null;
        if ($aftereventid && $event = $vault->get_event_by_id($aftereventid)) {
            $afterevent = $event;
        }

        return $vault->get_action_events_by_timesort($user, $timesortfrom, $timesortto, $afterevent, $limitnum,
                $limittononsuspendedevents, $searchvalue);
    }

    /**
     * Get a list of action events for the logged in user by the given
     * course and timesort values.
     *
     * @param \stdClass $course The course the events must belong to
     * @param int|null $timesortfrom The start timesort value (inclusive)
     * @param int|null $timesortto The end timesort value (inclusive)
     * @param int|null $aftereventid Only return events after this one
     * @param int $limitnum Limit results to this amount (between 1 and 50)
     * @param string|null $searchvalue The value a user wishes to search against
     * @return array A list of action_event_interface objects
     * @throws limit_invalid_parameter_exception
     */
    public static function get_action_events_by_course(
        $course,
        $timesortfrom = null,
        $timesortto = null,
        $aftereventid = null,
        $limitnum = 20,
        ?string $searchvalue = null
    ) {
        global $USER;

        if ($limitnum < 1 || $limitnum > 50) {
            throw new limit_invalid_parameter_exception(
                "Limit must be between 1 and 50 (inclusive)");
        }

        $vault = \core_calendar\local\event\container::get_event_vault();

        $afterevent = null;
        if ($aftereventid && $event = $vault->get_event_by_id($aftereventid)) {
            $afterevent = $event;
        }

        return $vault->get_action_events_by_course(
            $USER, $course, $timesortfrom, $timesortto, $afterevent, $limitnum, $searchvalue);
    }

    /**
     * Get a list of action events for the logged in user by the given
     * courses and timesort values.
     *
     * The limit number applies per course, not for the result set as a whole.
     * E.g. Requesting 3 courses with a limit of 10 will result in up to 30
     * events being returned (up to 10 per course).
     *
     * @param array $courses The courses the events must belong to
     * @param int|null $timesortfrom The start timesort value (inclusive)
     * @param int|null $timesortto The end timesort value (inclusive)
     * @param int $limitnum Limit results per course to this amount (between 1 and 50)
     * @param string|null $searchvalue The value a user wishes to search against
     * @return array A list of action_event_interface objects indexed by course id
     */
    public static function get_action_events_by_courses(
        $courses = [],
        $timesortfrom = null,
        $timesortto = null,
        $limitnum = 20,
        ?string $searchvalue = null
    ) {
        $return = [];

        foreach ($courses as $course) {
            $return[$course->id] = self::get_action_events_by_course(
                $course,
                $timesortfrom,
                $timesortto,
                null,
                $limitnum,
                $searchvalue
            );
        }

        return $return;
    }

    /**
     * Change the start day for an event. Only the date will be
     * modified, the time of day for the event will be left as is.
     *
     * @param event_interface $event The existing event to modify
     * @param DateTimeInterface $startdate The new date to use for the start day
     * @return event_interface The new event with updated start date
     */
    public static function update_event_start_day(
        event_interface $event,
        \DateTimeInterface $startdate
    ) {
        global $DB;

        $mapper = container::get_event_mapper();
        $legacyevent = $mapper->from_event_to_legacy_event($event);
        $hascoursemodule = !empty($event->get_course_module());
        $moduleinstance = null;
        $starttime = $event->get_times()->get_start_time()->setDate(
            $startdate->format('Y'),
            $startdate->format('n'),
            $startdate->format('j')
        );
        $starttimestamp = $starttime->getTimestamp();

        if ($hascoursemodule) {
            $moduleinstance = $DB->get_record(
                $event->get_course_module()->get('modname'),
                ['id' => $event->get_course_module()->get('instance')],
                '*',
                MUST_EXIST
            );

            // If there is a timestart range callback implemented then we can
            // use the values returned from the valid timestart range to apply
            // some default validation on the event's timestart value to ensure
            // that it falls within the specified range.
            list($min, $max) = component_callback(
                'mod_' . $event->get_course_module()->get('modname'),
                'core_calendar_get_valid_event_timestart_range',
                [$legacyevent, $moduleinstance],
                [false, false]
            );
        } else if ($legacyevent->courseid != 0 && $legacyevent->courseid != SITEID && $legacyevent->groupid == 0) {
            // This is a course event.
            list($min, $max) = component_callback(
                'core_course',
                'core_calendar_get_valid_event_timestart_range',
                [$legacyevent, $event->get_course()->get_proxied_instance()],
                [0, 0]
            );
        } else {
            $min = $max = 0;
        }

        // If the callback returns false for either value it means that
        // there is no valid time start range.
        if ($min === false || $max === false) {
            throw new \moodle_exception('The start day of this event can not be modified');
        }

        if ($min && $starttimestamp < $min[0]) {
            throw new \moodle_exception($min[1]);
        }

        if ($max && $starttimestamp > $max[0]) {
            throw new \moodle_exception($max[1]);
        }

        // This function does our capability checks.
        $legacyevent->update((object) ['timestart' => $starttime->getTimestamp()]);

        // Check that the user is allowed to manually edit calendar events before
        // calling the event updated callback. The manual flag causes the code to
        // check the user has the capabilities to modify the modules.
        //
        // We don't want to call the event update callback if the user isn't allowed
        // to modify course modules because depending on the callback it can make
        // some changes that would be considered security issues, such as updating the
        // due date for an assignment.
        if ($hascoursemodule && calendar_edit_event_allowed($legacyevent, true)) {
            // If this event is from an activity then we need to call
            // the activity callback to let it know that the event it
            // created has been modified so it needs to update accordingly.
            component_callback(
                'mod_' . $event->get_course_module()->get('modname'),
                'core_calendar_event_timestart_updated',
                [$legacyevent, $moduleinstance]
            );

            // Rebuild the course cache to make sure the updated dates are reflected.
            $courseid = $event->get_course()->get('id');
            $cmid = $event->get_course_module()->get('id');
            \course_modinfo::purge_course_module_cache($courseid, $cmid);
            rebuild_course_cache($courseid, true, true);
        }

        return $mapper->from_legacy_event_to_event($legacyevent);
    }
}
Proyectos de Subversion Moodle

(root)/calendar/classes/local/api.php – Rev 1342
