Catch-All PHP Form Processor
Documentation

Always do a database backup before performing upgrades, downgrades and installations to add-ons.


The Basics

Catch-All Form Processor is nothing but a processor. The form code must be provided on your end. This script does a few things that require you to put a little bit of thought into your form. For every input field you have you must give it a name (a standard in XHTML). How you name said fields will determine how they are displayed in the results. I have followed the standard of "pretty links" all around the web now. If you have a field such as "First Name" you would (probably) want to name it "first-name" or "first_name". This is processed in the script to read "First Name". For example:

<input type="text" name="first-name" id="first-name" value="Erik Reagan" /> 

This will be read by the script as the field "First Name" having a value of "Erik Reagan"

<textarea name="additional-comments">Text area  here</textarea> 

This will be read by the script as the field "Additional Comments" having it's relative value

Form Submission

THIS IS VERY IMPORTANT! In order for the script to process the form it must recognize the submit button. Your submit button must have the name set to 'submit' to work. Image submit buttons are also acceptable as long as you give them a value of 'submit' AND give them a name.

<input type="submit" name="submit" id="submit" value="Submit Results" />
      The above is acceptable
  <input type="submit" name="submit" id="formbutton" value="Blast Off!!!" />
      The above is acceptable
  <input type="image" src="button.jpg" id="formbutton" name="formbutton" value="submit" alt="Blast Off!!!" />
      The above is acceptable
  <input type="image" src="button.jpg" id="formbutton" value="submit" alt="Blast Off!!!" />
      The above is NOT acceptable (name="something" is missing) 

Require Fields

If you have fields you need to require (such as name, email, etc) you can simply append "require" to the FRONT of the name. For example:

<input type="text" name="require-first-name" id="first-name" value="Erik Reagan" /> 

This will alert the user if they have left a required field blank. I would suggest showing the user that the field is required by marking it somehow in your form

Requiring a <select> input is a bit different. To do this you'll need to adjust the name from something like 'cars[]' to 'required-cars[]' and then add an option similar to this:

<option value ="didnotchoose" selected>Choose One</option> 

You can put anything you want in the 'Choose One' area. This will require the select to be used. You can read more about the select usage below.

Ignore Fields

Many times developers use hidden input values during form submission. Another common factor (mostly seen in registration forms) is a terms and conditions text area. When filling out forms of this nature you typically do not want the user to 'review' this information. To hide these fields from the users review you can simply add "ignore" to the FRONT of the name. For example:

<textarea name="ignore-terms-and-conditions" rows="8" cols="40">
      Terms and conditions that go on and on and on and on....
   </textarea> 

The script breaks down this name as "Terms and Conditions" and does not display it to the user. Ignored fields are, however, included in the emailed results.

Email Validity

Any field name with the string 'email' in it will be flagged as needing to be a valid email address. The standard regular expression is used to check for this validity. For example:

<input type="text" name="email-address" value="erik@erikreagan.com" id="email" /> 

The script will flag this field as needing to validate as an email address because it sees 'email' in the name. It will display as "Email Address"

<input type="text" name="user-e-mail" value="erik@erikreagan.com" id="useremail" /> 

The script will flag this field as needing to validate as an email address because it sees 'email' in the name. It will display as "User Email" because the hyphen is treated like every other hyphen and is replaced by a space

<input type="text" name="users-mail" value="erik@erikreagan.com" id="usersmail" /> 

The script will NOT flag this field as needing to validate as an email address because there is no full string of 'email' in the name

Form Method & Action

In order for this script to work without tweaking the core of the php the method of the form must be POST. For example:

<form name="form-name" method="post" action="path/to/process-form.php"> 

Notice the action in the above example. This is what you should set the action to (but fill in YOUR path) if you are using the form processor as a standalone script. If you are using it inside your own site this may vary. You could leave it blank (action="") if the script is already loaded into the same page. I trust if you are including the script in your own template you can tweak the settings as needed.

Setting up Checkboxes and Selects for multiple options

Many times you will need to allow the user to check multiple boxes or select multiple options. In order to process the results as one result you must tell the form and script that the results are lumped into an array. This is a simple process but if overlooked the results will not be pleasing

<p>Favorite Types of Cars</p>
   <select name="car[]" id="car" multiple>
      <option value ="Volvo">Volvo</option>
      <option value ="Saab">Saab</option>
      <option value ="Opel">Opel</option>
      <option value ="Audi">Audi</option>
   </select> 

In this example the Select name is "car[]". The brackets are saying to the form "Put the following results into an array" and then when the results are being processed the script sees the array and displays the results as 1. For example if the user were to pick Volvo and Audi from the above example it would be displayed as "Volvo, Audi".

You can achieve a similar result by using check boxes

Volvo <input type="checkbox" id="volvo" name="car[]" value="volvo" />
   Saab <input type="checkbox" id="saab" name="car[]" value="saab" />
   Opel <input type="checkbox" id="opel" name="car[]" value="opel" />
   Audi <input type="checkbox" id="audi" name="car[]" value="audi" /> 

Setup & Customization - THE SCRIPT

The configuration for the script is in the file process-from-settings.php. These variables should be modified to your preference. I do not guarantee support of any modification of the actual script! Let's take a look at each option. The default values are displayed below.

$using_template = FALSE;

This variable defines whether or not you are using the script by itself or within your design or site. The available options are simply TRUE or FALSE

$custom_form = "path/to-your/form.php";

If you set $using_template to TRUE then you can include your form within the process-form.php script by putting the path to your form here. You would then access the form page by the process-form.php page directly or by using something like include('process-form.php') on your site.

$email_recipient = "recipient@theirmail.com";

This is fairly obvious. One note, however, is acceptable formats. You could use the above format (handle@domain.com) or you can use a format such as "Erik Reagan <erik@erikreagan.com>". You can also string together multiple recipients by adding a comma between. Two examples:

  • $email_recipient = "erik@erikreagan.com, erik@idealdesignfirm.com";
  • $email_recipient = "Erik Reagan <erik@erikreagan.com>, Big Dorky Guy <erik@idealdesignfirm.com>"

$bcc_recipient = "another-email@domainname.com";

This is for sending a blind carbon copy (bcc) to additional addresses

$forward_user = TRUE;

By default the script shows the user a success page and then using javascript to forward to a new location. If you do not want to forward the user for any reason set this value to FALSE.

$final_destination = "http://mywebsite.com/thankyou.html";

If $forward_user is set to TRUE then this is the location you will forward them to. It can be as specific as above or it can be relative to your site. For example if you just want them to go to your homepage (assuming your homepage is somethinghere.com) you can set this value to "/".

$subject = 'My PHP Form';

This is the subject of the email sent containing the results

$subject_in_form = FALSE;

This is used if you are allowing the user to type in the subject

$subject_field = "required-subject";

This is used to tell the script what the input field name is of the subject if the user is typing it in manually.

$from_name = "Your Name";

This is the "From" Name when when sent.

$from_name_in_form = TRUE;

This is the same function as $subject_in_form respective to the from name.

$from_name_field = "required-your-name";

This is the same function as $subject_field respective to the from name field.

$from_email = "handle@domainname.com";

This is the "From Email" address when sent.

$from_email_in_form = TRUE;

This is the same function as $from_name_in_field and $subject_in_field respective to the from email field.

$from_email_field = "required-your-email";

This is the same function as $from_name_field and $subject_field respective to the from email field.

$bypass_review = FALSE;

If you want to skip the Review/Print screen this can be set to TRUE.

$include_timestamp = TRUE;

If set to TRUE this adds the date and time at the end of the form results once emailed.

$include_blank_fields = TRUE;

If set to TRUE this includes fields that the user did not fill in and they are given a value of "[ left blank ]".

$email_html = TRUE;

This allows you to define what type of email formatting is sent. Set this to FALSE if you prefer plain text. A vast majority of email clients support the level of HTML that this script produces so I suggest leaving it where it is unless you really need plain text emails sent.

$header_troubles = FALSE;

This variable corrects an error some Unix servers have when processing email headers defined by PHP. If you are having issues with email headers try setting this to TRUE and submit the form again.

Your Style Sheet

If you choose to include this within your own template or design I've listed below the fields you may want to customize in your stylesheet(s). There are three portions to the display of the processed form. The main DIVS are 'top', 'results' and 'email'. 'top' contains the header only ("Form Results" & "Please Review Your Information") 'results' contains - you guessed it! - the results of the processed form. Keep in mind this COULD include error results. They are inside a DIV of their own nested inside of the 'results' div. 'email' contains the hidden fields while the user reviews their information. Also of note is that the Print, Email and Back buttons are inside this div. Here's the general layout (including just about every option):

  • #top
  • #top > h2
  • #top > h5
  • #results
  • #results > div.error
  • #results > div.error p
  • #results > div.error strong
  • #results > div.error ul
  • #results > div.error ul li
  • #results > div.error p a
  • #results > ul#display
  • #results > ul#display li
  • #results > ul#display li strong
  • #results > ul#display li span
  • #email
  • #email > input#print
  • #email > input#submit
  • #email > input#back

PHP Functions Used in script

  • array_key_exists()
  • count()
  • date()
  • define()
  • empty()
  • htmlspecialchars()
  • implode()
  • in_array()
  • is_array()
  • mail()
  • preg_replace()
  • stripslashes()
  • strstr()
  • strtolower()
  • str_replace()
  • ucwords()