1
|
|
|
<?php |
2
|
|
|
/** |
3
|
|
|
* This file is part of the ZBateson\MailMimeParser project. |
4
|
|
|
* |
5
|
|
|
* @license http://opensource.org/licenses/bsd-license.php BSD |
6
|
|
|
*/ |
7
|
|
|
namespace ZBateson\MailMimeParser\Header; |
8
|
|
|
|
9
|
|
|
use ZBateson\MailMimeParser\Header\Consumer\ConsumerService; |
10
|
|
|
use ZBateson\MailMimeParser\Header\Consumer\AbstractConsumer; |
11
|
|
|
use ZBateson\MailMimeParser\Header\Part\CommentPart; |
12
|
|
|
use ZBateson\MailMimeParser\Header\Part\DatePart; |
13
|
|
|
|
14
|
|
|
/** |
15
|
|
|
* Represents a Received header. |
16
|
|
|
* |
17
|
|
|
* The returned header value (as returned by a call to {@see |
18
|
|
|
* ReceivedHeader::getValue()}) for a |
19
|
|
|
* ReceivedHeader is the same as the raw value (as returned by a call to |
20
|
|
|
* {@see ReceivedHeader::getRawValue()}) since the header doesn't have a single |
21
|
|
|
* 'value' to extract. |
22
|
|
|
* |
23
|
|
|
* The parsed parts of a Received header can be accessed as parameters. To |
24
|
|
|
* check if a part exists, call {@see ReceivedHeader::hasParameter()} with the |
25
|
|
|
* name of the part, for example: ``` $header->hasParameter('from') ``` or |
26
|
|
|
* ``` $header->hasParameter('id') ```. The value of the part can be obtained |
27
|
|
|
* by calling {@see ReceivedHeader::getValueFor()}, for example |
28
|
|
|
* ``` $header->getValueFor('with'); ```. |
29
|
|
|
* |
30
|
|
|
* Additional parsing is performed on the "FROM" and "BY" parts of a received |
31
|
|
|
* header in an attempt to extract the self-identified name of the server, its |
32
|
|
|
* hostname, and its address (depending on what's included). These can be |
33
|
|
|
* accessed directly from the ReceivedHeader object by calling one of the |
34
|
|
|
* following methods: |
35
|
|
|
* |
36
|
|
|
* o {@see ReceivedHeader::getFromName()} -- the name portion of the FROM part |
37
|
|
|
* o {@see ReceivedHeader::getFromHostname()} -- the hostname of the FROM part |
38
|
|
|
* o {@see ReceivedHeader::getFromAddress()} -- the adddress portion of the FROM |
39
|
|
|
* part |
40
|
|
|
* o {@see ReceivedHeader::getByName()} -- same as getFromName, but for the BY |
41
|
|
|
* part, and etc... below |
42
|
|
|
* o {@see ReceivedHeader::getByHostname()} |
43
|
|
|
* o {@see ReceivedHeader::getByAddress()} |
44
|
|
|
* |
45
|
|
|
* The parsed parts of the FROM and BY parts are determined as follows: |
46
|
|
|
* |
47
|
|
|
* o Anything outside and before a parenthesized expression is considered "the |
48
|
|
|
* name", for example "FROM AlainDeBotton", "AlainDeBotton" would be the name, |
49
|
|
|
* but also if the name is an address, but exists outside the parenthesized |
50
|
|
|
* expression, it's still considered "the name". For example: |
51
|
|
|
* "From [1.2.3.4]", getFromName would return "[1.2.3.4]". |
52
|
|
|
* o A parenthesized expression MUST match what looks like either a domain name |
53
|
|
|
* on its own, or a domain name and an address. Otherwise the parenthesized |
54
|
|
|
* expression is considered a comment, and not parsed into hostname and |
55
|
|
|
* address. The rules are defined loosely because many implementations differ |
56
|
|
|
* in how strictly they follow the standard. For a domain, it's enough that |
57
|
|
|
* the expression starts with any alphanumeric character and contains at least |
58
|
|
|
* one '.', followed by any number of '.', '-' and alphanumeric characters. |
59
|
|
|
* The address portion must be surrounded in square brackets, and contain any |
60
|
|
|
* sequence of '.', ':', numbers, and characters 'a' through 'f'. In addition |
61
|
|
|
* the string 'ipv6' may start the expression (for instance, '[ipv6:::1]' |
62
|
|
|
* would be valid). A port number may also be considered valid as part of the |
63
|
|
|
* address, for example: [1.2.3.4:3231]. No additional validation on the |
64
|
|
|
* address is done, and so an invalid address such as '....' could be |
65
|
|
|
* returned, so users using the 'address' header are encouraged to validate it |
66
|
|
|
* before using it. The square brackets are parsed out of the returned |
67
|
|
|
* address, so the value returned by getFromAddress() would be "2.2.2.2", not |
68
|
|
|
* "[2.2.2.2]". |
69
|
|
|
* |
70
|
|
|
* The date/time stamp can be accessed as a DateTime object by calling |
71
|
|
|
* {@see ReceivedHeader::getDateTime()}. |
72
|
|
|
* |
73
|
|
|
* Parsed comments can be accessed by calling {@see |
74
|
|
|
* ReceivedHeader::getComments()}. Some implementations may include connection |
75
|
|
|
* encryption information or other details in non-standardized comments. |
76
|
|
|
* |
77
|
|
|
* @author Zaahid Bateson |
78
|
|
|
*/ |
79
|
|
|
class ReceivedHeader extends ParameterHeader |
80
|
|
|
{ |
81
|
|
|
/** |
82
|
|
|
* @var string[] an array of comments in the header. |
83
|
|
|
*/ |
84
|
|
|
protected $comments = []; |
85
|
|
|
|
86
|
|
|
/** |
87
|
|
|
* @var DateTime the date/time stamp in the header. |
|
|
|
|
88
|
|
|
*/ |
89
|
|
|
protected $date; |
90
|
|
|
|
91
|
|
|
/** |
92
|
|
|
* Returns a ReceivedConsumer. |
93
|
|
|
* |
94
|
|
|
* @param ConsumerService $consumerService |
95
|
|
|
* @return \ZBateson\MailMimeParser\Header\Consumer\AbstractConsumer |
96
|
|
|
*/ |
97
|
|
|
protected function getConsumer(ConsumerService $consumerService) |
98
|
|
|
{ |
99
|
|
|
return $consumerService->getReceivedConsumer(); |
100
|
|
|
} |
101
|
|
|
|
102
|
|
|
/** |
103
|
|
|
* Overridden to assign comments to $this->comments, and the DateTime to |
104
|
|
|
* $this->date. |
105
|
|
|
* |
106
|
|
|
* @param AbstractConsumer $consumer |
107
|
|
|
*/ |
108
|
|
|
protected function setParseHeaderValue(AbstractConsumer $consumer) |
109
|
|
|
{ |
110
|
|
|
parent::setParseHeaderValue($consumer); |
111
|
|
|
foreach ($this->parts as $part) { |
112
|
|
|
if ($part instanceof CommentPart) { |
113
|
|
|
$this->comments[] = $part->getComment(); |
114
|
|
|
} elseif ($part instanceof DatePart) { |
115
|
|
|
$this->date = $part->getDateTime(); |
|
|
|
|
116
|
|
|
} |
117
|
|
|
} |
118
|
|
|
} |
119
|
|
|
|
120
|
|
|
/** |
121
|
|
|
* Returns the raw, unparsed header value, same as {@see |
122
|
|
|
* ReceivedHeader::getRawValue()}. |
123
|
|
|
* |
124
|
|
|
* @return string |
125
|
|
|
*/ |
126
|
|
|
public function getValue() |
127
|
|
|
{ |
128
|
|
|
return $this->rawValue; |
129
|
|
|
} |
130
|
|
|
|
131
|
|
|
/** |
132
|
|
|
* Returns the name identified in the FROM part of the header. |
133
|
|
|
* |
134
|
|
|
* The returned value may either be a name or an address in the form |
135
|
|
|
* "[1.2.3.4]". Validation is not performed on this value, and so whatever |
136
|
|
|
* exists in this position is returned -- be it contains spaces, or invalid |
137
|
|
|
* characters, etc... |
138
|
|
|
* |
139
|
|
|
* @return string |
140
|
|
|
*/ |
141
|
|
|
public function getFromName() |
142
|
|
|
{ |
143
|
|
|
return (isset($this->parameters['from'])) ? |
144
|
|
|
$this->parameters['from']->getEhloName() : null; |
|
|
|
|
145
|
|
|
} |
146
|
|
|
|
147
|
|
|
/** |
148
|
|
|
* Returns the hostname part of a parenthesized FROM part. |
149
|
|
|
* |
150
|
|
|
* For example, "FROM name (host.name)" would return the string "host.name". |
151
|
|
|
* Validation of the hostname is not performed, and the returned value may |
152
|
|
|
* not be valid. More details on how the value is parsed and extracted can |
153
|
|
|
* be found in the class description for {@see ReceivedHeader}. |
154
|
|
|
* |
155
|
|
|
* @return string |
156
|
|
|
*/ |
157
|
|
|
public function getFromHostname() |
158
|
|
|
{ |
159
|
|
|
return (isset($this->parameters['from'])) ? |
160
|
|
|
$this->parameters['from']->getHostname() : null; |
|
|
|
|
161
|
|
|
} |
162
|
|
|
|
163
|
|
|
/** |
164
|
|
|
* Returns the address part of a parenthesized FROM part. |
165
|
|
|
* |
166
|
|
|
* For example, "FROM name ([1.2.3.4])" would return the string "1.2.3.4". |
167
|
|
|
* Validation of the address is not performed, and the returned value may |
168
|
|
|
* not be valid. More details on how the value is parsed and extracted can |
169
|
|
|
* be found in the class description for {@see ReceivedHeader}. |
170
|
|
|
* |
171
|
|
|
* @return string |
172
|
|
|
*/ |
173
|
|
|
public function getFromAddress() |
174
|
|
|
{ |
175
|
|
|
return (isset($this->parameters['from'])) ? |
176
|
|
|
$this->parameters['from']->getAddress() : null; |
|
|
|
|
177
|
|
|
} |
178
|
|
|
|
179
|
|
|
/** |
180
|
|
|
* Returns the name identified in the BY part of the header. |
181
|
|
|
* |
182
|
|
|
* The returned value may either be a name or an address in the form |
183
|
|
|
* "[1.2.3.4]". Validation is not performed on this value, and so whatever |
184
|
|
|
* exists in this position is returned -- be it contains spaces, or invalid |
185
|
|
|
* characters, etc... |
186
|
|
|
* |
187
|
|
|
* @return string |
188
|
|
|
*/ |
189
|
|
|
public function getByName() |
190
|
|
|
{ |
191
|
|
|
return (isset($this->parameters['by'])) ? |
192
|
|
|
$this->parameters['by']->getEhloName() : null; |
193
|
|
|
} |
194
|
|
|
|
195
|
|
|
/** |
196
|
|
|
* Returns the hostname part of a parenthesized BY part. |
197
|
|
|
* |
198
|
|
|
* For example, "BY name (host.name)" would return the string "host.name". |
199
|
|
|
* Validation of the hostname is not performed, and the returned value may |
200
|
|
|
* not be valid. More details on how the value is parsed and extracted can |
201
|
|
|
* be found in the class description for {@see ReceivedHeader}. |
202
|
|
|
* |
203
|
|
|
* @return string |
204
|
|
|
*/ |
205
|
|
|
public function getByHostname() |
206
|
|
|
{ |
207
|
|
|
return (isset($this->parameters['by'])) ? |
208
|
|
|
$this->parameters['by']->getHostname() : null; |
209
|
|
|
} |
210
|
|
|
|
211
|
|
|
/** |
212
|
|
|
* Returns the address part of a parenthesized BY part. |
213
|
|
|
* |
214
|
|
|
* For example, "BY name ([1.2.3.4])" would return the string "1.2.3.4". |
215
|
|
|
* Validation of the address is not performed, and the returned value may |
216
|
|
|
* not be valid. More details on how the value is parsed and extracted can |
217
|
|
|
* be found in the class description for {@see ReceivedHeader}. |
218
|
|
|
* |
219
|
|
|
* @return string |
220
|
|
|
*/ |
221
|
|
|
public function getByAddress() |
222
|
|
|
{ |
223
|
|
|
return (isset($this->parameters['by'])) ? |
224
|
|
|
$this->parameters['by']->getAddress() : null; |
225
|
|
|
} |
226
|
|
|
|
227
|
|
|
/** |
228
|
|
|
* Returns an array of comments parsed from the header. If there are no |
229
|
|
|
* comments in the header, an empty array is returned. |
230
|
|
|
* |
231
|
|
|
* @return string[] |
232
|
|
|
*/ |
233
|
|
|
public function getComments() |
234
|
|
|
{ |
235
|
|
|
return $this->comments; |
236
|
|
|
} |
237
|
|
|
|
238
|
|
|
/** |
239
|
|
|
* Returns the date/time stamp for the received header. |
240
|
|
|
* |
241
|
|
|
* @return \DateTime |
242
|
|
|
*/ |
243
|
|
|
public function getDateTime() |
244
|
|
|
{ |
245
|
|
|
return $this->date; |
246
|
|
|
} |
247
|
|
|
} |
248
|
|
|
|