[Summary view]

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  use core_external\external_api;
  18  use core_external\external_format_value;
  19  use core_external\external_function_parameters;
  20  use core_external\external_multiple_structure;
  21  use core_external\external_single_structure;
  22  use core_external\external_value;
  23  
  24  defined('MOODLE_INTERNAL') || die();
  25  
  26  /**
  27   * External message popup API
  28   *
  29   * @package    message_popup
  30   * @category   external
  31   * @copyright  2016 Ryan Wyllie <ryan@moodle.com>
  32   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33   */
  34  
  35  require_once($CFG->dirroot . "/message/lib.php");
  36  
  37  /**
  38   * Message external functions
  39   *
  40   * @package    message_popup
  41   * @category   external
  42   * @copyright  2016 Ryan Wyllie <ryan@moodle.com>
  43   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  44   */
  45  class message_popup_external extends external_api {
  46  
  47      /**
  48       * Get popup notifications parameters description.
  49       *
  50       * @return external_function_parameters
  51       * @since 3.2
  52       */
  53      public static function get_popup_notifications_parameters() {
  54          return new external_function_parameters(
  55              array(
  56                  'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for current user'),
  57                  'newestfirst' => new external_value(
  58                      PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
  59                      VALUE_DEFAULT, true),
  60                  'limit' => new external_value(PARAM_INT, 'the number of results to return', VALUE_DEFAULT, 0),
  61                  'offset' => new external_value(PARAM_INT, 'offset the result set by a given amount', VALUE_DEFAULT, 0)
  62              )
  63          );
  64      }
  65  
  66      /**
  67       * Get notifications function.
  68       *
  69       * @since  3.2
  70       * @throws invalid_parameter_exception
  71       * @throws moodle_exception
  72       * @param  int      $useridto           the user id who received the message
  73       * @param  bool     $newestfirst        true for ordering by newest first, false for oldest first
  74       * @param  int      $limit              the number of results to return
  75       * @param  int      $offset             offset the result set by a given amount
  76       * @return \core_external\external_description
  77       */
  78      public static function get_popup_notifications($useridto, $newestfirst, $limit, $offset) {
  79          global $USER, $PAGE;
  80  
  81          $params = self::validate_parameters(
  82              self::get_popup_notifications_parameters(),
  83              array(
  84                  'useridto' => $useridto,
  85                  'newestfirst' => $newestfirst,
  86                  'limit' => $limit,
  87                  'offset' => $offset,
  88              )
  89          );
  90  
  91          $context = context_system::instance();
  92          self::validate_context($context);
  93  
  94          $useridto = $params['useridto'];
  95          $newestfirst = $params['newestfirst'];
  96          $limit = $params['limit'];
  97          $offset = $params['offset'];
  98          $issuperuser = has_capability('moodle/site:readallmessages', $context);
  99          $renderer = $PAGE->get_renderer('core_message');
 100  
 101          if (empty($useridto)) {
 102              $useridto = $USER->id;
 103          }
 104  
 105          // Check if the current user is the sender/receiver or just a privileged user.
 106          if ($useridto != $USER->id and !$issuperuser) {
 107              throw new moodle_exception('accessdenied', 'admin');
 108          }
 109  
 110          if (!empty($useridto)) {
 111              if (!core_user::is_real_user($useridto)) {
 112                  throw new moodle_exception('invaliduser');
 113              }
 114          }
 115  
 116          $sort = $newestfirst ? 'DESC' : 'ASC';
 117          $notifications = \message_popup\api::get_popup_notifications($useridto, $sort, $limit, $offset);
 118          $notificationcontexts = [];
 119  
 120          if ($notifications) {
 121              foreach ($notifications as $notification) {
 122  
 123                  $notificationoutput = new \message_popup\output\popup_notification($notification);
 124  
 125                  $notificationcontext = $notificationoutput->export_for_template($renderer);
 126  
 127                  // Keep this for BC.
 128                  $notificationcontext->deleted = false;
 129                  $notificationcontexts[] = $notificationcontext;
 130              }
 131          }
 132  
 133          return array(
 134              'notifications' => $notificationcontexts,
 135              'unreadcount' => \message_popup\api::count_unread_popup_notifications($useridto),
 136          );
 137      }
 138  
 139      /**
 140       * Get notifications return description.
 141       *
 142       * @return external_single_structure
 143       * @since 3.2
 144       */
 145      public static function get_popup_notifications_returns() {
 146          return new external_single_structure(
 147              array(
 148                  'notifications' => new external_multiple_structure(
 149                      new external_single_structure(
 150                          array(
 151                              'id' => new external_value(PARAM_INT, 'Notification id (this is not guaranteed to be unique
 152                                  within this result set)'),
 153                              'useridfrom' => new external_value(PARAM_INT, 'User from id'),
 154                              'useridto' => new external_value(PARAM_INT, 'User to id'),
 155                              'subject' => new external_value(PARAM_TEXT, 'The notification subject'),
 156                              'shortenedsubject' => new external_value(PARAM_TEXT, 'The notification subject shortened
 157                                  with ellipsis'),
 158                              'text' => new external_value(PARAM_RAW, 'The message text formated'),
 159                              'fullmessage' => new external_value(PARAM_RAW, 'The message'),
 160                              'fullmessageformat' => new external_format_value('fullmessage'),
 161                              'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
 162                              'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
 163                              'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
 164                              'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
 165                              'timecreated' => new external_value(PARAM_INT, 'Time created'),
 166                              'timecreatedpretty' => new external_value(PARAM_TEXT, 'Time created in a pretty format'),
 167                              'timeread' => new external_value(PARAM_INT, 'Time read'),
 168                              'read' => new external_value(PARAM_BOOL, 'notification read status'),
 169                              'deleted' => new external_value(PARAM_BOOL, 'notification deletion status'),
 170                              'iconurl' => new external_value(PARAM_URL, 'URL for notification icon'),
 171                              'component' => new external_value(PARAM_TEXT, 'The component that generated the notification',
 172                                  VALUE_OPTIONAL),
 173                              'eventtype' => new external_value(PARAM_TEXT, 'The type of notification', VALUE_OPTIONAL),
 174                              'customdata' => new external_value(PARAM_RAW, 'Custom data to be passed to the message processor.
 175                                  The data here is serialised using json_encode().', VALUE_OPTIONAL),
 176                          ), 'message'
 177                      )
 178                  ),
 179                  'unreadcount' => new external_value(PARAM_INT, 'the number of unread message for the given user'),
 180              )
 181          );
 182      }
 183  
 184      /**
 185       * Get unread notification count parameters description.
 186       *
 187       * @return external_function_parameters
 188       * @since 3.2
 189       */
 190      public static function get_unread_popup_notification_count_parameters() {
 191          return new external_function_parameters(
 192              array(
 193                  'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
 194              )
 195          );
 196      }
 197  
 198      /**
 199       * Get unread notification count function.
 200       *
 201       * @since  3.2
 202       * @throws invalid_parameter_exception
 203       * @throws moodle_exception
 204       * @param  int      $useridto       the user id who received the message
 205       * @return \core_external\external_description
 206       */
 207      public static function get_unread_popup_notification_count($useridto) {
 208          global $USER;
 209  
 210          $params = self::validate_parameters(
 211              self::get_unread_popup_notification_count_parameters(),
 212              array('useridto' => $useridto)
 213          );
 214  
 215          $context = context_system::instance();
 216          self::validate_context($context);
 217  
 218          $useridto = $params['useridto'];
 219  
 220          if (!empty($useridto)) {
 221              if (core_user::is_real_user($useridto)) {
 222                  $userto = core_user::get_user($useridto, '*', MUST_EXIST);
 223              } else {
 224                  throw new moodle_exception('invaliduser');
 225              }
 226          }
 227  
 228          // Check if the current user is the sender/receiver or just a privileged user.
 229          if ($useridto != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
 230              throw new moodle_exception('accessdenied', 'admin');
 231          }
 232  
 233          return \message_popup\api::count_unread_popup_notifications($useridto);
 234      }
 235  
 236      /**
 237       * Get unread popup notification count return description.
 238       *
 239       * @return external_single_structure
 240       * @since 3.2
 241       */
 242      public static function get_unread_popup_notification_count_returns() {
 243          return new external_value(PARAM_INT, 'The count of unread popup notifications');
 244      }
 245  }