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

Review email documentation

Browse Source
This commit is contained in:
Will Rossiter 2014-09-28 21:39:59 +13:00 committed by Cam Findlay
parent 3d8c9232e0
commit c54dee5452
1 changed files with 157 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

219
docs/en/02_Developer_Guides/10_Email/index.md
View File

@ -2,104 +2,153 @@ summary: Send HTML and plain text email from your SilverStripe application.
# Email # Email
SilverStripe has emailing functionality using the built-in mail() function in PHP. Creating and sending email in SilverStripe is done through the [api:Email] and [api:Mailer] classes. This document
Features include sending plaintext- and HTML emails, sending bulk emails, subscription, handling bounced back emails. covers how to create an `Email` instance, customize it with a HTML template, then send it through a custom `Mailer`.
## Configuration ## Configuration
Your PHP configuration needs to include the SMTP module for sending emails. Out of the box, SilverStripe will use the built-in PHP `mail()` command. If you are not running an SMTP server, you
If you are not running an SMTP server together with your webserver, you might need to setup PHP with the credentials for will need to either configure PHP's SMTP settings (see [PHP documentation](http://php.net/mail) to include your mail
an external SMTP server (see [PHP documentation for mail()](http://php.net/mail)). server configuration or use one of the third party SMTP services like [Mandrill](https://github.com/lekoala/silverstripe-mandrill)
and [Postmark](https://github.com/fullscreeninteractive/silverstripe-postmarkmailer).
## Usage ## Usage
### Sending combined HTML and Plaintext ### Sending plain text only
By default, emails are sent in both HTML and Plaintext format.
A plaintext representation is automatically generated from the system
by stripping HTML markup, or transforming it where possible
(e.g. `<strong>text</strong>` is converted to `*text*`).
:::php
$email = new Email($from, $to, $subject, $body);
$email->send();
The default HTML template is located in `framework/templates/email/GenericEmail.ss`.
### Sending Plaintext only
:::php :::php
$email = new Email($from, $to, $subject, $body); $email = new Email($from, $to, $subject, $body);
$email->sendPlain(); $email->sendPlain();
### Templates ### Sending combined HTML and plain text
* Create a SS-template file called, in this example we will use 'MyEmail.ss' inside `mysite/templates/email`. By default, emails are sent in both HTML and Plaintext format. A plaintext representation is automatically generated
* Fill this out with the body text for your email. You can use any [SS-template syntax](/topics/templates) (e.g. `<% loop %>`, from the system by stripping HTML markup, or transforming it where possible (e.g. `<strong>text</strong>` is converted
`<% if %>`, $FirstName etc) to `*text*`).
* Choose your template with **setTemplate()**
* Populate any custom data into the template before sending with **populateTemplate()**
Example:
:::php :::php
$email = new Email($from, $to, $subject, $body); $email = new Email($from, $to, $subject, $body);
$email->setTemplate('MyEmail'); $email->send();
// You can call this multiple times or bundle everything into an array, including DataSetObjects <div class="info" markdown="1">
$email->populateTemplate(Member::currentUser()); The default HTML template for emails is named `GenericEmail` and is located in `framework/templates/email/`. To
customize this template, copy it to the `mysite/templates/Email/` folder or use `setTemplate` when you create the
`Email` instance.
</div>
$welcomeMsg = 'Thank you for joining on '.date('Y-m-d'.'!');
$email->populateTemplate(array( ### Templates
'WelcomeMessage' => $welcomeMsg, // Accessible in template via $WelcomeMessage
)); HTML emails can use custom templates using the same template language as your website template. You can also pass the
email object additional information using the `populateTemplate` method.
**mysite/templates/Email/MyCustomEmail.ss**
:::ss
<h1>Hi $Member.FirstName</h1>
<p>You can go to $Link.</p>
The PHP Logic..
:::php
$email = new Email();
$email
->setFrom($from)
->setTo($to)
->setSubject($subject)
->setTemplate('MyCustomEmail')
->populateTemplate(new ArrayData(array(
'Member' => Member::currentUser(),
'Link' => $link
)));
$email->send(); $email->send();
<div class="alert" markdown="1">
As we've added a new template file (`MyCustomEmail`) make sure you clear the SilverStripe cache for your changes to
take affect.
</div>
### Subclassing ## Sub classing
Class definition: To keep your application code clean and your internal API clear, a better approach to generating an email is to create
a new subclass of `Email` which takes the required dependencies and handles setting the properties itself.
**mysite/code/MyCustomEmail.php**
:::php :::php
<?php <?php
class MyEmail extends Email{
protected class MyEmail extends Email {
$to = '$Email', // Be sure to encase this in single-quotes, as it is evaluated later by the template parser
$from = 'email@email.com', protected $ss_template = "MyEmail";
$ss_template = 'MyEmail';
public function __construct($member) {
$from = 'no-reply@mysite.com';
$to = $member->Email;
$subject = "Welcome to our site.";
$link = Director::absoluteBaseUrl();
parent::__construct($from, $to, $subject);
$this->populateTemplate(new ArrayData(array(
'Member' => $member->Email,
'Link' => $link
)));
}
} }
Then within your application, usage of the email is much clearer to follow.
Usage:
:::php :::php
<?php <?php
$email = new MyEmail(); $member = Member::currentUser();
$email->populateTemplate(Member::currentUser()); // This will populate the template, $to, $from etc variables if they exist
$email->send(); // Will immediately send an HTML email with appropriate plain-text content $email = new MyEmail($member);
$email->send();
### Administrator Emails ## Administrator Emails
You can influence the default sender address of emails through the `Email.admin_email` You can set the default sender address of emails through the `Email.admin_email` [configuration setting](/developer_guides/configuration).
[configuration setting](/topics/configuration). This address is used if the `from` field is empty.
### Redirecting Emails **mysite/_config/app.yml**
Further [configuration settings](/topics/configuration) relating to email rewriting: :::yaml
Email:
admin_email: support@silverstripe.org
* `Email.send_all_emails_to` will redirect all emails sent to the given address. Handy for testing!
* `Email.cc_all_emails_to` and `Email.bcc_all_emails_to` will keep the email going to its original recipients, but <div class="alert" markdown="1">
add an additional recipient in the BCC/CC header. Good for monitoring system-generated correspondence on the live Remember, setting a `from` address that doesn't come from your domain (such as the users email) will likely see your
systems. email marked as spam. If you want to send from another address think about using the `replyTo` method.
</div>
## Redirecting Emails
There are several other [configuration settings](/developer_guides/configuration) to manipulate the email server.
* `Email.send_all_emails_to` will redirect all emails sent to the given address. This is useful for testing and staging
servers where you do not wish to send emails out.
* `Email.cc_all_emails_to` and `Email.bcc_all_emails_to` will add an additional recipient in the BCC / CC header.
These are good for monitoring system-generated correspondence on the live systems.
Configuration of those properties looks like the following:
**mysite/_config.php**
:::php :::php
if(Director::isLive()) Config::inst()->update('Email', 'bcc_all_emails_to', "client@example.com"); if(Director::isLive()) {
else Config::inst()->update('Email', 'send_all_emails_to', "developer@example.com"); Config::inst()->update('Email', 'bcc_all_emails_to', "client@example.com");
} else {
Config::inst()->update('Email', 'send_all_emails_to', "developer@example.com");
}
### Setting custom replyTo
:::php
$email = new Email(..);
$email->replyTo('me@address.com');
### Setting Custom Headers ### Setting Custom Headers
@ -111,13 +160,59 @@ $value)**
$email->addCustomHeader('HeaderName', 'HeaderValue'); $email->addCustomHeader('HeaderName', 'HeaderValue');
.. ..
<div class="info" markdown="1">
See this [Wikipedia](http://en.wikipedia.org/wiki/E-mail#Message_header) entry for a list of header names.
</div>
See [Wikipedia E-mail Message header](http://en.wikipedia.org/wiki/E-mail#Message_header) for a list of header names. ## Newsletters
### Newsletters
The [newsletter module](http://silverstripe.org/newsletter-module) provides a UI and logic to send batch emails. The [newsletter module](http://silverstripe.org/newsletter-module) provides a UI and logic to send batch emails.
## Custom Mailers
SilverStripe supports changing out the underlying web server SMTP mailer service through the `Email::set_mailer()`
function. A `Mailer` subclass will commonly override the `sendPlain` and `sendHTML` methods to send emails through curl
or some other process that isn't the built in `mail()` command.
<div class="info" markdown="1">
There are a number of custom mailer add-ons available like [Mandrill](https://github.com/lekoala/silverstripe-mandrill)
and [Postmark](https://github.com/fullscreeninteractive/silverstripe-postmarkmailer).
</div>
In this example, `LocalMailer` will take any email's going while the site is in Development mode and save it to the
assets folder instead.
**mysite/code/LocalMailer.php**
:::php
<?php
class LocalMailer extends Mailer {
function sendHTML($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false, $plainContent = false, $inlineImages = false) {
$file = ASSETS_PATH . '/_mail_'. urlencode(sprintf("%s_%s", $subject, $to));
file_put_contents($file, $htmlContent);
}
function sendPlain($to, $from, $subject, $htmlContent, $attachedFiles = false, $customheaders = false, $plainContent = false, $inlineImages = false) {
$file = ASSETS_PATH . '/_mail_'. urlencode(sprintf("%s_%s", $subject, $to));
file_put_contents($file, $htmlContent);
}
}
**mysite/_config.php**
:::php
if(Director::isLive()) {
Email::set_mailer(new PostmarkMailer());
} else {
Email::set_mailer(new LocalMailer());
}
### Setting bounce handler ### Setting bounce handler
A bounce handler email can be specified one of a few ways: A bounce handler email can be specified one of a few ways:
@ -128,4 +223,4 @@ A bounce handler email can be specified one of a few ways:
## API Documentation ## API Documentation
`[api:Email]` * [api:Email]