New mail API for the core

We will integrate the Swift Mailer API to the TYPO3 core. This enables us to have a nice object oriented API for:

  • creation of mails (handling of all the "dirty details" of MIME, RFC conformance, encoding, etc)
  • sending of mails (using the most modern techniques available, configurable in the Install Tool)

API sample:

Concatenated syntax:

1 $mail = t3lib_div::makeInstance('t3lib_mail_message');
2 $mail->setFrom(array($email => $name))
3   ->setTo(array($email => $name))
4   ->setSubject($subject)
5   ->setBody($body)
6   ->send();

Regular syntax:

1 $mail = t3lib_div::makeInstance('t3lib_mail_message');
2 $mail->setFrom(array($email => $name));
3 $mail->setTo(array($email => $name));
4 $mail->setSubject($subject);
5 $mail->setBody($body);
6 $mail->send();

Plan of migration

Plan is to deprecate t3lib_htmlmail. To achieve that, we will need to find replacements to all functionality that t3lib_htmlmail, which is:

  • Creating and sending a mail
  • Adding attachments (either inline or embedded) to mails
  • Fetching a remote URL and tranforming that into a mail (which is e.g. used by direct_mail)

To tackle that, this project approaches that in these three steps:

Step 1: Creating and sending a mail

The new class t3lib_mail_message extends Swift_Message, so we have all power that is available in Swift_Message in our API.

Refer to http://swiftmailer.org/docs/messages on what is possible with a t3lib_mail_message.

Additionally, the whole "Transport" and "Mailer" magic required to really send a created message is accessed by simply calling $mail->send() (this is not possible in pure Swift_Message).

TYPO3 core will take care of sending the mail through the configured mailer engine.

Sending the mail

Swift Mailer allows to send emails through:

  • direct SMTP, which is the most flexible and cross-plattform solution (can even deal with encryption and authentication)
  • call to local "sendmail"
  • or as the last fallback using PHP's mail() function, which is the most unflexible option.

Refer to http://swiftmailer.org/docs/sending.html#transport-types

In the install tool we have this configurable so that the core and extensions don't have to take care of anything when sending emails.

 1 # $TYPO3_CONF_VARS['MAIL']['transport'] = 'smtp' | 'sendmail' | 'mail'
 2 
 3 $TYPO3_CONF_VARS['MAIL']['transport'] = 'smtp';
 4 $TYPO3_CONF_VARS['MAIL']['transport_smtp_server'] = 'smtp.example.org';
 5 $TYPO3_CONF_VARS['MAIL']['transport_smtp_port'] = '25';
 6 $TYPO3_CONF_VARS['MAIL']['transport_smtp_encrypt'] = FALSE; # requires openssl in PHP
 7 $TYPO3_CONF_VARS['MAIL']['transport_smtp_username'] = 'username';
 8 $TYPO3_CONF_VARS['MAIL']['transport_smtp_password'] = 'password';
 9 
10 $TYPO3_CONF_VARS['MAIL']['transport'] = 'sendmail';
11 $TYPO3_CONF_VARS['MAIL']['transport_sendmail_command'] = '/usr/sbin/sendmail -bs'
12 
13 $TYPO3_CONF_VARS['MAIL']['transport'] = 'mail';

Everything until this point is handled RFC 15998, already pending in the core list.

Step 2: Adding attachments (either inline or embedded) to mails

SwiftMailer allows to add attachments easily to a Message object, but it requires instances of Swift_Attachment. The plan is to have a t3lib_mail_attachment adapter, which hides the Swift_Attachment details and provide some nicer hooks into TYPO3 functionality (e.g. future sys_file etc).

Other helper methods will be added to t3lib_mail_message to hide the "details" of simply attaching a file:

1 function attachFromFile($filename, $mimeType);
2 function attachData($data, $filename, $mimeType);
3 function embedFromFile($filename, $mimeType); # returns a "cid:" url that can be used inline
4 function embedData($data, $filename, $mimeType); # returns a "cid:" url that can be used inline

Step 3: Fetching a remote URL and tranforming that into a mail

This is for example used by direct_mail. An idea on how to implement that would be:

1 $mail = t3lib_div::makeInstance('t3lib_mail_messageFromUrl');
2 $mail->setUrl('http://www.example.com');
3 $mail->setAttachmentsEmbedded();
4 $mail->setTo(array($email => $name));
5 $mail->setSubject($subject);
6 $mail->setBody($body);
7 $mail->send();

The functions in t3lib_htmlmail which currently deal with parsing HTML etc should be moved to a dedicated utility class (the stuff is non-mail-related and doesn't belong to the t3lib_mail namespace).

Implementation in FLOW3

See http://forge.typo3.org/projects/package-typo3-swiftmailer

Usage:

1 $this->objectManager->create('F3\SwiftMailer\Message')
2   ->setFrom(array($email => $name))
3   ->setTo(array($email => $name))
4   ->setSubject($subject)
5   ->setBody($body)
6   ->send();