SOLMETRA FormValidator is a PHP class used to validate web forms against automated submissions. The process involves generating and displaying a distorted image of secret phrase which is readable to humans but completely incomprehendable to machines - even to OCR programs. This protection mechanism is known as CAPTCHA (completely automated public Turing test to tell computers and humans apart).
Features of the current release:
Requirements:
This program is provided AS IS. Use it at your own risk. SOLMETRA will not be held responsible for any direct or indirect damages that rise by the use or misuse of this program.
This program is copyright © 2005 by Solmetra.
By using this program you agree to the terms of License Agreement found in license.txt file in docs directory
Extract archive to a separate directory on your hard disk. Make sure the directory is accesible through web. Installation complete!
While SOLMETRA FormValidator can easily run with default settings, you can make adjustments in file SPAF_FormValidator.class.php to better suit your needs. We've decided against separate configuration file due to class' simplicity. All the configuration variables can be changed directly in class' property definition section.
Below are explanations for each class property:
$lib_dir - a directory where support files (background images and fonts) are located (this can be relative or absolute path). This value can be set directly from your PHP application by calling method setLibDir().
$backgrounds - an array of available background files. All files listed in this array should be available in directory specified in $lib_dir property. GIF, JPEG and PNG files are supported.
$fonts - an array of available TrueType fonts. All files listed in this array should be available in directory specified in $lib_dir property.
$font_sizes - an array of available character font sizes.
$colors - an array of available character colors. Each element is an array of 3 elements that represent color in RGB decimal values. (i.e. red is array(255, 0, 0))
$shadow_color - an array of 3 elements representing shadow color in RGB decimal values.
$hide_shadow - if set to true no letter shadowing will be used. It will most likely make letters less readable on jazzy backgrounds.
$char_num - number of characters in autogenerated secret phrase.
$chars - an array of characters that can be used when randomizing secret phrase. ATTENTION! Not all TrueType fonts support national characters so use them with caution. It is recommended to use only basic latin letters and numbers. In default configuration letters and numbers that could resemble each other are removed. (i.e. 1 and I)
$no_session - if this is set to true following config variables must also be set. FormValidator will use files on disk instead of PHP session to track users.
Following config variables are only used if $no_session is set to true.
$work_dir - set this variable to the directory in which FormValidator will create its temporary files. If path begins with a backslash (i.e. /tmp), FormValidator will assume it's an absolute path. Otherwise path will be treated as relative to FormValidator class location. Please note that this directory must be writable to PHP scripts.
$work_ext - an extention to use for temporary work files.
$tag_ttl - number of minutes to consider user tag valid. After this time elapses the file will be removed by first garbage collector that runs.
$tag_cookie - the name of cookie to be used for tagging a user.
$gc_prob - percental probability for garbage collector to launch per each instance of FormValidator class. Garbage collector is needed to remove old user tag files from disk. 0 means GC will never launch; 100 means GC will launch everytime you instantiate FormValidator.
To display a code image simply use HTML's <img ...> tag pointing to img.php file. Assuming you've put all of the package files into directory formvalidator, here's what your HTML would look like:
<img src="formvalidator/img.php" />
In order to avoid caching of the image by web browser you can include different query string parameters with your request. PHP's time() function is quite suitable for this:
<img src="formvalidator/img.php?<?php echo time(); ?>" />
The first time particular user views the page with this tag, a new "user tag" will be generated and saved in user's session for later reuse. If refreshed, the image will display the same code but with different random distortion parameters. This is suitable if using some combination of random parameters the text becomes unreadable. You can even put a link for user which he/she can use to reload the page and get a different view on the code.
If for some reason you want code to be regenerated, just include regen=y into your querystring:
<img src="formvalidator/img.php?regen=y&<?php echo time(); ?>" />
Note: image will be generated in the same format as source background image.
The complete example:
<form action="form.php" method="post"> Your name:<br /> <input type="text" name="name" /><br /><br /> Please enter confirmation code displayed below:<br /> <img src="formvalidator/img.php?regen=y&<?php echo time(); ?>" /> <input type="text" name="code" /><br /><br /> </form>
On the PHP page that receives form submission do following:
Note: In versions prior to 1.01 it was necessary to start a PHP session before using FormValidator. It is no longer the case since FormValidator will start a PHP session itself if it has not been started.
Example:
<?php
// 1. Sart session
session_start();
// 2. include the class
include_once 'formvalidator/SPAF_FormValidator.class.php';
// 3. instantiate the object
$obj = new SPAF_FormValidator();
// 4. validate
if (isset($_POST['code'])) {
if ($obj->validRequest($_POST['code'])) {
echo 'The code is correct!';
// destroy successful code
$obj->destroy();
}
else {
echo 'Error - the code entered is incorrrect';
}
}
?>
By default FormValidator uses PHP sessions to track users. If for some reason you do not want or simply cannot use PHP sessions there is an option for you.
In configuration section of SPAF_FormValidator.class.php set property $no_session to true
FormValidator now instead of putting secret code in session will tag the user with custom cookie and create the file in the filesystem of your server.
Everything will still work the same - no need to make any modification to your PHP scripts. There are however some things you have to be aware of:
That's all there is to it!
If needed you can rename or edit file img.php anyway you like. You can also put contents of the img.php file into other PHP scripts. In these cases make sure that following requirements are met:
Current version of SOLMETRA FormValidator imposes following limitations:
Please visit product page on SOLMETRA's website for latest developments.
Address all inquiries to dev@solmetra.com
SOLMETRA FormValidator copyright © 2005-2006 by Solmetra. All rights reserved.
SOLMETRA FormValidator © 2005-2006 by Solmetra. All rights reserved.
$Revision: 1.01 $, $Date: 2006/04/06 21:12:41 $