Documentation

Light-weight, fast, simple and powerful!
 
Translations of this page?:

Email.php helper

Introduction

The Email helper is a way for you to add simple email sending functionality to Wolf CMS. It allows you to send formated messages as text, html or both. It supports sending via the built in mail functions of PHP, via smtp server or sendmail. It supports file attachments and does some basic header injection checking / filtering for you. There is a lot that it doesn't do for you but it will get you started.

Class Attributes and Variables

Variable Default Description
$useragent “Wolf framework”; Useragent for sending emails
$mailpath ”/usr/sbin/sendmail”; Sendmail path
$protocol “mail”; mail/sendmail/smtp
$smtp_host ””; SMTP Server. Example: mail.earthlink.net
$smtp_user ””; SMTP Username
$smtp_pass ””; SMTP Password
$smtp_port “25”; SMTP Port
$smtp_timeout 5; SMTP Timeout in seconds
$wordwrap true; true/false Turns word-wrap on/off
$wrapchars “76”; Number of characters to wrap at.
$mailtype “text”; text/html Defines email formatting
$charset “utf-8”; Default char set: iso-8859-1 or us-ascii
$multipart “mixed”; “mixed” (in the body) or “related” (separate)
$alt_message ””; Alternative message for HTML emails
$validate false; true/false. Enables email validation
$priority “3”; Default priority (1 - 5)
$newline “\n”; Default newline. “\r\n” or “\n” (Use “\r\n” to comply with RFC 822)
$bcc_batch_mode false; true/false Turns on/off Bcc batch feature
$bcc_batch_size 200; If bcc_batch_mode = true, sets max number of Bccs in each batch

There are some other things that can be set but you should refer to the source for more information

Sending a Basic Email Message

To send a simple message without any advanced processing, simply call the to, from, subject, message, and send functions wherever you want to send the email. For example:

use_helper('Email');
$Email = new Email();
$Email->to('example@example.com');
$Email->from('you@yoursite.com');
$Email->subject('Hello from myWebsite');
$Email->message('Hi there!');
$Email->send();

Note: You must set filter to “none” wherever you put this code

Including the Code

There are a number of places to logically place your code:

  1. In a layout
  2. In the page itself
  3. In a separate tab
  4. In a snippet

Depending on what you want to do, you can put the email code in a number of places, all of which have advantages and disadvantages

In a Layout

If you include the layout code in your layout, it will be available everywhere, so it's always there when you need it. This probably isn't the best idea, as it would probably look something like this:

if(!empty($_POST)) { // someone has submitted our form!
    use_helper('Email');
    $Email = new Email();
    $Email->to('contact@mycompany.com');
    $Email->from($_POST['email_address']);
    $Email->subject($_POST['subject']);
    $Email->message($_POST['message']);
    if($Email->send()) {
        redirect($this->find('thanks')->url());
    } else {
        redirect($this->find('error')->url());
    }
}

Ignoring the obvious flaws with trusting raw post data, this method is open to serious abuse, as any page on your site will be able to send email, so spam robots can send a post request to any page on your site to send you an email.

In the Page Itself

This has the added benefit of only working on your contact page, however as you need the filter turned off, it's not great from a re-use point of view, it might look something like this:

<?php
if(!empty($_POST)) { // someone has submitted our form!
    use_helper('Email');
    $Email = new Email();
    $Email->to('contact@mycompany.com');
    $Email->from($_POST['email_address']);
    $Email->subject($_POST['subject']);
    $Email->message($_POST['message']);
    if($Email->send()) {
        echo '<div class="success">Thanks for your email, we\'ll be in touch asap!</div>';
    } else {
        echo '<div class="error">Sorry, there was an error sending your email, please try again.</div>';
    }
}
?>
 
<h1>Contact Us</h1>
 
<p>Thanks for your interest in myCompany please complete the form below to get in touch</p>
 
<form action="<?php echo $this->url(); ?>" method="POST">
    <label>
        Your Email Address:
        <input type="text" name="email_address" />
    </label>
    <label>
        Subject:
        <select name="subject">
            <option value="A message for you guys">A message for you guys</option>
            <option value="I'd like some work done">I'd like some work done</option>
            <option value="You guys rock">You guys rock</option>
        </select>
    </label>
    <label>
        Message:
        <input type="text" name="message" />
    </label>
 
    <input type="Submit" value="Submit" />
</form>

In a Separate Tab

I'm a big fan of code separation and re-use, so I prefer to include my email code in a separate tab. That means I can have my contact page content in the body tab (with a textile fitler), then have a form tab, with the form html, and an email tab with the email code, it would look something like this:

// body tab
 
h1. Contact Us
 
Thanks for your interest in myCompany please complete the form below to get in touch
// form tab
<?php echo $this->content('email'); ?>
 
<form action="<?php echo $this->url(); ?>" method="POST">
    <label>
        Your Email Address:
        <input type="text" name="email_address" />
    </label>
    <label>
        Subject:
        <select name="subject">
            <option value="A message for you guys">A message for you guys</option>
            <option value="I'd like some work done">I'd like some work done</option>
            <option value="You guys rock">You guys rock</option>
        </select>
    </label>
    <label>
        Message:
        <input type="text" name="message" />
    </label>
 
    <input type="Submit" value="Submit" />
</form>
// email tab
<?php
if(!empty($_POST)) { // someone has submitted our form!
    use_helper('Email');
    $Email = new Email();
    $Email->to('contact@mycompany.com');
    $Email->from($_POST['email_address']);
    $Email->subject($_POST['subject']);
    $Email->message($_POST['message']);
    if($Email->send()) {
        echo '<div class="success">Thanks for your email, we\'ll be in touch asap!</div>';
    } else {
        echo '<div class="error">Sorry, there was an error sending your email, please try again.</div>';
    }
}
?>
// Layout
<div id="content">
    <?php echo $this->content(); ?>
    <?php if($this->hasContent('form')) echo $this->content('form'); ?>
</div>

This is starting to look nicer, everything is separate and much easier to maintain, plus there is less chance of a content editor messing up our form code, however we still can't re-use our code which means that we have to duplicate it everywhere, and if we want to make a change, we have to remember everywhere we put it, we can go one better…

In a snippet

In my opinion (and it is just that), the best place for this code is a snippet. That way we can call the snippet anywhere we want to send an email, and only have 1 piece of code to maintain.

// body tab
 
h1. Contact Us
 
Thanks for your interest in myCompany please complete the form below to get in touch
// form tab
<?php $this->includeSnippet('email'); ?>
 
<form action="<?php echo $this->url(); ?>" method="POST">
    <label>
        Your Email Address:
        <input type="text" name="email_address" />
    </label>
    <label>
        Subject:
        <select name="subject">
            <option value="A message for you guys">A message for you guys</option>
            <option value="I'd like some work done">I'd like some work done</option>
            <option value="You guys rock">You guys rock</option>
        </select>
    </label>
    <label>
        Message:
        <input type="text" name="message" />
    </label>
 
    <input type="Submit" value="Submit" />
</form>
// email snippet
if(!empty($_POST)) { // someone has submitted our form!
    use_helper('Email');
    $Email = new Email();
    $Email->to('contact@mycompany.com');
    $Email->from('noreply@mycompany.com');
    $Email->subject('A message from myCompany WolfCMS');
    $message = '';
    foreach($_POST as $key => $value) {
        $message .= $key . ': ' . $value . $Email->newline;
    }
    $Email->message($message);
 
    if($Email->send()) {
        echo '<div class="success">Thanks for your email, we\'ll be in touch asap!</div>';
    } else {
        echo '<div class="error">Sorry, there was an error sending your email, please try again.</div>';
    }
}

Sending SMTP Email

Sending an SMTP email is similar to sending a basic message, except you need to set your smtp settings before you send

// email snippet
if(!empty($_POST)) { // someone has submitted our form!
    use_helper('Email');
    $Email = new Email();
 
    // Set smtp details
    $Email->protocol = 'smtp';
    $Email->smtp_host = 'smtp.gmail.com';
    $Email->smtp_user = 'contact@mycompany.com';
    $Email->smtp_pass = 'password';
    $Email->smtp_port = '587';
 
    // send email
    $Email->to('contact@mycompany.com');
    $Email->from('noreply@mycompany.com');
    $Email->subject('A message from myCompany WolfCMS');
    $message = '';
    foreach($_POST as $key => $value) {
        $message .= "{$key}: {$value}\r\n";
    }
    $Email->message($message);
 
    if($Email->send()) {
        echo '<div class="success">Thanks for your email, we\'ll be in touch asap!</div>';
    } else {
        echo '<div class="error">Sorry, there was an error sending your email, please try again.</div>';
    }
}

Attachments

TODO: write this

HTML Email

TODO: write this

Email Templates with Snippets

TODO: write this

Sending Email in a Loop

TODO: write this

Alternative Config Method

TODO: write this

 
helpers/email.txt · Last modified: 2012-06-11 15:51 by tikky
 
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.2
Copyright 2010 wolfcms.org / design by yello studio / Wolf CMS Inside