1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
<?php
/**
* This helper builds the EmailAddress object for a /mail/send API call
*
* PHP Version - 5.6, 7.0, 7.1, 7.2
*
* @package SendGrid\Mail
* @author Elmer Thomas <dx@sendgrid.com>
* @copyright 2018-19 Twilio SendGrid
* @license https://opensource.org/licenses/MIT The MIT License
* @version GIT: <git_id>
* @link http://packagist.org/packages/sendgrid/sendgrid
*/
namespace SendGrid\Mail;
/**
* This class is used to construct a EmailAddress object for the /mail/send API call
*
* @package SendGrid\Mail
*/
class EmailAddress implements \JsonSerializable
{
/** @var $name string The name of the person associated with the email */
private $name;
/** @var $email string The email address */
private $email;
/** @var $substitutions Substitution[] An array of key/value substitutions to be be applied to the text and html content of the email body */
private $substitutions;
/** @var $subject Subject The personalized subject of the email */
private $subject;
/**
* Optional constructor
*
* @param string|null $emailAddress The email address
* @param string|null $name The name of the person associated with
* the email
* @param array|null $substitutions An array of key/value substitutions to
* be be applied to the text and html content
* of the email body
* @param string|null $subject The personalized subject of the email
*/
public function __construct(
$emailAddress = null,
$name = null,
$substitutions = null,
$subject = null
) {
if (isset($emailAddress)) {
$this->setEmailAddress($emailAddress);
}
if (isset($name) && $name !== null) {
$this->setName($name);
}
if (isset($substitutions)) {
$this->setSubstitutions($substitutions);
}
if (isset($subject)) {
$this->setSubject($subject);
}
}
/**
* Add the email address to a EmailAddress object
*
* @param string $emailAddress The email address
*
* @throws TypeException
*/
public function setEmailAddress($emailAddress)
{
if (!(is_string($emailAddress) &&
filter_var($emailAddress, FILTER_VALIDATE_EMAIL))
) {
throw new TypeException(
'$emailAddress must be valid and of type string.'
);
}
$this->email = $emailAddress;
}
/**
* Retrieve the email address from a EmailAddress object
*
* @return string
*/
public function getEmailAddress()
{
return $this->email;
}
/**
* Retrieve the email address from a EmailAddress object
*
* @return string
*/
public function getEmail()
{
return $this->getEmailAddress();
}
/**
* Add a name to a EmailAddress object
*
* @param string $name The name of the person associated with the email
*
* @throws TypeException
*/
public function setName($name)
{
if (!is_string($name)) {
throw new TypeException('$name must be of type string.');
}
/*
Issue #368
==========
If the name is not wrapped in double quotes and contains a comma or
semicolon, the API fails to parse it correctly.
When wrapped in double quotes, commas, semicolons and unescaped single
quotes are supported.
Escaped double quotes are supported as well but will appear unescaped in
the mail (e.g. "O\'Keefe").
Double quotes will be shown in some email clients, so the name should
only be wrapped when necessary.
*/
// Only wrapp in double quote if comma or semicolon are found
if (false !== strpos($name, ',') || false !== strpos($name, ';')) {
// Unescape quotes
$name = stripslashes(html_entity_decode($name, ENT_QUOTES));
// Escape only double quotes
$name = str_replace('"', '\\"', $name);
// Wrapp in double quotes
$name = '"' . $name . '"';
}
$this->name = (!empty($name)) ? $name : null;
}
/**
* Retrieve the name from a EmailAddress object
*
* @return string
*/
public function getName()
{
return $this->name;
}
/**
* Add substitutions to a EmailAddress object
*
* @param array $substitutions An array of key/value substitutions to
* be be applied to the text and html content
* of the email body
*
* @throws TypeException
*/
public function setSubstitutions($substitutions)
{
if (!is_array($substitutions)) {
throw new TypeException('$substitutions must be an array.');
}
$this->substitutions = $substitutions;
}
/**
* Retrieve substitutions from a EmailAddress object
*/
public function getSubstitutions()
{
return $this->substitutions;
}
/**
* Add a subject to a EmailAddress object
*
* @param string $subject The personalized subject of the email
*
* @throws TypeException
*/
public function setSubject($subject)
{
if (!is_string($subject)) {
throw new TypeException('$subject must be of type string.');
}
if (!($subject instanceof Subject)) {
$this->subject = new Subject($subject);
} else {
$this->subject = $subject;
}
}
/**
* Retrieve a subject from a EmailAddress object
*
* @return Subject
*/
public function getSubject()
{
return $this->subject;
}
/**
* Return an array representing a EmailAddress object for the Twilio SendGrid API
*
* @return null|array
*/
public function jsonSerialize()
{
return array_filter(
[
'name' => $this->getName(),
'email' => $this->getEmail()
],
function ($value) {
return $value !== null;
}
) ?: null;
}
}
|
