THE ANALYSIS AND SOLUTIONS COMPANY Home Blog Advantages Databases Websites Software Tutorials Writings Presentations Resume Contact Address Standardization Calendar Credit Card Validation Form Layout Log Monitoring Simple Session SQL ST Parser Manual Requirements Functions Change Log FAQ Download License

Form Solution -- Manual

Table of Contents

• Description
• Setup and Use
  • Basic Concepts
  • Reserved Words
• Constructor Class and Function
• Functions
  • CopyObjectContentsIntoForm()
  • DateTimeOptionList()
  • DateValidateAndFormat()
  • EmailForm()
  • StripBadCharacters()
  • TimeValidateAndFormat()
• Credits

Description

Form Solution contains two PHP classes for easily dealing with HTML forms. Here's a quick run down of what this program does:

• Generates date, time, state and email form elements
• Cleans user input
• Validates date and time inputs
• Holds all of the variables submitted by a form

The result is improved security and data quality as well as making things easier to program.

The form elements are XML compliant, conforming to the W3C's "Strict" Extensible HyperText Markup Language (XHTML) 1.0 DTD standard.

Setup and Use

Basic Concepts

For those unfamiliar, or vaguely familiar, with PHP and/or classes, here's a quick set of instructions to get you started. Please note, before doing any of this, you'll need PHP installed.

1. Download the program.
2. Move to the place you saved it and unzip it. That will create a files named form.inc
3. Change the file's permissions to world readable via chmod 604 *.inc or Windows Explorer
4. Open a new document in a text editor and place the following code in that file:

      <?php
      require '/includes/form.inc';
      $Form = new FormSolution;
      echo '<form method="post" action="foo.htm">';
      $Form->DateTimeOptionList('month');
      echo '<input type="submit" name="Submit" value="GO!" />';
      echo '</form>';
      ?>
     

   Those commands peform the following tasks:
   1. Reads the file form.inc into your present file.
   2. Creates an object named $Form.
   3. Displays a list box containing the months in a year.
5. Replace /includes with the full or relative path to the directory where you saved the file.
6. Save the file on your webserver.
7. Change the file's permissions to world readable via chmod 604 or Windows Explorer.
8. Navigate your web browser over to the web page you just saved.
9. You should see an option list containing the months in a year. If not, some potential problems include:
   1. A message saying something like "Forbidden. You don't have permission..." means you need to change the web page's permissions. On Unix type systems, use chmod. On Windows systems, use the Windows Explorer to alter the file's Properties.
   2. If you see the PHP code, the file didn't get parsed by the PHP program. Alter your web server's configuration files or use the appropriate AddType in your .htaccess files.

Reserved Words

The system has three reserved variable names: Patterns_FS_RESERVED, Keep_FS_RESERVED and Max_FS_RESERVED.

Constructor Function

When the class is created (ie, $Form = new FormSolution;) the constructor function — FormSolution() — is automatically called, which does the following things:

• Each variable is checked for dangerous characters. If any are found such characters are omitted. Also, if the string is longer than permitted, the end of the string is dropped.

  The choice of valid characters and length can be set by you when via the Constructor Function's optional arguments ($Keep and $Max) when the object is created.

  There are several predefined Keep types. In addition, you can also whip up your own special ereg pattern for the $Keep argument by creating an array where the name of the pattern is the key and the pattern is the value. Then pass that array to the $Keep argument. If the array you pass has more than one element, only the first one is used. Additional patterns can be added later. See the StripBadCharacters() function for more information.

      # To use the default settings ('Default', 200), just do this...
      #
      require '/includes/form.inc';
      $Form = new FormSolution;
  
  
      # BUT, if you want to use some other settings
      # you can do something like this...
      #
      require '/includes/form.inc';
      $Form = new FormSolution('AlphaNumSpace', 50);
  
  
      # When you want all of the incoming varaibles to be cleaned
      # by your own custom ereg pattern. The Keep pattern named
      # here also remains available for use later on.
      #
      $Pattern = array('SomeName' => '[^YN]');
      require '/includes/form.inc';
      $Form = new FormSolution($Pattern, 1);
  
  
  

• The variable is then placed into the object. For example, if your form had an input element with name="Age", the value from that input becomes $Form->Age.
   
• The original variable, in this example $Age, is then removed to conserve memory and prevent inadvertent use of unchecked input.
   
• The $_GET, $_POST, $_REQUEST, $HTTP_POST_VARS and $HTTP_GET_VARS are also deleted, again to save memory and keep unscrened data from being used.

One and two dimensional arrays will get cleaned and passed along. 3+ dimensional arrays are deleted.

If a variable is submitted via both GET and POST methods, the POST variable will be the one that remains.

Functions

If a function uses arguments, they are listed in an arguments table:

Things to note:

• Arguments are listed in the order they need to be used.
• Type is the data type expected.
• "--" in the Default column means the argument is required.
• Blank cells in the Default column means the default is an empty string.

So, in this case, you'd call the function like this $Form->SomeFunction('Sediment', 33); if you wanted to set the Fluff argument manually. Otherwise, you can make life easier by letting Fluff be set to the default: $Form->SomeFunction('Sediment');.

CopyObjectContentsIntoForm()

This function copies the contents of another object to $this object. If From is not an object, the function prints that From "is not an object." and returns 0.

    $Form->CopyObjectContentsIntoForm('OtherObject');

DateTimeOptionList()

Generates an option list of date or time segments. If Default is before Begin or after the end of Begin plus Years, the value of Begin and/or Years will be adjusted to make it fit.

Several examples:

    echo '<form>';

    echo '<label for="the_id" accesskey="y"><u>Y</u>ear</label>';

    $Form->DateTimeOptionList('year', $Form->StartYear, 'StartYear',
            'N', 10, 'N', 1995, 15, 'some_class_name', 'the_id');

    $Form->DateTimeOptionList('month', $Form->StartMonth, 'StartMonth', 'N', 13, 'Y');

    echo '</form>';

DateValidateAndFormat()

Ensures dates entered by users are valid and formatted correctly. Output format is an option. Places the date into a variable within this object.

If there's a problem, the function returns 0. If everything is fine, returns 1.

    $Form->DateValidateAndFormat($Form->StartYr, $Form->StartMo,
            $Form->StartDay, 'StartDate', 'j M y', 'Y');

EmailForm()

Creates a form people browsing your site can use to contact you. Then, it processes the input received therefrom and mails it to you. Using a contact form is nice since it keeps spammers from harvesting your email address off your website.

User input is first run through StripBadCharacters() then passed through individual checks. Name can only contain letters, spaces, periods, hyphens and '. Subject can only contain letters, numbers, spaces, periods, commas, hyphens and '. The Email Address field must conform to RFC 2822 (see EmailMatch in the Keep types, below). The Message can't have < or > in it. In addition, the Message can only be up to $Form->Max_FS_RESERVED long and the rest of the fields can be up to 255 characters long. If the user submits something that doesn't conform to the above standards, an error message is generated, and the cleaned up input is shown in the form for them to modify and resubmit.

The form provides users a Preview option, so they can see how their email will look and make changes if desired.

The Message is wordwrapped at 70 characters.

Once submitted, a thank you message and a table containing their submission appear.

If there's a server problem which prohibits the mail() function from working properly, the filled in form is displayed again and a message tells the user to try again later.

$Opt = array(
    'names' => array(
        'Name' => 'one',
        'Email' => 'two',
        'Subject' => 'three',
        'Message' => 'four',
        'Submit' => 'five',
    ),
);

    require './form.inc';
    $Form = new FormSolution('EmailForm');

    $Opt = array(
        'alignp' => 'center',
        'widthp' => '75%'
    );
    $Form->EmailForm('youremail@example.net', $Opt);

StripBadCharacters()

Examine and clean up the $Input presented. If undesirable characters are found, they are dropped. If input is too long, the end is left off. It's run automatically when data is submitted, screening the input against the default settings. Then, you can use this function manually to further screen data via its more restrictive criteria.

Here's the regular way to use the function:

    $Form->StripBadCharacters($Form->Group, 'AlphaNumSpace', 40);

If you used a custom Keep when creating the class with the new operator, that Keep remains available for use here.

You can add your own Keep regular expression patterns by adding them to the Patterns_FS_RESERVED array. The array's key is the name of the expression used in the $Keep argument, while the value is the regex you want to use. For example, in your script, you can do this:

    $Form->Patterns_FS_RESERVED = array('OnlyYN' => '[^YN]');
    $Form->StripBadCharacters($Form->Agree, 'OnlyYN', 1);

Similarly, it's possible to edit existing Keep patterns.

Note: the regular expressions are run through PHP's ereg_replace() function. Items that match are replaced by a blank string.

TimeValidateAndFormat()

Ensures times entered by users are valid and formatted correctly. Output format is an option. Places the time into a variable within this object.

If there's a problem, the function returns 0. If everything is fine, returns 1.

    $Form->TimeValidateAndFormat($Form->StartHr, $Form->StartMin,
            $Form->StartSec, 'StartTime', 'g:i A');

Credits

• Many thanks to everyone on the PHP Mailing list who've given all sorts of great general programming tips.