weekly release 3.0dev
[moodle.git] / lib / classes / message / message.php
CommitLineData
53a842e6
AA
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
26namespace core\message;
27
28defined('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 */
58class 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 * This method lets you define content that would be added to the message only for specific message processors.
220 *
221 * Example of $content:-
222 * array('fullmessagehtml' => array('header' => 'header content', 'footer' => 'footer content'),
223 * 'smallmessage' => array('header' => 'header content for small message', 'footer' => 'footer content'),
224 * '*' => array('header' => 'header content for all types', 'footer' => 'footer content')
225 * )
226 *
227 * @param string $processorname name of the processor.
228 * @param array $content content to add in the above defined format.
229 */
230 public function set_additional_content($processorname, $content) {
231 $this->additionalcontent[$processorname] = $content;
232 }
233
234 /**
235 * Get a event object for a specific processor in stdClass format.
236 *
237 * @param string $processorname Name of the processor.
238 *
239 * @return \stdClass event object in stdClass format.
240 */
241 public function get_eventobject_for_processor($processorname) {
242 // This is done for Backwards compatibility. We should consider throwing notices here in future versions and requesting
243 // them to use proper api.
244
245 $eventdata = new \stdClass();
246 foreach ($this->properties as $prop) {
247 $func = "get_$prop";
248 $eventdata->$prop = method_exists($this, $func) ? $this->$func($processorname) : $this->$prop;
249 }
250 return $eventdata;
251 }
252}