FormSnarfer processes POST variables from a submitted HTML FORM. Configuration Elements control what happens with the processed data. These Configuration Elements are defined by passing a PHP array when the FormSnarfer Class is instantiated. This is both more secure and more flexible than passing hidden FORM elements.

FormSnarfer is designed as a PHP Class, instead of a collection of procedures. Classes provide much better namespace and scoping control, as well as enhancing modularity and encapsulation. Typically, one includes Class definitions at the beginning of a page so that Class names are globally known (without requiring a "globals" statement); then a Class can be instantiated at any scope within the program.

FormSnarfer 0.2 can:

• optionally send email to a specified recipient or recipients, containing FORM values entered by the web visitor.



• after processing is completed, generate a "thank you" page or redirect the visitor to another page



• optionally display alternating background and text colors (or cycle through more than two colors) in the table of values in the "thank you" page



• optionally require the visitor to enter data in certain FORM fields, and generate an "error page" if the required data isn't entered



• optionally ignore the data from certain FORM fields



• for the "thank you" page or "error page": generate standalone pages (including HEAD, BODY, etc. HTML tags), or pages to be embedded within your site's normal page layout



• correctly handle FORM variables that are arrays, for example:
  
  
  <select name="whatever[]" multiple>
  <option selected> option one </option>
  <option> option two </option>
  <option> option three </option>
  </select>

Planned future enhancements include:

• save form values to a log file or (on Unix) to syslog
• save form values to a MySQL database
• send an "auto-responder" email from a template, substituting in form values

Just copy FormSnarfer.php into a directory that's in your php_include_path.

Although your include path is allowed to contain directories within your document root, we recommend that your include path contain a directory outside your document root, and that you place most included files (like FormSnarfer.php) in that directory. This helps protect the source of your scripts (especially important when your scripts contain database passwords, etc.).

You can "include" FormSnarfer.php at the global level, or inside a function or method. The configuration for a form is specified by an associative array that's passed to the constructor for the FormSnarfer class. All the possible configuration elements are described in a later section.

Your form variables can have any legal HTML names, and they won't conflict with variables used within FormSnarfer. Values that are arrays can be defined separately, or inline (see example below).

Here's an example form:

  <form action="thanks.php3" method=post>

  <table border=0>

  <tr>
  <td align=right> Name:
  </td>
  <td> <input type=text name="Name" size=40 maxsize=40>
  </td>
  </tr>

  <tr>
  <td align=right> Address line 1:
  </td>
  <td> <input type=text name="Address[]" size=40 maxsize=40>
  </td>
  </tr>

  <tr>
  <td align=right> Address line 2:
  </td>
  <td> <input type=text name="Address[]" size=40 maxsize=40>
  </td>
  </tr>

  <tr>
  <td align=right> City:
  </td>
  <td> <input type=text name="City" size=40 maxsize=40>
  </td>
  </tr>

  <tr>
  <td align=right> State:
  </td>
  <td> <input type=text name="State" size=40 maxsize=40>
  </td>
  </tr>

  <tr>
  <td align=right> Zip:
  </td>
  <td> <input type=text name="Zip" size=40 maxsize=40>
  </td>
  </tr>

  <tr>
  <td colspan=2 align=center>
  <input type=submit name="Submit" value="send form">
  </td>
  </tr>

  </table>
  </form>

And here's a sample of what might be in the file "thanks.php3":

   ...enclosing html... 
  <?php
	include ('FormSnarfer.php');

	$snarfRequired = array (	// fields I want to require
		"Name",
		, "Address"
		, "City"
		, "State"
		, "Zip"
	);

	$snarfConcealed = array (	// fields I want to conceal
		"Submit"
	);

	$snarfConf = array (
		"required-fields"	=> $snarfRequired
		, "concealed-fields"	=> $snarfConcealed
		, "mail-visitor-info"	=> true
		, "mail-recipient"	=> "me@example.com"
		, "mail-subject"	=> "Results from example.com form"
		, "mail-from"		=> "webmaster@example.com"
		, "thanks-back-url"	=> "/"
		, "thanks-back-text"	=> "Return to Example.com home"
		, "thanks-tdbgcolors"	=> array ("#f0f0f0", "white")
		, "thanks-tdtextcolors"	=> array ("black")
	);

	$snarfer = new FormSnarfer ($snarfConf);

	// process the entire form

	$snarfer->snarf();

  ?>
   ...enclosing html... 

If you configure embed to false, you don't even need any enclosing HTML! (But then the generated pages won't match the "look" of your site.) This is convenient when you're first testing a form.

Configuration Elements may be specified in any order, since they go into an associative array. You needn't specify a particular element if you want the default behavior of that element.

• Configuration Elements whose names begin with mail- control the generated email.
• Configuration Elements whose names begin with thanks- control the look of the "Thank You" page.
• Other elements may apply in multiple contexts.
• To generate an email containing the FORM visitor's entered data, you must at least specify the mail-recipient element. If no mail-recipient is specified, no email is generated.
• To generate a "Thank You" page for the visitor, you must not specify the redirect element.

Here are all the elements, in alphabetical order.

FormSnarfer was written and documented by Carol Deihl of Tinker Internet Services. The current version of FormSnarfer can be found in the downloads section of www.tinker.com. Please send comments, suggestions, bug reports, and fixes to opensource@tinker.com. Although I can't promise a personal response, all input will be carefully considered!

FormSnarfer was loosely inspired by the FormMail.pl Perl script from Matt's script archive (http://www.worldwidemart.com/scripts/). The original (un-released) version of FormSnarfer used hidden FORM variables for configuration, like FormMail.pl.

The idea for using PHP variables for configuration was inspired by Alan Little's Phorm script (http://www.holotech.com/scripts). This is both more secure and more flexible than using hidden FORM variables. Phorm is designed as a collection of functions instead of as a Class, which unfortunately makes it unsuitable for use in my context.