Add ability to set SMTP envelope addresses

[ameir]

I am working on a program that is called from a mail server, and re-injects the message back into the mail queue to be sent to multiple recipients (using a Postfix content filter). The problem is that this library forms the RCPT TO: information from the message headers, which in this case, will not work (the goal is for the message to arrive untouched). There should be an option to pass SMTP-level message options to the transport to handle situations like this.

I currently have something like the following:

$email = file_get_contents("php://stdin");
$headers = $body = '';
Zend\Mime\Decode::splitMessage($email, $headers, $body);

// Setup SMTP transport
$transport = new Zend\Mail\Transport\Smtp();
$options = new Zend\Mail\Transport\SmtpOptions(
        array(
    'name' => php_uname('n'),
    'host' => '127.0.0.1',
    'port' => 10025,
        )
);
$transport->setOptions($options);

$message = new Zend\Mail\Message();
$message->setHeaders($headers);
$message->setBody($body);
$transport->send($message);

This pull request will allow you to do:

    $message = new Zend\Mail\Message();
    $message->setHeaders($headers);
    $message->setBody($body);
    $envelope = new Zend\Mail\Transport\Envelope(array(
        'from' => 'mail-from@address.com',
        'to' => 'rcpt-to@address.com',
            )
    );
    $transport->setEnvelope($envelope);
    $transport->send($message);

[Ocramius]

@ameir thanks for the contribution!

A couple of things are still missing though:

• test cases covering all of the newly introduced API
• a documentation pull request to be submitted to https://github.com/zendframework/zf2-documentation

[Ocramius]

= null is not required in php

[ameir]

Thanks, @Ocramius! I'll work on some test cases and update this PR in a bit.

[Ocramius]

string|null

[Ocramius]

This PR is still requiring tests before being mergeable

[weierophinney]

Ping @ameir — I'd love to merge this for 2.4, but we need tests for the new functionality. Would you be able to do that in the next 2 weeks?

[ameir]

@weierophinney I'll see if I can find time to knock this out in the next few days. My apologies for the delays; my schedule has been hectic. I have a number of other changes to perform PRs against as well (https://github.com/ameir/zf2/tree/mail-improvements), but they'll also need tests.

[ameir]

@weierophinney @Ocramius I wrote tests and updated the code accordingly. I had to reintroduce the setters and getters due to a separate test failing that checked for existence of those. I then updated the code to use the setters/getters. Let me know if this needs further modification.

[weierophinney]

Incorporated feedback from @Ocramius and merged to develop for release with 2.4.