So, I’ve spent far too long messing with formmail.php.. but I just can’t resist getting everything just right! I was getting an obscure error, which requires a little form field validation.

The problem

I found during testing that if I populated form fields with the excellent Web Developer toolbar for Firefox, I would get the following error:

The following error occurred in FormMail :
mail_failed
**********
Error=Failed to send email

The error whilst using the formmail tag <fmerroritemlist /> the only feedback displayed to the user was:

There was an error in processing your form…

Not so helpful.

Whilst using the error handling tags <fmerrorcode /> and <fmfullerror />, the feedback was little better:

Error Code: mail_failed
Failed to send email

The failure was due to the email address being faulty. The Web Developer Toolbar populated the field with ‘email’ (the name of the field), and formmail.php choked on the invalid address.

The solution

The solution was found in the following forum post at Tectite.com. We simply add a condition:

If an email is submitted, test it, and notify the user if it’s bad!

Just add the following condition to your form:

<input type="hidden" name="conditions" value=":#
#IF#email#email ~ /^[a-z0-9_.]+@[a-z0-9_]+\.([a-z0-9_.]+)*[a-z0-9_.]$/i ##
Please enter a valid email address.#">

Sorted! Now the user will be told “Please enter a valid email address” if, and only if, they enter something in the email field.

Please note that in the formmail documentation the author recommends that you use either conditions, or required fields. I’ve found no problems whilst using them together in my simple scenario, but if you encounter gremlins in your error handling, RTFM.

Wordpress Training Melbourne

I’ve spent a little more time on prettying up a recent fommail.php installation, and have come to grips with some quirks involved in getting all the juicy info possible into the email I recieve.

If you are setting up formmail.php for the first time, it might be worth reading my previous post Configure formmail.php more easily.

My priorities are:

• using formmail.php to conceal my email address from spammers
• setting the subject to include derived fields
• tracking the IP address and User Agent of the user
• compile all the data into a presentable email

Using formmail.ini

My .ini file is really simple, and looks like this:

[special_fields]
recipients = "tim@mysite.com"
;this is a comment

Now I no longer need to specify recipients in my form, so the address is not harvestable, and there’s no need to use an AT_MANGLE to obsfucate the address.

Note that a semi-colon functions comments out a line.

I’ve tried including other options in formmail.ini, but few function, so I prefer to keep all the values bar recipients together in the form.

Setting a useful subject line with ‘Derived Fields’

Derived Fields allow the form to combine values that the user enters into new variables which can be used in the email or to name files.  I wanted to be able to see the User’s name in the subject line of the email (and other details.. I’ve dumbed this down for clarity), which requires defining ‘subject’ as a derived field.

The documentation is pretty clear about the nitty gritty of configuring derived fields, just not on including them in the html template.

Check the following example from my form:

<input type="hidden" name="derive_fields" value="subject=%'[Contact Form] -'%+email" />

• ‘subject=’ is pretty straight-forward
  
• %’this is how to include a literal string using formmail‘%
• + concatenates (joins) two values with a space between.  A period joins with no space.
• email calls a field that you’ve defined somewhere else, either as a user-entered field, or defined later in the derived_fields.. stay tuned.

You can define a whole lot of these values within the one hidden field.  They can get mighty confusing, so it’s best to span them over many lines, as I’ve done below:

<input type="hidden" name="derive_fields" value="
    subject=%'[Contact Form] -'%+email,
    DateTime = %'Form was submitted: '% . %date% + %time%,
    remote_addr = REMOTE_ADDR,
    http_user_agent = HTTP_USER_AGENT" />

Note the commas between each line.  You can span required fields over multiple lines in the same way.

Using Derived Fields in the email template

Now we have access to all those handy values we’ve defined.  Printing them in the email template is as simple as prefixing each value with a $.  Here’s a taste of my email template:

<html>
<body>
<h1>$title</h1>
<p>$DateTime</p>

<pre>
You can put preformat text in here,
ready to be pasted into a website,
as long as you convert all your
opening angle brackets to html entities.
Substitute each < with <.

</pre>

<ul>
	<li>IP Address: $remote_addr</li>
	<li>User Agent: $http_user_agent</li>
</ul>

</body>
</html>

Simple, in retrospect

Wordpress Training Melbourne

Formmail.php is a free script which delivers a user’s details from a form on your site’s contact page to your email inbox. It can do file uploads, it is spam savvy, it does captcha text.. phew, it threatens to fold your washing!

The file itself is more heavily documented than any other script I’ve seen: comments just about outweigh the code, which ironically makes it tedious to configure manually.  Thankfully, Tectite offers a Configuration Wizard, which offers a free trial, or 7 day access for a measly US$4.95.  I highly recommend that you use it.

If, however, you find yourself configuring it repeatedly, I’d suggest making your own configuration file.  The purpose of this is to gather the 15 odd lines you actually need to edit on one page.  Why is this so useful?  Because the whole script weighs in at over 10,200 lines of code!  That’s a lot of scanning through code.

Configuring formmail.php

First, enter your $TARGET_EMAIL, and define DEF_ALERT around line 230 in the script.  This is well documented.

The essential step is to trigger formmail’s test function, which will email you the paths that it detects on your server.    Do this by visiting the script directly in your browser:

name-of-your-formmail.php?testalert=1

then check your email.  This will provide you with the correct path to use when configuring further options.  I found recently, on a particularly convoluted server, that I needed the value PATH_TRANSLATED. Strip the trailing slash, and the script name off the end, so that you’re left with the a string ending in the directory containing the script:

PATH_TRANSLATED: /home/www/01/mydomain.com.au/www/formmail/formmail.php

Hijacking the Configuration

Enter the following line into formmail.php before the comments begin (line 3)

include('config.php');

Now create a new file in the same directory as formmail.php, and name it, surprise.. config.php.

Browse through the script (the configuration is roughly between lines 230 and 520) and identify the variables that you want to set, and with each of them:

• copy the line to your config.php
• comment out the original line

My config file looks like so:

<?php
$TARGET_EMAIL = array(EMAIL_NAME."@mydomain\.com$");
define("DEF_ALERT","tim@mydomain.com");

$LOGDIR             = "/home/www/formmail/log";
$CSVDIR             = "/home/www/formmail/csv";
$TEMPLATEDIR        = "/home/www/formmail/templates";
$FORM_INI_FILE      = "/home/www/formmail/formmail.ini";

define("FILEUPLOADS",true);
$FILE_REPOSITORY     = "/home/www/uploads";

define("CHECK_FOR_NEW_VERSION",true);
define("CHECK_DAYS",30);

$SCRATCH_PAD         = "/home/www/formmail/scratchpad";
define("ALERT_ON_USER_ERROR",true);
?>

A few thoughts before signing off:

• I think you’d be crazy negligent not to use the formmail.ini option, which protects your email address being harvested by separating it from the html form itself
• I recommend having ALERT_ON_USER_ERROR set to true for the first week of operation, then set it to false when you tire of receiving a stream of mail notifying that someone has forgotten to enter a required field.

Caveats

This, of course, will need to be repeated if you upgrade.  In the meantime, it could save you quite a bit of frustration if you’re running backwards and forwards between your configuration, your form, and your inbox.  Tectite provides a really handy Upgrade Wizard, if you plan to follow the beaten path.

In Conclusion

I can’t help but think the formmail has been created obscure to scare people into using, and ultimately subscribing to the Configuration Wizard, but I don’t begrudge its author Russell Robinson this.  Ten thousand lines of code don’t come from nowhere!

Formmail is a great product, and comes at the ultimate price, and it’s saved me a number of times.

Formmail.php is available as a free download from Tectite.com, and they offer a Configuration Wizard.

Note: Of course, you’ll need to have PHP installed and running on your host (it’s free, and almost universal in budget setups).

Wordpress Training Melbourne