Lazy load structured Headers

[Slamdunk]

Following @wujku issue #246 here I'm proposing a change to Message\Headers to resolve it.

Since the very first tag in 2013, header validation and specifically EmailAddresses and Date header validation are done at Message\Headers construction, meaning that if any error occurs in any header, no header at all can be queried.

An invalid Date would make this code raising the Exception:

$message = $mailbox->getMessage(1);
// throws InvalidDateHeaderException
var_dump($message->getSubject());

While I would expect it to be thrown only when needed:

$message = $mailbox->getMessage(1);
// Ok
var_dump($message->getSubject());
// throws InvalidDateHeaderException
var_dump($message->getDate());

This PR leaves the decode in the Header construction, so all headers will always be UTF-8, but moves the logic to the Message\AbstractMessage API.

Is this a BC break?

Yes and No.

Yes because this code would behave differently:

// Message\Headers is an ArrayIterator
$headers = $message->getHeaders();
var_dump($headers['to']);
// Before: array of EmailAddress
// After: array of \stdClass
var_dump($headers['date']);
// Before: class DateTimeImmutable
// After: string "Wed, 27 Sep 2017 12:48:51 +0200"

No because the previous example is not a public API usage (i.e. interfaces signatures), so it wouldn't be an incompatible API change. In fact the following code would behave the same:

var_dump($message->getTo());
// Before & After: array of EmailAddress
var_dump($message->getDate());
// Before & After: class DateTimeImmutable

We could in theory make the change fully backward compatible, but we would need to overwrite a lot of ArrayIterator functions: current, getArrayCopy, next, offsetGet, get, seek, serialize etc. Too complex, doesn't worth the effort.

Moreover, I like the change to the Message\Headers contents because the user would be able to choose to query the raw header through the Message\Headers instance, or the parsed header through the Message API.

At the time of writing, I'm tagging this to the 1.1 milestone expected to be released on 2017-11-06.
If we decide this to be a complete BC break, I'll move it to the 2.0 milestone, expected to be released on 2018-03-05 (at least 6 months after the previous major release to gather other major suggestions).

@ddeboer @wujku what do you think?

[ddeboer]

I agree with both your reasons both for implementing this change and with your statement that it’s reasonably BC.

[Slamdunk]

@ddeboer In the release I'll write a clear note about this change, hoping not to break anyone code.