Elgg  Version master
Email.php
Go to the documentation of this file.
1 <?php
2 
3 namespace Elgg;
4 
9 
13 final class Email {
14 
18  protected $from;
19 
23  protected $to = [];
24 
28  protected $cc = [];
29 
33  protected $bcc = [];
34 
38  protected $sender;
39 
43  protected $subject;
44 
48  protected $body;
49 
53  protected $params = [];
54 
58  protected $headers = [];
59 
63  protected $attachments = [];
64 
80  public static function factory(array $options = []) {
81  $from = elgg_extract('from', $options);
82  $to = elgg_extract('to', $options);
83  $cc = elgg_extract('cc', $options);
84  $bcc = elgg_extract('bcc', $options);
85  $subject = elgg_extract('subject', $options);
86  $body = elgg_extract('body', $options);
87  $params = elgg_extract('params', $options, []);
88  $headers = elgg_extract('headers', $options, []);
89 
90  $email = new self();
91  $email->setSender($from);
92  $email->setFrom(self::prepareFrom($from));
93  $email->setTo($to);
94  $email->setCc($cc);
95  $email->setBcc($bcc);
96  $email->setSubject($subject);
97  $email->setBody($body);
98  $email->setParams($params);
99  $email->setHeaders($headers);
100 
101  if (isset($params['attachments']) && is_array($params['attachments'])) {
102  foreach ($params['attachments'] as $attachment) {
103  $email->addAttachment($attachment);
104  }
105  }
106 
107  return $email;
108  }
109 
117  public function setSender($sender) {
118  $this->sender = $sender;
119  return $this;
120  }
121 
127  public function getSender() {
128  return $this->sender;
129  }
130 
138  public function setFrom(Address $from) {
139  $this->from = $from;
140  return $this;
141  }
142 
148  public function getFrom() {
149  return $this->from;
150  }
151 
159  public function setTo($recipient): self {
160  $this->to = $this->prepareRecipients($recipient);
161  return $this;
162  }
163 
169  public function getTo(): array {
170  return $this->to;
171  }
172 
180  public function setCc($recipient): self {
181  $this->cc = $this->prepareRecipients($recipient);
182  return $this;
183  }
184 
190  public function getCc(): array {
191  return $this->cc;
192  }
193 
201  public function setBcc($recipient): self {
202  $this->bcc = $this->prepareRecipients($recipient);
203  return $this;
204  }
205 
211  public function getBcc(): array {
212  return $this->bcc;
213  }
214 
222  public function setSubject($subject = '') {
223  $this->subject = $subject;
224  return $this;
225  }
226 
234  public function getSubject() {
235  return elgg_substr($this->subject, 0, (int) _elgg_services()->config->email_subject_limit);
236  }
237 
245  public function setBody($body = '') {
246  $this->body = $body;
247  return $this;
248  }
249 
255  public function getBody() {
256  return $this->body;
257  }
258 
266  public function setParams(array $params = []) {
267  $this->params = $params;
268  return $this;
269  }
270 
276  public function getParams() {
277  return $this->params;
278  }
279 
288  public function addHeader($name, $value) {
289  $this->headers[$name] = $value;
290  return $this;
291  }
292 
300  public function setHeaders(array $headers = []) {
301  $this->headers = $headers;
302  return $this;
303  }
304 
310  public function getHeaders() {
311  return $this->headers;
312  }
313 
323  public function addAttachment($attachment) {
324 
325  if ($attachment instanceof Part) {
326  $this->attachments[] = $attachment;
327  return $this;
328  }
329 
330  if ($attachment instanceof \ElggFile) {
331  $this->attachments[] = Attachment::fromElggFile($attachment);
332  return $this;
333  }
334 
335  $attachment = Attachment::factory($attachment);
336  if (!empty($attachment)) {
337  $this->attachments[] = $attachment;
338  }
339 
340  return $this;
341  }
342 
348  public function getAttachments() {
349  return $this->attachments;
350  }
351 
361  public function createEntityMessageID(\ElggEntity $entity, bool $add_microtime = false): string {
362  $microtime = '';
363  if ($add_microtime) {
364  $microtime = '.' . microtime(true);
365  }
366 
367  $hostname = parse_url(elgg_get_site_url(), PHP_URL_HOST);
368  $urlPath = parse_url(elgg_get_site_url(), PHP_URL_PATH);
369 
370  return "{$urlPath}.entity.{$entity->guid}{$microtime}@{$hostname}";
371  }
372 
382  protected static function prepareFrom($from) {
383  if (empty($from)) {
384  // get the site email address
386  $from = new Address($site->getEmailAddress(), $site->getDisplayName());
387  } elseif ($from instanceof \ElggSite) {
388  // use site email address
389  $from = new Address($from->getEmailAddress(), $from->getDisplayName());
390  } elseif ($from instanceof \ElggEntity) {
391  // If there's an email address, use it - but only if it's not from a user.
392  if (!$from instanceof \ElggUser && $from->email) {
393  $from = Address::fromEntity($from);
394  } else {
395  // get the site email address
397  $from_display = elgg_echo('notification:method:email:from', [$from->getDisplayName(), $site->getDisplayName()]);
398  $from = new Address($site->getEmailAddress(), $from_display);
399  }
400  } elseif (is_string($from)) {
401  $from = Address::fromString($from);
402  }
403 
404  if (!$from instanceof Address) {
405  throw new InvalidArgumentException('From address is not in a valid format');
406  }
407 
408  return $from;
409  }
410 
420  protected function prepareRecipients($recipients) {
421  if (empty($recipients)) {
422  return [];
423  }
424 
425  if (!is_array($recipients)) {
426  $recipients = [$recipients];
427  }
428 
429  $result = [];
430  foreach ($recipients as $recipient) {
431  if ($recipient instanceof Address) {
432  $result[] = $recipient;
433  continue;
434  }
435 
436  if ($recipient instanceof \ElggEntity) {
437  $recipient = Address::fromEntity($recipient);
438  } elseif (is_string($recipient)) {
439  $recipient = Address::fromString($recipient);
440  }
441 
442  if (!$recipient instanceof Address) {
443  throw new InvalidArgumentException('Recipient address is not in a valid format');
444  }
445 
446  $result[] = $recipient;
447  }
448 
449  return $result;
450  }
451 }
setFrom(Address $from)
Sets sender address.
Definition: Email.php:138
setCc($recipient)
Sets recipient address in cc.
Definition: Email.php:180
getTo()
Returns recipient address.
Definition: Email.php:169
Exception thrown if an argument is not of the expected type.
$params
Saves global plugin settings.
Definition: save.php:13
if(!$user||!$user->canDelete()) $name
Definition: delete.php:22
prepareRecipients($recipients)
Converts mixed input to an array of Laminas address instances.
Definition: Email.php:420
setParams(array $params=[])
Sets additional params.
Definition: Email.php:266
setSender($sender)
Sets email sender.
Definition: Email.php:117
elgg_echo(string $message_key, array $args=[], string $language= '')
Elgg language module Functions to manage language and translations.
Definition: languages.php:17
static prepareFrom($from)
Converts mixed input to an instance of Laminas addres.
Definition: Email.php:382
$email
Definition: change_email.php:7
getParams()
Returns additional params.
Definition: Email.php:276
setHeaders(array $headers=[])
Replaces header bag.
Definition: Email.php:300
getBcc()
Returns recipient address from bcc.
Definition: Email.php:211
static factory(array $options=[])
Create an email instance form an array of options.
Definition: Email.php:80
setSubject($subject= '')
Sets email subject.
Definition: Email.php:222
setBcc($recipient)
Sets recipient address in bcc.
Definition: Email.php:201
$site
Definition: icons.php:5
setBody($body= '')
Sets the email message body.
Definition: Email.php:245
if($item instanceof\ElggEntity) elseif($item instanceof\ElggRiverItem) elseif($item instanceof\ElggRelationship) elseif(is_callable([$item, 'getType']))
Definition: item.php:48
$value
Definition: generic.php:51
elgg_extract($key, $array, $default=null, bool $strict=true)
Checks for $array[$key] and returns its value if it exists, else returns $default.
Definition: elgglib.php:254
if($who_can_change_language=== 'nobody') elseif($who_can_change_language=== 'admin_only'&&!elgg_is_admin_logged_in()) $options
Definition: language.php:20
Email message.
Definition: Email.php:13
$entity
Definition: reset.php:8
getCc()
Returns recipient address from cc.
Definition: Email.php:190
getSubject()
Returns the subject.
Definition: Email.php:234
addAttachment($attachment)
Add an attachment.
Definition: Email.php:323
getSender()
Returns sender.
Definition: Email.php:127
elgg_get_site_url()
Get the URL for the current (or specified) site, ending with "/".
$body
Definition: useradd.php:55
elgg_get_site_entity()
Get the current site entity.
Definition: entities.php:101
getBody()
Returns email body.
Definition: Email.php:255
elgg_substr()
Wrapper function for mb_substr().
Definition: mb_wrapper.php:195
$attachments
Outputs attachments.
Definition: attachments.php:9
setTo($recipient)
Sets recipient address.
Definition: Email.php:159
getHeaders()
Returns headers.
Definition: Email.php:310
createEntityMessageID(\ElggEntity $entity, bool $add_microtime=false)
Create a Message-ID header string for the given entity.
Definition: Email.php:361
Email address.
Definition: Address.php:15
_elgg_services()
Get the global service provider.
Definition: elgglib.php:351
getFrom()
Returns sender address.
Definition: Email.php:148
addHeader($name, $value)
Adds/replaces an HTTP/IMF header.
Definition: Email.php:288
$recipient
Definition: mute.php:8
$subject
Definition: useradd.php:54
getAttachments()
Get all attachments.
Definition: Email.php:348