NOTE: This tutorial is to be used with at least version 3.0.14 of our form processing scripts. It will work with both the NateMail.php and ProcessForm.php script. The script requires PHP 4 and the GD Image Libraries (installed by default in most recent versions of PHP). You may use this script and tutorial as freeware.
The purpose of this script and tutorial is NOT to provide a sophisticated, fool-proof catpcha image that can't be machine-read. Rather, my intent is to make the form processing scripts safer from the vast majority of spam hijacking attempts without overly compromising accessibility. Aside from the script itself being useless for sending out mass emails, a security image makes even the annoying, pointless spamming abuse much more difficult, and hopefully not worth the effort.
As with the rest of our scripts, these security add-ons are provided as-is and we can not be responsible for any damage caused by their installation, use or misuse.
This script works by adding a security image and text entry field to your pre-existing HTML form. The value entered into the text entry field must match the string of letters and numbers shown in the security image. When the form is processed in NateMail or ProcessForm, the code entered into the input field is compared against the code used for the image and the submission is rejected if the codes are different.
To begin installation, download the "mpfs.zip" archive containing all the necessary files:
Next, unzip the archive and install the script by uploading the entire "mpfs" folder to the document root folder of your web server (same directory your home page is in). You may install the script into a different folder of your site, but you will later need to alter a couple paths in the code to tell PHP where everything is. For minimal editing, it's best to install into your site's document root directory.
To use the MPFS script in your HTML form, you'll first need to change the extension of your form page to .php (or whatever extension your web host requires to alert the server that there's PHP code in the page that needs to be processed). Next, to connect the script to the form on your page, you'll need to add some PHP code into the very top of the form page (if you're using a visual web editor like Dreamweaver or GoLive, make sure you're in source code view). It's very important that there NOT be any content before the PHP code - not even spaces or line breaks.
I will later show an example of the code to use that takes advantage of all configuration options, but for a minimal installation using all the default settings (best for initial testing), here is the code to paste:
<?php
$MPFSHttpPath = '/mpfs/';
$MPFSServerPath = $_SERVER['DOCUMENT_ROOT'].'/mpfs/';
require($MPFSServerPath.'MPFS.class.php');
$MPFS = new MP_MPFS();
// start configuration options
// end configuration options
$MPFS->generateCode();
?>
If you've installed the "mpfs" folder into the document root of your site, in most cases you can leave everything as-is. Otherwise, if you've installed into a different directory or your server can't find the script files, here is a line-by-line description of what's happening, and what to change if needed:
$MPFSHttpPath = '/mpfs/';$MPFSServerPath = $_SERVER['DOCUMENT_ROOT'].'/mpfs/';$MPFSServerPath = 'var/www/html/mpfs/';The rest of the code is purely functional, and should not require editing. It basically imports the MPFS.class.php script file, creates a new object named $MPFS and generates a new random code to be used in the security image.
At this point, I'd recommend uploading your edited form page and loading it in your browser. If all went well, your form should look the same as it did before installation. If the server has a problem with either of your path settings, you will most likely see either a blank page, or a PHP error message complaining that it can't find the MPFS.class.php file. If you're getting an error message, see the FAQ section, or contact your web host for the correct paths to use. Otherwise, we'll continue...
To add the code image and input field, you will need to add a few PHP snippets into the HTML source code of your form page as follows:
<?php print($MPFS->outputImageTag()); ?><?php print($MPFS->outputInputBox()); ?><?php print($MPFS->outputNewImgLink("new image")); ?><?php print($MPFS->outputHintText()); ?>For example, the captcha code between your <form> tags may look like the following:
<p>
<?php print($MPFS->outputImageTag()); ?>
<?php print($MPFS->outputNewImgLink("new image")); ?>
<?php print($MPFS->outputHintText()); ?>
</p>
<p><label>
Please re-enter the security code shown above:
<?php print($MPFS->outputInputBox()); ?>
</label></p>
At this point, you should be able to upload your form page, load it in your browser, and see the automatically generated security image and input field. If the image is not appearing, the problem is most likely with your HTTP path to the "mpfs" folder. Otherwise, we'll continue...
It's often more convenient for your visitors to include JavaScript pre-validation for your security image, which checks if the user input matches the code before allowing the form to submit. To accomplish this, you'll need to add a PHP snippet in the <head> section of your form page:
<?php print($MPFS->outputJSCheck("formName")); ?>
This will import the necessary JavaScript functions to check the code input. The "formName" value between the quotes will need to be changed to whatever the "name" attribute is set to in your HTML <form> tag. To use the JavaScript with your form, you'll also need to add an onsubmit="return MPFSValidate();" attribute to your form tag that calls the function. For example:
<form name="formName" method="POST" action="/path/to/processor.php" onsubmit="return MPFSValidate();">
If you are already using JavaScript validation and would like to implement the code check into your own script instead, include the same PHP snippet into your form page's <head> section, but instead of attaching the onsubmit event above, call the MPFSCheckStatus() function from within your own validation script and it will return a boolean "true" if the codes match, and "false" otherwise.
As long as you're using NateMail or ProcessForm, versions 3.0.14 or greater, activating the security image features should be very simple. See lines 173 - 174 in ProcessForm (144 - 145 in NateMail)...
$securityFile = "";
$securityError = "Form security error (security image mismatch or unauthorized form page).<br>$le";
To activate the image security, enter the absolute server path to the MPFSProcessForm.php file (inside the "mpfs" folder) for the $securityFile value. The path should start out the same as the $MPFSServerPath path entered in the form page, plus the name of the MPFSProcessForm.php file. For instance:
$securityFile = $_SERVER['DOCUMENT_ROOT']."/mpfs/MPFSProcessForm.php";
$securityError = "Form security error (security image mismatch or unauthorized form page).<br>$le";
Of course, the path inside the quotes will need to be modified if the security folder is not at the root level of your site. You can also customize the error message in the $securityError line for when the text entry does not match the security image.
If you're NOT using NateMail or ProcessForm, you should still be able to implement this plug-in by importing the main MPFS.class.php file, creating a new instance of the class and using the $MPFS->validateInput() method to return a boolean "true" if the codes match, and "false" otherwise. For example:
require_once($_SERVER['DOCUMENT_ROOT']."/mpfs/MPFS.class.php");
$MPFS = new MP_MPFS();
$captchaStatus =
$MPFS->validateInput();
if (!captchaStatus) { /* handle captcha error */ }
The script should now be installed and ready to upload and test. If it looks like something is not working, please see the FAQ section below. Otherwise, we will continue with the script's configuration options.
The script is customized from your form page instead of the main MPFS.class.php file. Earlier we installed the script using the default configuration settings, but you may have noticed the following lines in the code:
// start configuration options
// end configuration options
Any custom configuration settings should be inserted between these two lines in the form page. Here is an example showing and installation with all the configuration options and their default settings:
<?php
$MPFSHttpPath = '/mpfs/';
$MPFSServerPath = $_SERVER['DOCUMENT_ROOT'].'/mpfs/';
require($MPFSServerPath.'MPFS.class.php');
$MPFS = new MP_MPFS();
// start configuration options
$MPFS->codeMinLength = 3;
$MPFS->codeMaxLength = 5;
$MPFS->textColor = array('R'=>225, 'G'=>225, 'B'=>225);
$MPFS->bgColor = array('R'=>75, 'G'=>75, 'B'=>75);
$MPFS->colorVariance = 50;
$MPFS->randomColorFlip = true;
$MPFS->caseSensitive = false;
$MPFS->forceCase = '';
$MPFS->inputFieldName = 'MPFS_input';
$MPFS->imgNameID = 'MPFS_image';
$MPFS->imgAltText = '(verification image)';
$MPFS->codeStructure = 'XHTML';
// hint text options (if applicable)
$MPFS->hintAsAltText = false;
$MPFS->hintNumberText = 'number ';
$MPFS->hintLetterText = 'letter ';
$MPFS->hintLetterUpper = 'uppercase ';
$MPFS->hintLetterLower = 'lowercase ';
$MPFS->hintNumbers[0] = 'zero';
$MPFS->hintNumbers[1] = 'one';
$MPFS->hintNumbers[2] = 'two';
$MPFS->hintNumbers[3] = 'three';
$MPFS->hintNumbers[4] = 'four';
$MPFS->hintNumbers[5] = 'five';
$MPFS->hintNumbers[6] = 'six';
$MPFS->hintNumbers[7] = 'seven';
$MPFS->hintNumbers[8] = 'eight';
$MPFS->hintNumbers[9] = 'nine';
$MPFS->hintPrefix = 'CODE HINT: ';
$MPFS->codeMinLength = 3;
$MPFS->codeMinLength = 3;
// end configuration options
$MPFS->generateCode();
?>
A line-by-line description of each setting follows:
$MPFS->codeMinLength$MPFS->codeMaxLength$MPFS->textColor$MPFS->bgColor$MPFS->colorVariance$MPFS->randomColorFlip$MPFS->caseSensitive$MPFS->forceCase$MPFS->inputFieldName$MPFS->imgNameID$MPFS->imgAltText$MPFS->codeStructure = 'XHTML';$MPFS->hintAsAltText$MPFS->hintAsAltText$MPFS->hintNumberText$MPFS->hintLetterText$MPFS->hintLetterUpper$MPFS->hintLetterLower$MPFS->hintNumbers$MPFS->hintPrefix[ back to top ]