MDL-55188 events: Final deprecation events_trigger.
[moodle.git] / lib / eventslib.php
CommitLineData
0856223c 1<?php
117bd748
PS
2// This file is part of Moodle - http://moodle.org/
3//
11e1f828
MH
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.
117bd748 13//
11e1f828
MH
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
0856223c 17/**
18 * Library of functions for events manipulation.
117bd748 19 *
583e93ca 20 * The public API is all at the end of this file.
d77717d7 21 *
ef6cf871 22 * @package core
1d1719f5
SH
23 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
0856223c 25 */
26
78bfb562
PS
27defined('MOODLE_INTERNAL') || die();
28
0856223c 29/**
30 * Gets the capabilities that have been cached in the database for this
31 * component.
d77717d7 32 *
ef6cf871 33 * @access protected To be used from eventslib only
11e1f828 34 *
650462df 35 * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
11e1f828 36 * @return array of events
0856223c 37 */
d46306de 38function events_get_cached($component) {
25c6a19d 39 global $DB;
40
d46306de 41 $cachedhandlers = array();
42
650462df 43 if ($storedhandlers = $DB->get_records('events_handlers', array('component'=>$component))) {
d46306de 44 foreach ($storedhandlers as $handler) {
45 $cachedhandlers[$handler->eventname] = array (
46 'id' => $handler->id,
47 'handlerfile' => $handler->handlerfile,
48 'handlerfunction' => $handler->handlerfunction,
650462df
PS
49 'schedule' => $handler->schedule,
50 'internal' => $handler->internal);
0856223c 51 }
0856223c 52 }
0856223c 53
d46306de 54 return $cachedhandlers;
d77717d7 55}
0856223c 56
d46306de 57/**
58 * Remove all event handlers and queued events
11e1f828 59 *
1d1719f5 60 * @category event
650462df 61 * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
d46306de 62 */
63function events_uninstall($component) {
64 $cachedhandlers = events_get_cached($component);
65 events_cleanup($component, $cachedhandlers);
650462df
PS
66
67 events_get_handlers('reset');
d46306de 68}
69
0856223c 70/**
71 * Deletes cached events that are no longer needed by the component.
d77717d7 72 *
ef6cf871 73 * @access protected To be used from eventslib only
11e1f828 74 *
650462df 75 * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
d6e7a057 76 * @param array $cachedhandlers array of the cached events definitions that will be
650462df 77 * @return int number of unused handlers that have been removed
0856223c 78 */
d46306de 79function events_cleanup($component, $cachedhandlers) {
25c6a19d 80 global $DB;
81
0856223c 82 $deletecount = 0;
d46306de 83 foreach ($cachedhandlers as $eventname => $cachedhandler) {
25c6a19d 84 if ($qhandlers = $DB->get_records('events_queue_handlers', array('handlerid'=>$cachedhandler['id']))) {
650462df 85 //debugging("Removing pending events from queue before deleting of event handler: $component - $eventname");
d46306de 86 foreach ($qhandlers as $qhandler) {
87 events_dequeue($qhandler);
88 }
89 }
650462df
PS
90 $DB->delete_records('events_handlers', array('eventname'=>$eventname, 'component'=>$component));
91 $deletecount++;
0856223c 92 }
650462df 93
0856223c 94 return $deletecount;
95}
96
d46306de 97/**
d6e7a057 98 * Removes this queued handler from the events_queued_handler table
11e1f828 99 *
d6e7a057 100 * Removes events_queue record from events_queue if no more references to this event object exists
d46306de 101 *
ef6cf871 102 * @access protected To be used from eventslib only
11e1f828 103 *
ef6cf871 104 * @param stdClass $qhandler A row from the events_queued_handler table
d46306de 105 */
106function events_dequeue($qhandler) {
25c6a19d 107 global $DB;
108
d46306de 109 // first delete the queue handler
25c6a19d 110 $DB->delete_records('events_queue_handlers', array('id'=>$qhandler->id));
8aaf935a 111
d46306de 112 // if no more queued handler is pointing to the same event - delete the event too
25c6a19d 113 if (!$DB->record_exists('events_queue_handlers', array('queuedeventid'=>$qhandler->queuedeventid))) {
114 $DB->delete_records('events_queue', array('id'=>$qhandler->queuedeventid));
d46306de 115 }
8aaf935a 116}
117
1336c96e 118/**
d6e7a057 119 * Returns handlers for given event. Uses caching for better perf.
1336c96e 120 *
ef6cf871 121 * @access protected To be used from eventslib only
11e1f828 122 *
11e1f828 123 * @staticvar array $handlers
ef6cf871 124 * @param string $eventname name of event or 'reset'
1d1719f5 125 * @return array|false array of handlers or false otherwise
1336c96e 126 */
127function events_get_handlers($eventname) {
a2d51ba8 128 global $DB;
1336c96e 129 static $handlers = array();
130
650462df 131 if ($eventname === 'reset') {
1336c96e 132 $handlers = array();
133 return false;
134 }
d46306de 135
1336c96e 136 if (!array_key_exists($eventname, $handlers)) {
137 $handlers[$eventname] = $DB->get_records('events_handlers', array('eventname'=>$eventname));
138 }
139
140 return $handlers[$eventname];
141}