sFire PHP Framework
sFire\Mail\Mail lets you send emails while using the PHP mail method. It is a wrapper interface for easy mailing. Adding attachments, send custom headers and adding carbon copy email addresses are just some of the features sFire\Mail\Mail supports.
To use the Mail client you should create a new instance:
use sFire\Mail\Mail;
$mail = new Mail();
It is easy to send a mail. Pass a callable function to the send method to set options like in the example below.
$mail -> send(function($mail) {
$mail -> to('john@domain.com', 'John Doe');
$mail -> to('james@domain.com', 'James Smith');
$mail -> message('html content', 'plain text content');
});
This will send an email to "john@domain.com" and "james@domain.com" with "html content" as message content if the receivers email client supports HTML and "plain text content" as message content if not.
To add a subject, you can use the subject method. It accepts a String parameter.
$mail -> send(function($mail) {
$mail -> to('email@domain.com', 'John Do');
$mail -> message('html content', 'plain text content');
$mail -> subject('Hello mail!');
});
You can add a view or you can add a String as message of an email.
To send a ViewModel as message you can use the render method. This method accepts two String parameters with the paths (directory separator as a dot). The first parameter is the HTML view and the second parameters is the plain text view for the email. Only one is required, but using both is recommended for optimal support.
$mail -> send(function($mail) {
$mail -> render('mail.register.html', 'mail.register.text');
$mail -> to('email@domain.com', 'John Do');
$mail -> subject('Hello mail!');
});
This will render the "view/mail/register/html.tpl" and "view/mail/register/text.tpl" templates.
To send plain text you can use the message method. This method also accepts two String parameters with HTML and plain text content. Only one is required, but using both is recommended for optimal support.
$mail -> send(function($mail) {
$mail -> message('html content', 'plain text content');
$mail -> to('email@domain.com', 'John Do');
$mail -> subject('Hello mail!');
});
To add a from, CC or BCC email address, you can use the form, cc and bcc method. The first parameter is a String email address and the second parameter is a String name.
$mail -> send(function($mail) {
$mail -> from('email@domain.com', 'My company name');
$mail -> cc('john@domain.com', 'John Doo');
$mail -> bcc('james@domain.com', 'James Smith');
$mail -> message('html content', 'plain text content');
});
You can add a notify email address to automatically send a mail if the received party has opened the mail, if the received mail client supports it. To do this, you can use the notify method. The first parameter is a String email address and the second parameter is a String name.
$mail -> send(function($mail) {
$mail -> notify('james@domain.com', 'James Smith');
$mail -> to('John@domain.com', 'John Doo');
$mail -> from('email@domain.com', 'My company name');
$mail -> message('html content', 'plain text content');
});
To add files to an email, you may use the attachment method. This method accepts three parameters.
$mail -> attachment(string $path | sFire\System\File $path, [string $name, string $mime]);
Example using sFire\System\File:
use sFire\System\File;
$attachment = new File('foo.txt');
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> attachment($attachment)
$mail -> message('html content', 'plain text content');
});
Example using String path:
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> attachment('path/to/file.txt');
$mail -> message('html content', 'plain text content');
});
Example setting new name and mime type:
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> attachment('path/to/file.txt', 'bar.txt', 'plain/text');
$mail -> message('html content', 'plain text content');
});
If you want to set a priority to the email, you may use the priority method. This method accepts an Integer between 1 and 5 where 1 is the default.
Levels explained:
| Level | Explanation |
|---|---|
| 1 | Highest |
| 2 | High |
| 3 | Normal |
| 4 | Lower |
| 5 | Lowest |
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> priority(4);
$mail -> message('html content', 'plain text content');
});
sFire\Mail\Mail lets you define your own custom headers. You can add new headers with the addHeader method, delete predefined custom headers with the removeHeader method and view all the custom headers with the getHeaders method.
Adding a new custom header is a breeze. Call the addHeader method which accepts two String parameters. The first parameter is the key/name of the header and the second parameter is the value/content of the header. All headers will automatically be separated with \n\r.
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> addHeader('X-Mailer', 'php');
$mail -> message('html content', 'plain text content');
});
After you added a new custom mail header, you can remove it:
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> addHeader('X-Mailer', 'php');
$mail -> removeHeader('X-Mailer');
$mail -> message('html content', 'plain text content');
});
To retrieve the custom headers, you can use the getHeaders method.
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> addHeader('X-Mailer', 'php');
$mail -> message('html content', 'plain text content');
print_r($mail -> getHeaders()); //Will output Array('X-Mailer' => 'php')
});
To determine if an email has been send successfully, you may use the success or failed method. Both methods returns a Boolean that will represent if the mail has failed or has been send.
Note: This checks if the local mail server (or the SMTP configured in php.ini) accepted the outgoing email. The mail server will then try to send the email to the recipient's mail server, but this is done after sFire\Mail\Mail returns.
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> message('html content', 'plain text content');
});
if(true === $mail -> success()) {
//Mail has been send successfully
}
$mail -> send(function($mail) {
$mail -> to('John@domain.com', 'John Doo');
$mail -> message('html content', 'plain text content');
});
if(true === $mail -> failed()) {
//Failed to send email
}