Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:73407
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain sugarcrm.com designates 108.166.43.115 as permitted sender)
Message-ID: <5330F2B2.1030201@sugarcrm.com>
Date: Mon, 24 Mar 2014 20:06:26 -0700
Organization: SugarCRM
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:24.0) Gecko/20100101 Thunderbird/24.4.0
MIME-Version: 1.0
To: Gary Mort <garyamort@gmail.com>, 
 "internals@lists.php.net" <internals@lists.php.net>
References: <5330E319.5060302@gmail.com>
In-Reply-To: <5330E319.5060302@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Proposal: Mail Handling, feedback requested
From: smalyshev@sugarcrm.com (Stas Malyshev)

Hi!

> Current e-mail handling in PHP is dreadful.   Almost every framework
> implements it's own email handling class in order to make sending e-mail 
> reliable, easy to configure, and to implement multiple mail schemes.

That is probably because sending mail involves more than just passing a
stream of bytes to SMTP server. There's MIME, encodings, headers, etc.
which all need to be taken care of. There's email server configurations.
There's error handling.

> class MailMessage {
> 
> /* Properties */
> $private array $recipients;
> $private string $sender;
> $private string $subject;
> $private string $body;
> $private string $header;

What is "header"? If it's a content of whole header, then a) it already
includes all previous fields except "body" and b) you'd still need a
user class to actually make any use of it.
Does it mean if I set $header it would automatically set all the rest of
the fields contained there? Does it mean if I set $subject $header would
automatically be updated?

>$private string $additionalParamters;

What those will be used for?

> public MailMessage __construct (  [string $to, string $subject, string 
> $message, string $additional_headers, string $additional_parameters, 
> string $from, MailHandlerInterface $handler] )

Why additional_headers is a string and not array? That would open the
door to a lot of confusion with formatting the long lines, line endings,
etc. that should be taken care of by basic class.
Same with to - why won't it accept array of email addresses too instead
of making the user figure out how to properly quote and merge them? If
we are already trying to help them...

> 
> /* Send a mail message.  Throws exception on problems.  If $handler is
> specified, then that handler is used.  If not specified, then the the
> objects $handler property is used.  */
> public MailMessage send ([MailHandle $handler ]);

Why send returns MailMessage? What use would I make of it?

> /* Magic method to allow direct setting of sender, subject, body,
> recipients, and additionalParameters.   It is not recommended to
> allow the setting of mail handler or sentTo in this manner. */
> 
> public MailMessage __set();

Why the difference with mail handler and sentTo?

> In addition to a MailMessage class, there would also be a MailHandler 
> interface.  It only requires 2 methods, send and sendBatch.
> 
> MailHandlerInterface {
> /* Methods */
> abstract public bool send ( MailMessage $message [, string $address ] )
> abstract public bool sendBatch ( MailMessage $message [, array 
> $recipients ] )
> }

Why we need $address and $recipients if those are already in the message?

> sendBatch at it's simplest would simply loop through each recipient in 
> the message and call send($message, $recipient).   It could also be 

Why one needs a separate method then? Also, being the interface, it
means that each implementation should copy this method even though we
already know what it would look like. Also, sending to each recipient
individually may be a waste of resources since for most configs one can
send the email with multiple recipients to the mail server once, and let
the server figure out how to handle them.

> send is used to deliver a message to a single recipient.  If a message 
> has multiple potential recipients, send should throw an exception if the 
> specific recipient is not specified via $address.

How this would be useful? Sending email to one or more than one
recipient is not different in any way, moreover, same email may be sent
to one or more recipients depending on the configuration. Why would a
method throw an exception if the email does not contain specific address
in the recipient list? What's the use case for such logic?

> Both send and sendBatch must update the sentTo property of the message 
> to add each recipient a message is actually sent to.  This allows mass 
> e-mail situations to add tracking information to embedded images in the 
> message for each recipient.  Note, such functionality is beyond the 
> scope of the base interface.

I'm not sure how that is supposed to work - send will return after the
message is sent, supposedly, so how I would add embedded images if the
message has been already sent? Also, why would I use message sending
class to get email addresses which I supposedly passed it anyway - if I
had them, why wouldn't I first set the images and only then send it?

> My goal is that the creation and sending of basic e-mail should be a 
> simple operation.  It should be possible for a developer to simply call 
> the mail() function and not be concerned about possible e-mail handling 
> configurations.

I'm not sure - so how you actually configure the email server in your
model and what advantage it gives over mail()? Is it just the framework
for mail() to call? Then it probably should just have one send() method
and not contain any business logic - that should be either in mail() or
in specific handlers. I actually like the idea of such class for mail()
alike to what we did for sessions, but the API should be refined so that
it matches what people do with emails, and error reporting capabilities
should be added (e.g. for some applications what email server answered
is actually important).
-- 
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227