[Summary view] [Print] [Text view]

   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  /**
  18   * New messaging class.
  19   *
  20   * @package   core_message
  21   * @since     Moodle 2.9
  22   * @copyright 2015 onwards Ankit Agarwal
  23   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  namespace core\message;
  27  
  28  defined('MOODLE_INTERNAL') || die();
  29  
  30  /**
  31   * New messaging class.
  32   *
  33   * Required parameters of the $eventdata object:
  34   *  component string Component name. must exist in message_providers
  35   *  name string Message type name. must exist in message_providers
  36   *  userfrom object|int The user sending the message
  37   *  userto object|int The message recipient
  38   *  subject string The message subject
  39   *  fullmessage string The full message in a given format
  40   *  fullmessageformat int The format if the full message (FORMAT_MOODLE, FORMAT_HTML, ..)
  41   *  fullmessagehtml string The full version (the message processor will choose with one to use)
  42   *  smallmessage string The small version of the message
  43   *
  44   * Optional parameters of the $eventdata object:
  45   *  notification bool Should the message be considered as a notification rather than a personal message
  46   *  contexturl string If this is a notification then you can specify a url to view the event.
  47   *                    For example the forum post the user is being notified of.
  48   *  contexturlname string The display text for contexturl.
  49   *  replyto string An email address which can be used to send an reply.
  50   *  attachment stored_file File instance that needs to be sent as attachment.
  51   *  attachname string Name of the attachment.
  52   *
  53   * @package   core_message
  54   * @since     Moodle 2.9
  55   * @copyright 2015 onwards Ankit Agarwal
  56   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  57   */
  58  class message {
  59      /** @var string Component name. */
  60      private $component;
  61  
  62      /** @var string Name. */
  63      private $name;
  64  
  65      /** @var object|int The user who is sending this message. */
  66      private $userfrom;
  67  
  68      /** @var object|int The user who is receiving from which is sending this message. */
  69      private $userto;
  70  
  71      /** @var string Subject of the message. */
  72      private $subject;
  73  
  74      /** @var string Complete message. */
  75      private $fullmessage;
  76  
  77      /** @var int Message format. */
  78      private $fullmessageformat;
  79  
  80      /** @var string Complete message in html format. */
  81      private $fullmessagehtml;
  82  
  83      /** @var  string Smaller version of the message. */
  84      private $smallmessage;
  85  
  86      /** @var  int Is it a notification? */
  87      private $notification;
  88  
  89      /** @var  string context url. */
  90      private $contexturl;
  91  
  92      /** @var  string context name. */
  93      private $contexturlname;
  94  
  95      /** @var  string An email address which can be used to send an reply. */
  96      private $replyto;
  97  
  98      /** @var  int Used internally to store the id of the row representing this message in DB. */
  99      private $savedmessageid;
 100  
 101      /** @var  \stored_file  File to be attached to the message. Note:- not all processors support this.*/
 102      private $attachment;
 103  
 104      /** @var  string Name of the attachment. Note:- not all processors support this.*/
 105      private $attachname;
 106  
 107      /** @var array a list of properties that is allowed for each message. */
 108      private $properties = array('component', 'name', 'userfrom', 'userto', 'subject', 'fullmessage', 'fullmessageformat',
 109                                  'fullmessagehtml', 'smallmessage', 'notification', 'contexturl', 'contexturlname', 'savedmessageid',
 110                                  'replyto', 'attachment', 'attachname');
 111  
 112      /** @var array property to store any additional message processor specific content */
 113      private $additionalcontent = array();
 114  
 115      /**
 116       * Fullmessagehtml content including any processor specific content.
 117       *
 118       * @param string $processorname Name of the processor.
 119       *
 120       * @return mixed|string
 121       */
 122      protected function get_fullmessagehtml($processorname = '') {
 123          if (!empty($processorname) && isset($this->additionalcontent[$processorname])) {
 124              return $this->get_message_with_additional_content($processorname, 'fullmessagehtml');
 125          } else {
 126              return $this->fullmessagehtml;
 127          }
 128      }
 129  
 130      /**
 131       * Fullmessage content including any processor specific content.
 132       *
 133       * @param string $processorname Name of the processor.
 134       *
 135       * @return mixed|string
 136       */
 137      protected function get_fullmessage($processorname = '') {
 138          if (!empty($processorname) && isset($this->additionalcontent[$processorname])) {
 139              return $this->get_message_with_additional_content($processorname, 'fullmessage');
 140          } else {
 141              return $this->fullmessage;
 142          }
 143      }
 144  
 145      /**
 146       * Smallmessage content including any processor specific content.
 147       *
 148       * @param string $processorname Name of the processor.
 149       *
 150       * @return mixed|string
 151       */
 152      protected function get_smallmessage($processorname = '') {
 153          if (!empty($processorname) && isset($this->additionalcontent[$processorname])) {
 154              return $this->get_message_with_additional_content($processorname, 'smallmessage');
 155          } else {
 156              return $this->smallmessage;
 157          }
 158      }
 159  
 160      /**
 161       * Helper method used to get message content added with processor specific content.
 162       *
 163       * @param string $processorname Name of the processor.
 164       * @param string $messagetype one of 'fullmessagehtml', 'fullmessage', 'smallmessage'.
 165       *
 166       * @return mixed|string
 167       */
 168      protected function get_message_with_additional_content($processorname, $messagetype) {
 169          $message = $this->$messagetype;
 170          if (isset($this->additionalcontent[$processorname]['*'])) {
 171              // Content that needs to be added to all format.
 172              $pattern = $this->additionalcontent[$processorname]['*'];
 173              $message = empty($pattern['header']) ? $message : $pattern['header'] . $message;
 174              $message = empty($pattern['footer']) ? $message : $message . $pattern['footer'];
 175          }
 176  
 177          if (isset($this->additionalcontent[$processorname][$messagetype])) {
 178              // Content that needs to be added to the specific given format.
 179              $pattern = $this->additionalcontent[$processorname][$messagetype];
 180              $message = empty($pattern['header']) ? $message : $pattern['header'] . $message;
 181              $message = empty($pattern['footer']) ? $message : $message . $pattern['footer'];
 182          }
 183  
 184          return $message;
 185      }
 186  
 187      /**
 188       * Magic getter method.
 189       *
 190       * @param string $prop name of property to get.
 191       *
 192       * @return mixed
 193       * @throws \coding_exception
 194       */
 195      public function __get($prop) {
 196          if (in_array($prop, $this->properties)) {
 197              return $this->$prop;
 198          }
 199          throw new \coding_exception("Invalid property $prop specified");
 200      }
 201  
 202      /**
 203       * Magic setter method.
 204       *
 205       * @param string $prop name of property to set.
 206       * @param mixed $value value to assign to the property.
 207       *
 208       * @return mixed
 209       * @throws \coding_exception
 210       */
 211      public function __set($prop, $value) {
 212          if (in_array($prop, $this->properties)) {
 213              return $this->$prop = $value;
 214          }
 215          throw new \coding_exception("Invalid property $prop specified");
 216      }
 217  
 218      /**
 219       * Magic method to check if property is set.
 220       *
 221       * @param string $prop name of property to check.
 222       * @return bool
 223       * @throws \coding_exception
 224       */
 225      public function __isset($prop) {
 226          if (in_array($prop, $this->properties)) {
 227              return isset($this->$prop);
 228          }
 229          throw new \coding_exception("Invalid property $prop specified");
 230      }
 231  
 232      /**
 233       * This method lets you define content that would be added to the message only for specific message processors.
 234       *
 235       * Example of $content:-
 236       * array('fullmessagehtml' => array('header' => 'header content', 'footer' => 'footer content'),
 237       *       'smallmessage' => array('header' => 'header content for small message', 'footer' => 'footer content'),
 238       *       '*' => array('header' => 'header content for all types', 'footer' => 'footer content')
 239       * )
 240       *
 241       * @param string $processorname name of the processor.
 242       * @param array $content content to add in the above defined format.
 243       */
 244      public function set_additional_content($processorname, $content) {
 245          $this->additionalcontent[$processorname] = $content;
 246      }
 247  
 248      /**
 249       * Get a event object for a specific processor in stdClass format.
 250       *
 251       * @param string $processorname Name of the processor.
 252       *
 253       * @return \stdClass event object in stdClass format.
 254       */
 255      public function get_eventobject_for_processor($processorname) {
 256          // This is done for Backwards compatibility. We should consider throwing notices here in future versions and requesting
 257          // them to use proper api.
 258  
 259          $eventdata = new \stdClass();
 260          foreach ($this->properties as $prop) {
 261              $func = "get_$prop";
 262              $eventdata->$prop = method_exists($this, $func) ? $this->$func($processorname) : $this->$prop;
 263          }
 264          return $eventdata;
 265      }
 266  }