tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

API Deprecated global email methods, moved to Mailer class

Browse Source 
Code reorganization to reduce global scope pollution.
Removed non-functional `$inlineImages` option for sending emails.
This commit is contained in:
Ingo Schommer 2012-12-03 00:02:47 +01:00
parent 4d106aa998
commit fb076c0396
3 changed files with 421 additions and 375 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/changelogs/3.1.0.md
View File

@ -14,3 +14,5 @@
* Removed `Member_ProfileForm`, use `CMSProfileController` instead * Removed `Member_ProfileForm`, use `CMSProfileController` instead
* `SiteTree::$nested_urls` enabled by default. To disable, call `SiteTree::disable_nested_urls()`. * `SiteTree::$nested_urls` enabled by default. To disable, call `SiteTree::disable_nested_urls()`.
* Removed CMS permission checks from `File->canEdit()` and `File->canDelete()`. If you have unsecured controllers relying on these permissions, please override them through a `DataExtension`. * Removed CMS permission checks from `File->canEdit()` and `File->canDelete()`. If you have unsecured controllers relying on these permissions, please override them through a `DataExtension`.
* Deprecated global email methods `htmlEmail()` and `plaintextEmail`, as well as various email helper methods like `encodeMultipart()`. Use the `Email` API, or the `Mailer` class where applicable.
* Removed non-functional `$inlineImages` option for sending emails

2
email/Email.php
View File

@ -360,7 +360,7 @@ class Email extends ViewableData {
} }
/** /**
* @desc Validates the email address. Returns true of false * Validates the email address. Returns true of false
*/ */
public static function validEmailAddress($address) { public static function validEmailAddress($address) {
if (function_exists('filter_var')) { if (function_exists('filter_var')) {

384
email/Mailer.php
View File

@ -6,7 +6,8 @@
* @package framework * @package framework
* @subpackage email * @subpackage email
*/ */
class Mailer extends Object { class Mailer {
/** /**
* Send a plain-text email. * Send a plain-text email.
* *
@ -19,35 +20,100 @@ class Mailer extends Object {
* @return bool * @return bool
*/ */
public function sendPlain($to, $from, $subject, $plainContent, $attachedFiles = false, $customheaders = false) { public function sendPlain($to, $from, $subject, $plainContent, $attachedFiles = false, $customheaders = false) {
return plaintextEmail($to, $from, $subject, $plainContent, $attachedFiles, $customheaders); // Not ensurely where this is supposed to be set, but defined it false for now to remove php notices
$plainEncoding = false;
if ($customheaders && is_array($customheaders) == false) {
echo "htmlEmail($to, $from, $subject, ...) could not send mail: improper \$customheaders passed:<BR>";
dieprintr($customheaders);
}
// If the subject line contains extended characters, we must encode it
$subject = Convert::xml2raw($subject);
$subject = "=?UTF-8?B?" . base64_encode($subject) . "?=";
// Make the plain text part
$headers["Content-Type"] = "text/plain; charset=utf-8";
$headers["Content-Transfer-Encoding"] = $plainEncoding ? $plainEncoding : "quoted-printable";
$plainContent = ($plainEncoding == "base64")
? chunk_split(base64_encode($plainContent),60)
: $this->QuotedPrintable_encode($plainContent);
// Messages with attachments are handled differently
if($attachedFiles) {
// The first part is the message itself
$fullMessage = $this->processHeaders($headers, $plainContent);
$messageParts = array($fullMessage);
// Include any specified attachments as additional parts
foreach($attachedFiles as $file) {
if(isset($file['tmp_name']) && isset($file['name'])) {
$messageParts[] = $this->encodeFileForEmail($file['tmp_name'], $file['name']);
} else {
$messageParts[] = $this->encodeFileForEmail($file);
}
}
// We further wrap all of this into another multipart block
list($fullBody, $headers) = $this->encodeMultipart($messageParts, "multipart/mixed");
// Messages without attachments do not require such treatment
} else {
$fullBody = $plainContent;
}
// Email headers
$headers["From"] = $this->validEmailAddr($from);
// Messages with the X-SilverStripeMessageID header can be tracked
if(isset($customheaders["X-SilverStripeMessageID"]) && defined('BOUNCE_EMAIL')) {
$bounceAddress = BOUNCE_EMAIL;
// Get the human name from the from address, if there is one
if(preg_match('/^([^<>]+)<([^<>])> *$/', $from, $parts))
$bounceAddress = "$parts[1]<$bounceAddress>";
} else {
$bounceAddress = $from;
}
// $headers["Sender"] = $from;
$headers["X-Mailer"] = X_MAILER;
if(!isset($customheaders["X-Priority"])) {
$headers["X-Priority"] = 3;
}
$headers = array_merge((array)$headers, (array)$customheaders);
// the carbon copy header has to be 'Cc', not 'CC' or 'cc' -- ensure this.
if (isset($headers['CC'])) { $headers['Cc'] = $headers['CC']; unset($headers['CC']); }
if (isset($headers['cc'])) { $headers['Cc'] = $headers['cc']; unset($headers['cc']); }
// Send the email
$headers = $this->processHeaders($headers);
$to = $this->validEmailAddr($to);
// Try it without the -f option if it fails
if(!$result = @mail($to, $subject, $fullBody, $headers, "-f$bounceAddress"))
$result = mail($to, $subject, $fullBody, $headers);
if($result)
return array($to,$subject,$fullBody,$headers);
return false;
} }
/** /**
* Send a multi-part HTML email.
*
* @return bool
*/
public function sendHTML($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false,
$plainContent = false, $inlineImages = false) {
return htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles, $customheaders,
$plainContent, $inlineImages);
}
}
// TO DO: Clean this code up, make it more OO.
// For now, we've just put a clean interface around this dirty code :)
/*
* Sends an email as a both HTML and plaintext * Sends an email as a both HTML and plaintext
*
* $attachedFiles should be an array of file names * $attachedFiles should be an array of file names
* - if you pass the entire $_FILES entry, the user-uploaded filename will be preserved * - if you pass the entire $_FILES entry, the user-uploaded filename will be preserved
* use $plainContent to override default plain-content generation * use $plainContent to override default plain-content generation
* *
* @return bool * @return bool
*/ */
function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false, public function sendHTML($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false,
$plainContent = false, $inlineImages = false) { $plainContent = false) {
if ($customheaders && is_array($customheaders) == false) { if ($customheaders && is_array($customheaders) == false) {
echo "htmlEmail($to, $from, $subject, ...) could not send mail: improper \$customheaders passed:<BR>"; echo "htmlEmail($to, $from, $subject, ...) could not send mail: improper \$customheaders passed:<BR>";
@ -74,9 +140,9 @@ function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $
$headers["Content-Type"] = "text/plain; charset=utf-8"; $headers["Content-Type"] = "text/plain; charset=utf-8";
$headers["Content-Transfer-Encoding"] = $plainEncoding ? $plainEncoding : "quoted-printable"; $headers["Content-Transfer-Encoding"] = $plainEncoding ? $plainEncoding : "quoted-printable";
$plainPart = processHeaders($headers, ($plainEncoding == "base64") $plainPart = $this->processHeaders($headers, ($plainEncoding == "base64")
? chunk_split(base64_encode($plainContent),60) ? chunk_split(base64_encode($plainContent),60)
: wordwrap(QuotedPrintable_encode($plainContent),75)); : wordwrap($this->QuotedPrintable_encode($plainContent),75));
// Make the HTML part // Make the HTML part
$headers["Content-Type"] = "text/html; charset=utf-8"; $headers["Content-Type"] = "text/html; charset=utf-8";
@ -96,33 +162,32 @@ function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $
"</HTML>"; "</HTML>";
} }
if($inlineImages) {
$htmlPart = wrapImagesInline($htmlContent);
} else {
$headers["Content-Transfer-Encoding"] = "quoted-printable"; $headers["Content-Transfer-Encoding"] = "quoted-printable";
$htmlPart = processHeaders($headers, wordwrap(QuotedPrintable_encode($htmlContent),75)); $htmlPart = $this->processHeaders($headers, wordwrap($this->QuotedPrintable_encode($htmlContent),75));
}
list($messageBody, $messageHeaders) = encodeMultipart(array($plainPart,$htmlPart), "multipart/alternative"); list($messageBody, $messageHeaders) = $this->encodeMultipart(
array($plainPart,$htmlPart),
"multipart/alternative"
);
// Messages with attachments are handled differently // Messages with attachments are handled differently
if($attachedFiles && is_array($attachedFiles)) { if($attachedFiles && is_array($attachedFiles)) {
// The first part is the message itself // The first part is the message itself
$fullMessage = processHeaders($messageHeaders, $messageBody); $fullMessage = $this->processHeaders($messageHeaders, $messageBody);
$messageParts = array($fullMessage); $messageParts = array($fullMessage);
// Include any specified attachments as additional parts // Include any specified attachments as additional parts
foreach($attachedFiles as $file) { foreach($attachedFiles as $file) {
if(isset($file['tmp_name']) && isset($file['name'])) { if(isset($file['tmp_name']) && isset($file['name'])) {
$messageParts[] = encodeFileForEmail($file['tmp_name'], $file['name']); $messageParts[] = $this->encodeFileForEmail($file['tmp_name'], $file['name']);
} else { } else {
$messageParts[] = encodeFileForEmail($file); $messageParts[] = $this->encodeFileForEmail($file);
} }
} }
// We further wrap all of this into another multipart block // We further wrap all of this into another multipart block
list($fullBody, $headers) = encodeMultipart($messageParts, "multipart/mixed"); list($fullBody, $headers) = $this->encodeMultipart($messageParts, "multipart/mixed");
// Messages without attachments do not require such treatment // Messages without attachments do not require such treatment
} else { } else {
@ -131,7 +196,7 @@ function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $
} }
// Email headers // Email headers
$headers["From"] = validEmailAddr($from); $headers["From"] = $this->validEmailAddr($from);
// Messages with the X-SilverStripeMessageID header can be tracked // Messages with the X-SilverStripeMessageID header can be tracked
if(isset($customheaders["X-SilverStripeMessageID"]) && defined('BOUNCE_EMAIL')) { if(isset($customheaders["X-SilverStripeMessageID"]) && defined('BOUNCE_EMAIL')) {
@ -159,8 +224,8 @@ function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $
// Send the email // Send the email
$headers = processHeaders($headers); $headers = $this->processHeaders($headers);
$to = validEmailAddr($to); $to = $this->validEmailAddr($to);
// Try it without the -f option if it fails // Try it without the -f option if it fails
if(!($result = @mail($to, $subject, $fullBody, $headers, "-f$bounceAddress"))) { if(!($result = @mail($to, $subject, $fullBody, $headers, "-f$bounceAddress"))) {
@ -170,94 +235,9 @@ function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $
return $result; return $result;
} }
/* /**
* Send a plain text e-mail * @todo Make visibility protected in 3.2
*/ */
function plaintextEmail($to, $from, $subject, $plainContent, $attachedFiles, $customheaders = false) {
// Not ensurely where this is supposed to be set, but defined it false for now to remove php notices
$plainEncoding = false;
if ($customheaders && is_array($customheaders) == false) {
echo "htmlEmail($to, $from, $subject, ...) could not send mail: improper \$customheaders passed:<BR>";
dieprintr($customheaders);
}
// If the subject line contains extended characters, we must encode it
$subject = Convert::xml2raw($subject);
$subject = "=?UTF-8?B?" . base64_encode($subject) . "?=";
// Make the plain text part
$headers["Content-Type"] = "text/plain; charset=utf-8";
$headers["Content-Transfer-Encoding"] = $plainEncoding ? $plainEncoding : "quoted-printable";
$plainContent = ($plainEncoding == "base64")
? chunk_split(base64_encode($plainContent),60)
: QuotedPrintable_encode($plainContent);
// Messages with attachments are handled differently
if($attachedFiles) {
// The first part is the message itself
$fullMessage = processHeaders($headers, $plainContent);
$messageParts = array($fullMessage);
// Include any specified attachments as additional parts
foreach($attachedFiles as $file) {
if(isset($file['tmp_name']) && isset($file['name'])) {
$messageParts[] = encodeFileForEmail($file['tmp_name'], $file['name']);
} else {
$messageParts[] = encodeFileForEmail($file);
}
}
// We further wrap all of this into another multipart block
list($fullBody, $headers) = encodeMultipart($messageParts, "multipart/mixed");
// Messages without attachments do not require such treatment
} else {
$fullBody = $plainContent;
}
// Email headers
$headers["From"] = validEmailAddr($from);
// Messages with the X-SilverStripeMessageID header can be tracked
if(isset($customheaders["X-SilverStripeMessageID"]) && defined('BOUNCE_EMAIL')) {
$bounceAddress = BOUNCE_EMAIL;
// Get the human name from the from address, if there is one
if(preg_match('/^([^<>]+)<([^<>])> *$/', $from, $parts))
$bounceAddress = "$parts[1]<$bounceAddress>";
} else {
$bounceAddress = $from;
}
// $headers["Sender"] = $from;
$headers["X-Mailer"] = X_MAILER;
if(!isset($customheaders["X-Priority"])) {
$headers["X-Priority"] = 3;
}
$headers = array_merge((array)$headers, (array)$customheaders);
// the carbon copy header has to be 'Cc', not 'CC' or 'cc' -- ensure this.
if (isset($headers['CC'])) { $headers['Cc'] = $headers['CC']; unset($headers['CC']); }
if (isset($headers['cc'])) { $headers['Cc'] = $headers['cc']; unset($headers['cc']); }
// Send the email
$headers = processHeaders($headers);
$to = validEmailAddr($to);
// Try it without the -f option if it fails
if(!$result = @mail($to, $subject, $fullBody, $headers, "-f$bounceAddress"))
$result = mail($to, $subject, $fullBody, $headers);
if($result)
return array($to,$subject,$fullBody,$headers);
return false;
}
function encodeMultipart($parts, $contentType, $headers = false) { function encodeMultipart($parts, $contentType, $headers = false) {
$separator = "----=_NextPart_" . preg_replace('/[^0-9]/', '', rand() * 10000000000); $separator = "----=_NextPart_" . preg_replace('/[^0-9]/', '', rand() * 10000000000);
@ -283,46 +263,8 @@ function encodeMultipart($parts, $contentType, $headers = false) {
return array($body, $headers); return array($body, $headers);
} }
/* /**
* Return a multipart/related e-mail chunk for the given HTML message and its linked images * @todo Make visibility protected in 3.2
* Decodes absolute URLs, accessing the appropriate local images
*/
function wrapImagesInline($htmlContent) {
global $_INLINED_IMAGES;
$_INLINED_IMAGES = null;
$replacedContent = imageRewriter($htmlContent, 'wrapImagesInline_rewriter($URL)');
// Make the HTML part
$headers["Content-Type"] = "text/html; charset=utf-8";
$headers["Content-Transfer-Encoding"] = "quoted-printable";
$multiparts[] = processHeaders($headers, QuotedPrintable_encode($replacedContent));
// Make all the image parts
global $_INLINED_IMAGES;
foreach($_INLINED_IMAGES as $url => $cid) {
$multiparts[] = encodeFileForEmail($url, false, "inline", "Content-ID: <$cid>\n");
}
// Merge together in a multipart
list($body, $headers) = encodeMultipart($multiparts, "multipart/related");
return processHeaders($headers, $body);
}
function wrapImagesInline_rewriter($url) {
$url = relativiseURL($url);
global $_INLINED_IMAGES;
if(!$_INLINED_IMAGES[$url]) {
$identifier = "automatedmessage." . rand(1000,1000000000) . "@silverstripe.com";
$_INLINED_IMAGES[$url] = $identifier;
}
return "cid:" . $_INLINED_IMAGES[$url];
}
/*
* Combine headers w/ the body into a single string.
*/ */
function processHeaders($headers, $body = false) { function processHeaders($headers, $body = false) {
$res = ''; $res = '';
@ -346,19 +288,20 @@ function processHeaders($headers, $body = false) {
* *
* h5. contentLocation * h5. contentLocation
* *
* Content Location is one of the two methods allowed for embedding images into an html email. It's also the simplest, * Content Location is one of the two methods allowed for embedding images into an html email.
* and best supported. * It's also the simplest, and best supported.
* *
* Assume we have an email with this in the body: * Assume we have an email with this in the body:
* *
* <img src="http://example.com/image.gif" /> * <img src="http://example.com/image.gif" />
* *
* To display the image, an email viewer would have to download the image from the web every time it is displayed. Due * To display the image, an email viewer would have to download the image from the web every time
* to privacy issues, most viewers will not display any images unless the user clicks 'Show images in this email'. Not * it is displayed. Due to privacy issues, most viewers will not display any images unless
* optimal. * the user clicks 'Show images in this email'. Not optimal.
* *
* However, we can also include a copy of this image as an attached file in the email. By giving it a contentLocation * However, we can also include a copy of this image as an attached file in the email.
* of "http://example.com/image.gif" most email viewers will use this attached copy instead of downloading it. Better, * By giving it a contentLocation of "http://example.com/image.gif" most email viewers
* will use this attached copy instead of downloading it. Better,
* most viewers will show it without a 'Show images in this email' conformation. * most viewers will show it without a 'Show images in this email' conformation.
* *
* Here is an example of passing this information through Email.php: * Here is an example of passing this information through Email.php:
@ -371,6 +314,7 @@ function processHeaders($headers, $body = false) {
* 'contentLocation' => Director::absoluteBaseURL() . "/themes/mytheme/images/header.gif" * 'contentLocation' => Director::absoluteBaseURL() . "/themes/mytheme/images/header.gif"
* ); * );
* *
* @todo Make visibility protected in 3.2
*/ */
function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $extraHeaders = "") { function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $extraHeaders = "") {
if(!$file) { if(!$file) {
@ -403,7 +347,7 @@ function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $
// This mime type is needed, otherwise some clients will show it as an inline attachment // This mime type is needed, otherwise some clients will show it as an inline attachment
$mimeType = 'application/octet-stream'; $mimeType = 'application/octet-stream';
$encoding = "quoted-printable"; $encoding = "quoted-printable";
$file['contents'] = QuotedPrintable_encode($file['contents']); $file['contents'] = $this->QuotedPrintable_encode($file['contents']);
} }
$headers = "Content-type: $mimeType;\n\tname=\"$base\"\n". $headers = "Content-type: $mimeType;\n\tname=\"$base\"\n".
@ -418,6 +362,9 @@ function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $
return $headers . $file['contents']; return $headers . $file['contents'];
} }
/**
* @todo Make visibility protected in 3.2
*/
function QuotedPrintable_encode($quotprint) { function QuotedPrintable_encode($quotprint) {
$quotprint = (string)str_replace('\r\n',chr(13).chr(10),$quotprint); $quotprint = (string)str_replace('\r\n',chr(13).chr(10),$quotprint);
$quotprint = (string)str_replace('\n', chr(13).chr(10),$quotprint); $quotprint = (string)str_replace('\n', chr(13).chr(10),$quotprint);
@ -430,6 +377,9 @@ function QuotedPrintable_encode($quotprint) {
return (string) $quotprint; return (string) $quotprint;
} }
/**
* @todo Make visibility protected in 3.2
*/
function validEmailAddr($emailAddress) { function validEmailAddr($emailAddress) {
$emailAddress = trim($emailAddress); $emailAddress = trim($emailAddress);
$angBrack = strpos($emailAddress, '<'); $angBrack = strpos($emailAddress, '<');
@ -444,3 +394,97 @@ function validEmailAddr($emailAddress) {
return $emailAddress; return $emailAddress;
} }
}
/**
* @deprecated 3.1
*/
function htmlEmail($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false,
$plainContent = false) {
Deprecation::notice('3.1', 'Use Email->sendHTML() instead');
$mailer = Injector::inst()->create('Mailer');
return $mailer->sendHTML($to, $from, $subject, $plainContent, $attachedFiles, $customheaders = false);
}
/**
* @deprecated 3.1
*/
function plaintextEmail($to, $from, $subject, $plainContent, $attachedFiles, $customheaders = false) {
Deprecation::notice('3.1', 'Use Email->sendPlain() instead');
$mailer = Injector::inst()->create('Mailer');
return $mailer->sendPlain($to, $from, $subject, $plainContent, $attachedFiles, $customheaders = false);
}
/**
* @deprecated 3.1
*/
function encodeMultipart($parts, $contentType, $headers = false) {
Deprecation::notice('3.1', 'Use Email->$this->encodeMultipart() instead');
$mailer = Injector::inst()->create('Mailer');
return $mailer->encodeMultipart($parts, $contentType, $headers = false);
}
/**
* @deprecated 3.1
*/
function wrapImagesInline($htmlContent) {
Deprecation::notice('3.1', 'Functionality removed from core');
$mailer = Injector::inst()->create('Mailer');
return $mailer->wrapImagesInline($htmlContent);
}
/**
* @deprecated 3.1
*/
function wrapImagesInline_rewriter($url) {
Deprecation::notice('3.1', 'Functionality removed from core');
$mailer = Injector::inst()->create('Mailer');
return $mailer->wrapImagesInline_rewriter($url);
}
/**
* @deprecated 3.1
*/
function processHeaders($headers, $body = false) {
Deprecation::notice('3.1', 'Set headers through Email->addCustomHeader()');
$mailer = Injector::inst()->create('Mailer');
return $mailer->processHeaders($headers, $url);
}
/**
* @deprecated 3.1
*/
function encodeFileForEmail($file, $destFileName = false, $disposition = NULL, $extraHeaders = "") {
Deprecation::notice('3.1', 'Please add files through Email->attachFile()');
$mailer = Injector::inst()->create('Mailer');
return $mailer->encodeFileForEmail($file, $destFileName, $disposition, $extraHeaders);
}
/**
* @deprecated 3.1
*/
function QuotedPrintable_encode($quotprint) {
Deprecation::notice('3.1', 'No longer available, handled internally');
$mailer = Injector::inst()->create('Mailer');
return $mailer->QuotedPrintable_encode($quotprint);
}
/**
* @deprecated 3.1
*/
function validEmailAddr($emailAddress) {
Deprecation::notice('3.1', 'Use Email->validEmailAddr() instead');
$mailer = Injector::inst()->create('Mailer');
return $mailer->validEmailAddr($emailAddress);
}