How to integrate Mandrill into Yii 2.0

This is a brief guide to how to integrate Mandrill into an existing Yii 2.0 web app. These instructions have been written for Mac and MAMP has been setup to host the Yii site on localhost using port 80. If you are using Windows please use Command Prompt instead of Terminal and WAMP instead of MAMP.

Things you’ll need

  • Existing Yii 2.0 Basic Web App
  • Existing Mandrill account
  • Basic PHP/HTML skills

1. Downloading Mandrill

If you didn’t create your Yii project with Composer, install Composer now using this guide.

Once Composer has been installed you will need to download the Mandrill PHP SDK, download Mandrill with the following command and press enter:

php composer.phar require mandrill/mandrill 1.0

If you are using Terminal it will look similar to below:

Once Mandrill has finished downloading Terminal will return to the cursor.

2. Making the template

  • Log into Mandrill,
  • go to Outbound (the envelope on the left hand menu),
  • click on Templates on the new menu that appears at the top of the page,
  • click the blue ‘create a template’ button near the top of the page.
  • Enter the template name, in this case we are going to call it ‘avengers-contact-us’
  • finally click ‘Start Coding’, you should then see the following layout
setting the template up in Mandrill

Template Info: This can be left as it is, it is just the name of the template that you have entered and the template slug. You can change the name if you wish but the slug will remain the same. If you want to use a different slug you will need to delete the template and create a new template with the new name.

Template Defaults: This is where you can set the details from name and email address, this can be useful if you are emailing a user, in that scenario you can set it to the admin email address for the site.

Otherwise it’s best to leave it blank as you will probably want to set it to the user’s name and email address. Set the subject to something quick to identify.

Finally we need to code the email message that will be sent, generally a quick introductory line and then into the data you want to receive. Wrapping text with *| |* informs Mandrill that these are variable names, this allows you to pass dynamic data into the email. In this case as we are sending a contact email, lets just add NAME, EMAIL and QUESTION.

3. Adding Code

If you didn’t use Composer to create the Yii web app, you will need to add the following code to the web/index.php file. If you are using the advanced Yii template you will need to add this line to all modules you want to be able send emails from.

require(__DIR__ . ‘/../vendor/autoload.php’);

So the index.php file will look something like this, where the new line of code is line 5.

To enable easy identification and if necessary a one place update, we add a key to the params file which is called “mandrillKey”, this key holds the API key from Mandrill. If you are using the advanced Yii template it can be useful to set the params-local.php to have the test API key and the params.php file to use live API key, in the case of the advanced template we would tend to put the keys in the common config params files so they are accessible across all modules. Where xxxxxx is your 23 character Mandrill key.

For the purpose of this guide we are going to trigger the email being sent from a button click, but you can easily take this code and change it to be triggered from a form submission. So on the default root of the project we are going to have a button that triggers the email which will be sent from the SiteController in the Send action. At the top of the SiteController.php file we need to import Mandrill, Yii does this using the ‘use’ command, because we downloaded Mandrill using Composer we have already registered the SDK. To import Mandrill add the following code to the top of the SiteController.php file, after use yii\web\Controller

use Mandrill;
use Mandrill_Error;

So the first few lines of SiteController.php will look something like the below image, where the new lines of code are Lines 8 and 9.

Next we need make the new action on the SiteController, the action is going to be called actionSend. In this function there is going to be a try / catch statement, Mandrill is going be initialised with the key we added to the params earlier and we’re going to set a static to, from and message. At a later point you can change these values to either come from the database or from a form submission.

In the above print screen, line 34 is initialising Mandrill with the key we set in the params, the message array sets who the email is coming from, where the message is being sent and setting the variables we set up in the Mandrill template. Finally on line 52, the template is selected and the message passed through. Now when the action is run the email is sent and outcome is sent to the view so we can display either a success or an error message.

4. Sending the message

Now if you go to http://localhost and click on the button you added to go to http://localhost/site/send, the email should be sent, but you want to check out the email right? Ok, so go to the SiteController and change line 28 to your email address, and re-send the email. When the email comes through it should look something like the image to the right.

5. What Next?

This guide has shown you how to implement the very basics of integrating Mandrill into Yii. In addition to just sending variables, you can also attach PDFs, JPGs, PNGs, etc, that have been generated or stored on the server. In addition to attachments you can also add users to CC and BCC, set up webhooks and much more. Check out Mandrill’s API to get ideas on what you can achieve. Depending on where you are going to be sending emails from in your code, you could create function on an inherited controller to handle setting the template and adding the required variables, or if it’s only going to send on the ContactForm.php you could move the code from the SiteController and add to a function on the ContactForm and then check the email sent as part of the validation of the form.

Happy Coding!

6. Resources

find more information on our website…