[Summary view]

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

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