Monday, April 18, 2011

How to Send Emails with the Zend Framework

Introduction

Many PHP applications require the ability to send emails nowadays from simple plain-text emails confirming a registration to advanced HTML newsletters.

PHP allows us to send emails using the mail() function but this can quickly get complex when you begin to add HTML, attachments and different character encoding.

Luckily for us developers, the Zend_Mail component from the Zend Framework greatly simplifies the process by providing easy-to-use methods for creating and sending emails.

This article will walk you through creating and sending plain-text and HTML emails, adding attachments, multiple recipients and much more.


Requirements

To use the Zend_Mail component you will first need to download the Zend Framework.

Visit the Zend Framework download page and download the newest version of the Zend Framework (1.5RC1 at the time of writing).

Once downloaded, unzip the Zend Framework archive to your Desktop or Home folder. The folder we are interested in is the library folder. Copy the library folder and its contents to your web folder so that your PHP scripts can access it.


Sending Plain Text Emails

Sending plain text emails with the Zend Framework couldn't be easier. All you need it a sender, a recipient, a subject, and the email body itself.

Lets get started with our PHP script by setting up our include path to help our script find the Zend_Mail component:


PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);
This has told PHP that our Zend Framework classes are in the library folder in the current folder.

The next step is to include the Zend_Mail class:

PHP Code:
include_once 'Zend/Mail.php'
The Zend_Mail class has now been included into your script and is available for use.

Now we need to write the email that we wish to send. The example email below is a typical email that may be sent from any Helpdesk application to the user when they create a new Helpdesk ticket.

PHP Code:
$body 'Hi,

Thank you for submitting a ticket to our Helpdesk.

Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk'
This email could have been created from a template stored in a file or database and you could also process it to include the recipients name, change the reference number and so on.

Now that we have our email body ready we need to create the email itself complete with subject and recipients.

We start by creating a mail object from the Zend_Mail class:

PHP Code:
$mail = new Zend_Mail(); 
Now we have our mail object we can use it to add the sender, recipients, subject and body to our email:

PHP Code:
$mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Your helpdesk ticket #12345'); $mail->setBodyText($body); 
This PHP code should be fairly self-explanatory. First we use the setFrom()method to set the sender of the email. setFrom() takes two arguments, the email address and a descriptive name. The email address is required where as the descriptive name is optional so you can leave that our if you wish.

Next we use the addTo() method to add a recipient to our email. Like setFrom(), this takes two arguments, the email address and a descriptive name for the recipient. Again, only the email address argument is required here.

Now we set our email subject using the setSubject() method, and finally we set our plain-text email body using the setBodyText() method.

Now that our email is ready to go all we need to do is send it. As you might expect, the Zend_Mail class makes this simple by providing the send() method:

PHP Code:
$mail->send(); 
And that's all there is to it! You should now see an email appear in your inbox that looks something like the following:

Screenshot: Plain-Text Email Example

Below is the full code for sending plain-text emails with Zend_Mail:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Hi,

Thank you for submitting a ticket to our Helpdesk.

Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk'
;
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Your helpdesk ticket #12345'); $mail->setBodyText($body);
$mail->send();
Sending HTML Emails

Sending HTML emails with the built-in PHP mail() function used to be a chore. You would have to set the MIME-Version header, the Content-type header, and more.

The Zend_Mail component makes sending HTML emails as simple as sending plain-text emails. In fact, it's so simple, we only need to change two items from our previous example.

The first thing we need to change is the email body text. We are going to change it to the following to include some HTML:

PHP Code:
$body 'Hi!
Thank you for submitting a ticket to our Helpdesk.


Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk

'
As you can see we have included various HTML tags in the email so we can see our HTML email in action.

The next change we need to make to our previous code is to use the setBodyHtml method instead of the setBodyText() method:

PHP Code:
$mail->setBodyHtml($body); 
And that's all there is too it.

If you make these two changes to our original code and run it you will receive a HTML email that looks something like the following:

Screenshot: HTML Email Example

Below is the full code for our HTML email example:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Hi!
Thank you for submitting a ticket to our Helpdesk.


Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk

'
;
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Your helpdesk ticket #54321'); $mail->setBodyHtml($body);
$mail->send();

Adding Attachments

You will often find that you need to add one of more attachments to your emails. As you might expect, Zend_Mail makes this process simple.

First we need to setup our include path and include the Zend_Mail class as we did in the previous examples:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
The next step is to create the body of our email then add the sender, recipients, subject and body. For more details please see the plain-text email example above:

PHP Code:
$body 'Please find the zip file attached';
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('File attachment Test'); $mail->setBodyText($body); 
Now that we have our email ready to go we need to add the attachment. In this example we are going to add a zip file called test_file.zip so the first step is to get the contents of this file and store it in a variable:

PHP Code:
$fileContents file_get_contents('test_file.zip'); 
Now that $fileContents contains the contents of our zip file we use the createAttachment method to add it to our email:

PHP Code:
$attachment $mail->createAttachment($fileContents); 
And finally, we need to give our new attachment a filename:

PHP Code:
$attachment->filename 'test_file.zip'
Now we have our email with attachments ready we need to send it:

PHP Code:
$mail->send(); 
Check your inbox and you should find an email that looks something like:

Screenshot: Email with Attachment Example

You can use the createAttachment() method multiple times if you wish to add multiple attachments to an email.

Below is the full code to add attachments to your emails:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Please find the zip file attached';
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('File attachment Test'); $mail->setBodyText($body);
$fileContents file_get_contents('test_file.zip'); $attachment $mail->createAttachment($fileContents); $attachment->filename 'test_file.zip';
$mail->send();

Adding Multiple Recipients

Zend_Mail provides full support for adding CC and BCC recipients to your emails allowing you to send the mail to many people at once.

To add CC recipients to your email, you need to use the addCc() method:

PHP Code:
$mail->addCc('someone@example.com''Someone Else'); $mail->addCc('another@example.com''Another Recipient'); 
In this example, we have added two additional recipients. As you can see, addCc() takes the same arguments as the addTo() method, a recipients email address and a descriptive name for the recipient. The descriptive name is an optional argument so you can leave that out if you wish.

To add BCC recipients we use the addBcc() method:

PHP Code:
$mail->addBcc('topsecret@example.com''Top Secret Recipient'); 
This should be fairly straight-forward by now as it uses the same syntax as addTo() and addCc(), a required email address and an optional descriptive name.

Now use the send() method and you will receive an email that looks something like:

Screenshot: Multiple Recipients Email Example

Below is a full example of using Zend_Mail to send the same email to multiple recipients:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Hi all,

Don\'t forget that basketball training has been moved
from Tuesday to Wednesday.

See you all then!
Alan'
;
$mail = new Zend_Mail(); $mail->setFrom('alan@citconsultants.co.uk''Alan @ CIT'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->addCc('someone@example.com''Someone Else'); $mail->addCc('another@example.com''Another Recipient'); $mail->addBcc('topsecret@example.com''Top Secret Recipient'); $mail->setSubject('Basketball practice this week'); $mail->setBodyText($body);
$mail->send();

Adding Extra Headers

Occasionally you may find the you need to add extra email headers to your emails. Zend_Mail provides the addHeader() method for this purpose:

PHP Code:
$mail->addHeader('X-MailGenerator''MyPHPApplication v1.0'); 
If you then sent an email with this additional header then viewed the original / source of the email that you received you would see something like:

Screenshot: Mail with Extra Headers

Below is an example script that sends an email with an additional header:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Look at this cool email sent from MyPHPApplication v1.0!';
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Read me!'); $mail->setBodyText($body); $mail->addHeader('X-MailGenerator''MyPHPApplication v1.0');
$mail->send();

Conclusion

Hopefully this tutorial has shown you just how easy it is to send emails in PHP using the Zend_Mail component and the Zend Framework. The Zend_Mail component allows you to do many other advanced features such as changing character sets and even reading emails. Take a look at some of the links below to learn more about the Zend_Mail component.

Many PHP applications require the ability to send emails nowadays from simple plain-text emails confirming a registration to advanced HTML newsletters.

PHP allows us to send emails using the mail() function but this can quickly get complex when you begin to add HTML, attachments and different character encoding.

Luckily for us developers, the Zend_Mail component from the Zend Framework greatly simplifies the process by providing easy-to-use methods for creating and sending emails.

This article will walk you through creating and sending plain-text and HTML emails, adding attachments, multiple recipients and much more.


Requirements

To use the Zend_Mail component you will first need to download the Zend Framework.

Visit the Zend Framework download page and download the newest version of the Zend Framework (1.5RC1 at the time of writing).

Once downloaded, unzip the Zend Framework archive to your Desktop or Home folder. The folder we are interested in is the library folder. Copy the library folder and its contents to your web folder so that your PHP scripts can access it.


Sending Plain Text Emails

Sending plain text emails with the Zend Framework couldn't be easier. All you need it a sender, a recipient, a subject, and the email body itself.

Lets get started with our PHP script by setting up our include path to help our script find the Zend_Mail component:


PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);
This has told PHP that our Zend Framework classes are in the library folder in the current folder.

The next step is to include the Zend_Mail class:

PHP Code:
include_once 'Zend/Mail.php'
The Zend_Mail class has now been included into your script and is available for use.

Now we need to write the email that we wish to send. The example email below is a typical email that may be sent from any Helpdesk application to the user when they create a new Helpdesk ticket.

PHP Code:
$body 'Hi,

Thank you for submitting a ticket to our Helpdesk.

Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk'
This email could have been created from a template stored in a file or database and you could also process it to include the recipients name, change the reference number and so on.

Now that we have our email body ready we need to create the email itself complete with subject and recipients.

We start by creating a mail object from the Zend_Mail class:

PHP Code:
$mail = new Zend_Mail(); 
Now we have our mail object we can use it to add the sender, recipients, subject and body to our email:

PHP Code:
$mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Your helpdesk ticket #12345'); $mail->setBodyText($body); 
This PHP code should be fairly self-explanatory. First we use the setFrom()method to set the sender of the email. setFrom() takes two arguments, the email address and a descriptive name. The email address is required where as the descriptive name is optional so you can leave that our if you wish.

Next we use the addTo() method to add a recipient to our email. Like setFrom(), this takes two arguments, the email address and a descriptive name for the recipient. Again, only the email address argument is required here.

Now we set our email subject using the setSubject() method, and finally we set our plain-text email body using the setBodyText() method.

Now that our email is ready to go all we need to do is send it. As you might expect, the Zend_Mail class makes this simple by providing the send() method:

PHP Code:
$mail->send(); 
And that's all there is to it! You should now see an email appear in your inbox that looks something like the following:

Screenshot: Plain-Text Email Example

Below is the full code for sending plain-text emails with Zend_Mail:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Hi,

Thank you for submitting a ticket to our Helpdesk.

Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk'
;
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Your helpdesk ticket #12345'); $mail->setBodyText($body);
$mail->send();
Sending HTML Emails

Sending HTML emails with the built-in PHP mail() function used to be a chore. You would have to set the MIME-Version header, the Content-type header, and more.

The Zend_Mail component makes sending HTML emails as simple as sending plain-text emails. In fact, it's so simple, we only need to change two items from our previous example.

The first thing we need to change is the email body text. We are going to change it to the following to include some HTML:

PHP Code:
$body 'Hi!
Thank you for submitting a ticket to our Helpdesk.


Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk

'
As you can see we have included various HTML tags in the email so we can see our HTML email in action.

The next change we need to make to our previous code is to use the setBodyHtml method instead of the setBodyText() method:

PHP Code:
$mail->setBodyHtml($body); 
And that's all there is too it.

If you make these two changes to our original code and run it you will receive a HTML email that looks something like the following:

Screenshot: HTML Email Example

Below is the full code for our HTML email example:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Hi!
Thank you for submitting a ticket to our Helpdesk.


Your ticket reference number is 12345 and it will be investigated shortly.

Kind regards,
My Site Helpdesk

'
;
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Your helpdesk ticket #54321'); $mail->setBodyHtml($body);
$mail->send();

Adding Attachments

You will often find that you need to add one of more attachments to your emails. As you might expect, Zend_Mail makes this process simple.

First we need to setup our include path and include the Zend_Mail class as we did in the previous examples:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
The next step is to create the body of our email then add the sender, recipients, subject and body. For more details please see the plain-text email example above:

PHP Code:
$body 'Please find the zip file attached';
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('File attachment Test'); $mail->setBodyText($body); 
Now that we have our email ready to go we need to add the attachment. In this example we are going to add a zip file called test_file.zip so the first step is to get the contents of this file and store it in a variable:

PHP Code:
$fileContents file_get_contents('test_file.zip'); 
Now that $fileContents contains the contents of our zip file we use the createAttachment method to add it to our email:

PHP Code:
$attachment $mail->createAttachment($fileContents); 
And finally, we need to give our new attachment a filename:

PHP Code:
$attachment->filename 'test_file.zip'
Now we have our email with attachments ready we need to send it:

PHP Code:
$mail->send(); 
Check your inbox and you should find an email that looks something like:

Screenshot: Email with Attachment Example

You can use the createAttachment() method multiple times if you wish to add multiple attachments to an email.

Below is the full code to add attachments to your emails:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Please find the zip file attached';
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('File attachment Test'); $mail->setBodyText($body);
$fileContents file_get_contents('test_file.zip'); $attachment $mail->createAttachment($fileContents); $attachment->filename 'test_file.zip';
$mail->send();

Adding Multiple Recipients

Zend_Mail provides full support for adding CC and BCC recipients to your emails allowing you to send the mail to many people at once.

To add CC recipients to your email, you need to use the addCc() method:

PHP Code:
$mail->addCc('someone@example.com''Someone Else'); $mail->addCc('another@example.com''Another Recipient'); 
In this example, we have added two additional recipients. As you can see, addCc() takes the same arguments as the addTo() method, a recipients email address and a descriptive name for the recipient. The descriptive name is an optional argument so you can leave that out if you wish.

To add BCC recipients we use the addBcc() method:

PHP Code:
$mail->addBcc('topsecret@example.com''Top Secret Recipient'); 
This should be fairly straight-forward by now as it uses the same syntax as addTo() and addCc(), a required email address and an optional descriptive name.

Now use the send() method and you will receive an email that looks something like:

Screenshot: Multiple Recipients Email Example

Below is a full example of using Zend_Mail to send the same email to multiple recipients:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Hi all,

Don\'t forget that basketball training has been moved
from Tuesday to Wednesday.

See you all then!
Alan'
;
$mail = new Zend_Mail(); $mail->setFrom('alan@citconsultants.co.uk''Alan @ CIT'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->addCc('someone@example.com''Someone Else'); $mail->addCc('another@example.com''Another Recipient'); $mail->addBcc('topsecret@example.com''Top Secret Recipient'); $mail->setSubject('Basketball practice this week'); $mail->setBodyText($body);
$mail->send();

Adding Extra Headers

Occasionally you may find the you need to add extra email headers to your emails. Zend_Mail provides the addHeader() method for this purpose:

PHP Code:
$mail->addHeader('X-MailGenerator''MyPHPApplication v1.0'); 
If you then sent an email with this additional header then viewed the original / source of the email that you received you would see something like:

Screenshot: Mail with Extra Headers

Below is an example script that sends an email with an additional header:

PHP Code:

set_include_path
('.'
    
PATH_SEPARATOR './library'
    
PATH_SEPARATOR get_include_path()
);

include_once 
'Zend/Mail.php';
$body 'Look at this cool email sent from MyPHPApplication v1.0!';
$mail = new Zend_Mail(); $mail->setFrom('support@example.com''My Site Helpdesk'); $mail->addTo('awagstaff@gmail.com''Alan Wagstaff'); $mail->setSubject('Read me!'); $mail->setBodyText($body); $mail->addHeader('X-MailGenerator''MyPHPApplication v1.0');
$mail->send();

Conclusion

Hopefully this tutorial has shown you just how easy it is to send emails in PHP using the Zend_Mail component and the Zend Framework. The Zend_Mail component allows you to do many other advanced features such as changing character sets and even reading emails. Take a look at some of the links below to learn more about the Zend_Mail component.

No comments:

Post a Comment