Form Solution -- Manual

Table of Contents

 

Description

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

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:

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:

Arguments Type Default Description
Foo string -- Header above boingie tables.
Fluff int 1 Number of fluffs in boingie tables.

Things to note:

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.

Arguments Type Default Description
From string -- Name of an object which has the contents you want to copy.
    $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.

Arguments Applies to which Periods Type Default Description
Period all string -- Type of list to generate: 'year', 'month' and 'day', 'hour', 'minute' or 'second'. Choice is case sensitive.
Default all array
variable
string
C (urrent)
x
C Default value(s) selected in the list. If you'd like nothing to be selected, use 'x'. To get the current time for an element, use 'C'.
When using arrays:
• Associative or enumerated keys can be used.
• The items to be selected go in the array's value fields.
• If Multiple is "N", only the first array element will be used.
Name all string Same as Period Name of the form element.
Zero all N (o)
Y (es)
E (mpty)
B (oth)
N Should zero and/or null values be listed? See tables, below for details on how these settings affect output depending on what data type is used for Default.
Size all int 0 Number of rows visible at one time. "0" sets no size attribute, which is preferable when Multiple is "N".
Multiple all Y/N N Should multiple selections be permitted? If set to "Y", browsers may display the whole list by default if no Size is set.
Begin year int 2 years ago Which year the list should start at (YYYY).
Years year int 5 How many years should be on the list.
Class all string   If this argument is supplied, a class attribute (class="your_input") will added to the <select> tag.
ID all string   If this argument is supplied, an ID attribute (id="your_input") will added to the <select> tag. Helpful for use with <label> elements to allow keyboard navigation via accesskey.
 
Output for year, month and day Periods
depending on Default and Zero arguments
Default Zero
N Y E B
empty current current empty empty
NULL current current empty empty
00 or 0000 current 0 empty 0
Integer (non 0) integer integer integer integer
C current current current current
 
Output for hour, minute and second Periods
depending on Default and Zero arguments
Default Zero
N Y E B
empty current current empty empty
NULL current current empty empty
Integer (including 0) integer integer integer integer
C current current current current

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.

Arguments Type Default Description
Year int in YYYY format -- Year to be evaluated. Must be greater than 1969.
Month int in MM format -- Month to be evaluated
Day int in DD format -- Day to be evaluated
ObjVarTo string Date Name of an object variable to which the correct date is to be assigned, not the name of the object itself.
Format string Y-m-d Format you wish the time to be in. Uses the same formatting codes as PHP's date() function.
Zero Y/N N Is 0000-00-00 a valid date?
    $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.

Arguments Type Default Description
To string -- The email address you want the form results sent to.
Opt array   An array holding options for the layout of the form and tables.
 
Potential Elements for the $Opt Argument Array
Option Type Default Description
alignf left | center | right   How the form table should be aligned on the page.
alignp left | center | right   How the preview table should be aligned on the page.
borderf int 0 Form table border size. "0" = none.
borderp int 1 Preview table border size. "0" = none.
captionf string   HTML Caption that can go above or below the form table.
captionp string   HTML Caption that can go above or below the preview table.
captionalignf top | bottom   Where the form caption should go.
captionalignp top | bottom   Where the preview caption should go.
cellpaddingf int   Amount of padding in the form table cells.
cellpaddingp int   Amount of padding in the preview table cells.
cellspacingf int   Spacing between the form table cells.
cellspacingp int   Spacing between the preview table cells.
classf string   Class HTML element attribute that can be placed in each tag of the form table and form output. Helpful with formatting via Cascading Style Sheets.
classp string   Class HTML element attribute that can be placed in each tag of the preview table output. Helpful with formatting via Cascading Style Sheets.
idf string   id attribute that can be placed in the <form>. Helpful with formatting via Cascading Style Sheets.
idp string   id attribute that can be placed in the preview <table> output. Helpful with formatting via Cascading Style Sheets.
prefixs string   String prepended to the subject line of the email sent to you. As of version 5.7.
names array
$Opt = array(
    'names' => array(
        'Name' => 'one',
        'Email' => 'two',
        'Subject' => 'three',
        'Message' => 'four',
        'Submit' => 'five',
    ),
);
A map of the name attributes used in the form. This makes it easy to change the name attributes' values, making it harder for spam bots to do their job. When using this option, copy this sample array, and tweak the values as desired, BUT DO NOT CHANGE THE KEYS. As of version 5.10.
rows integer 8 Rows in the form's Message field.
size integer 40 Width of the form's input fields.
summaryf string   Description of the table that can get put into the form table's <table> tag.
summaryp string   Description of the table that can get put into the preview table's <table> tag.
suppressresults boolean false Allows suppression of the "results" output table on success.
widthf numeric string   Form table width. Can be in pixels or percent (eg: "75" or "75%").
widthp numeric string   Preview table width. Can be in pixels or percent (eg: "75" or "75%").
    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.

Arguments Type Default Description
Input string -- String or number that should be checked.
Keep string   Which characters should be kept. The string used is case sensitive. See the table below for which types are available.
Max int 200 Maximum length the input should be allowed.

The Keep argument, above, has the following predefined options
Keep Permits the following characters
Num 0-9
Decimal 0-9.-
IP 0-9.
Alpha A-Za-z
AlphaNum A-Za-z0-9
AlphaNumSpace A-Za-z0-9 plus space (" ")
AlphaNumAll AlphaNumSpace plus all horizontal and vertical whitespace characters.
AlphaForeign A-Za-z

AlphaForeignNum AlphaForeign plus 0-9
AlphaForeignNumSpace AlphaForeign plus 0-9 and space (" ").
AlphaForeignNumAll AlphaForeignSpace plus all horizontal and vertical whitespace characters.
Email -!#$%&'*+/=?^_`{|}~A-Za-z0-9.@
URI A-Za-z0-9!#$%&'()*+,-./:;=?@_~
EmailForm URI plus " and all horizontal and vertical whitespace characters.
Default AlphaForeign plus 0-9 and space (" ") and +./:=@_~-
Notes:
• The character set used is ISO 8859-1.
• "0-9", "A-Z" and "a-z" represent the range of characters between and including the stated characters.
• The list of characters allowed in URI's was derived from RFC 2396.

URI Warning: The URI setting permits several characters that are dangerous. When using such input inside exec(), system() and passthrough() calls, make sure to use escapeshellcmd()! When using such input inside queries, use addslashes()!

Default Warning: The default setting lets through the "~" character. This is a special character when used inside exec(), system() and passthrough() functions. This character, when used alone or at the beginning of a word, represents the user's home directory. This character is permitted through the default screening because it is commonly appears in URI's and poses only minor problems inside command lines. So, remember to use escapeshellcmd() when running Program Execution functions.

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.

Arguments Type Default Description
Hour int in HH format -- Hour to be evaluated
Minute int in MM format -- Minute to be evaluated
Second int in SS format -- Second to be evaluated
ObjVarTo string Time Name of an object variable to which the correct date is to be assigned, not the name of the object itself.
Format string H:i:s Format you wish the time to be in. Uses the same foramtting codes as PHP's date() function.
    $Form->TimeValidateAndFormat($Form->StartHr, $Form->StartMin,
            $Form->StartSec, 'StartTime', 'g:i A');



Credits