Phorm™ v3.5.2
Copyright © 2005 Holotech Enterprises.

Data Validation:
      With Phorm, you can specify criteria for validation of the form data - ensuring numbers are within a certain range, checking email addresses, etc. Data validation is one of the most powerful features of Phorm, but can also be one of the trickiest. Read this section carefully, and pay special attention to the file format described below and the example rule file at the end of this section.

      To use this feature, create a rule file and put its name in the variable $PHORM_VALDEFS. This is a plain text file in the following format: 
   FILES
   [FileName]
   [FileName]
   [FileName]
   ###

   RULE: [identifier]
   CRIT: [criterion]
   ARGS: [arguments]
   COND: [condition]
   FFLD: [form field]
   LEVL: [error level]
   CMNT: [comment]
   MESG:
   [error message]
   ###
      The FILES section specifies one or more error message templates to output if validation fails. [FileName] is the name of an error template file; it is a standard HTML file, and may also contain variable substitutions as described in the Using Phorm section. If you list more than one template, the error level of a rule indicates which to use. If you do not specify any files, or the file specified cannot be opened, Phorm will use the file valid_err.html in the files subdirectory, or an internal template if even that cannot be found.

      If you do not specify a path, Phorm will look for the error template file in the templates directory for the form. There is a special construction which can be used here. If you begin the path with $/ Phorm will replace this with the value of the environment variable $DOCUMENT_ROOT. This is a variable which is set by your server, and points to the root directory of your web site.

Validation Rule Format
      A validation rule has eight components: a rule identifier, a criterion, criterion arguments, a condition, a form field name, an error level, comments, and an error message. Each component is indicated by a token:
RULE
The RULE component provides an identifier for the rule, so it can be inserted into the error template. It is optional; if not present, the rule will be assigned a sequential number based on its position in the file.
CRIT
The CRIT component specifies the criterion against which to evaluate the field. A full list of criteria is given below. This component is required.
ARGS
Some criteria have arguments (don't ask me why they're called that). The ARGS component specifies the arguments for criteria that require them. Arguments are detailed under the criteria definitions. You can use standard variable substitution in arguments.

Note: Some criteria (such as ONEOF) can have more than one argument. These arguments are separated by spaces. To include a space as part of an arugment, add a \ (backslash) character before it.
COND
The COND component specifies a condition for the rule. If the condition is not true, the rule will not be evaluated. For example: 
  CRIT: REQ
  FFLD: Field1
  COND: $Field2 == "Yes" && $Field3 != "No"
will require Field1 only if Field2 has the value "Yes" and Field3 does not have the value "No". Note the double equal sign in the expression: The expressions you use here are evaluated directly by PHP, and therefore must use PHP operators. They are:

    == Equal To
    != Not Equal To
    > Greater Than
    < Less Than
    >= Greater Than or Equal To
    <= Less Than or Equal To
    && Logical AND
    || Logical OR

For more information on operators and on precedence of logical operators, refer to the PHP documentation at http://www.php.net/manual/en/language.operators.php.
FFLD
The FFLD component specifies the form field to evaluate. You can concatenate (stick together) multiple fields by putting them together with a dot character between them. For example: 
  CRIT: UNIQUE
  FFLD: FirstName.LastName
LEVL
The LEVL component sets the error level of the rule. The error level corresponds to the list of files in the FILES section of the rules file. Error level 1 uses the first file, and so on. This component is optional; if it is not set the rule will have an error level of 1.
CMNT
A comment about the rule. This component is completely ignored by Phorm.
MESG
The MESG component specifies the message to be displayed if the rule fails. It can be as long as you wish, and contain HTML and standard variable substitution.
The tokens can also be spelled out, and are not case-sensitive. A line containing just ### ends the rule definition.

Validation Criteria
      The following are the validation criteria available:

REQ    Simply, the field is required. It must have something in it. This does not work for file upload fields.
EMAIL    A valid email address.
CCARD    A number in valid credit card format.
PHONE    A number in valid U.S. phone number format.
PHONEC    Contains only valid phone number characters: 0-9, parentheses, plus sign, hyphen and space
FLDLEN    The data entered is a specified length.
REGEX    The field matches a given regular expression.
ALPHA    Contains only alphabetic characters.
NUMERIC    Only digits 0-9, commas and/or periods.
DATECMP    Compare a date against today's date or a specified range.
RANGE    An inclusive numeric or alphanumeric range.
ONEOF    One of a list of items.
UNIQUE    The value doesn't already exist in a database table.
EXISTS    The value does already exist in a database table.
FILEREQ    A file upload is required for the specified file field.
NOFILE    The visitor specified a file for upload, which doesn't exist on his or her system.
FILEDSC    The visitor uploaded a file with the same name as an existing file on your system, and it was discarded.
FILEEXT    Specifies valid file extensions for an uploaded file.
FILESIZ    Specifies a maximum file size for uploaded files.
FILERR    Indicates a message to display if there is an error saving the file on your system.
GT    Greater than the specified value.
LT    Less than the specified value.
EQ    Equal to the specified value.
GE    Greater than or equal to the specified value.
LE    Less than or equal to the specified value.
NE    Not equal to the specified value.

EMAIL    <<
      The EMAIL criterion has five levels of checking; each level above 1 includes all the checks of the prior level(s). Level 1 checks that:       Level 2 checks to see if the string after the dot is a valid TLD (i.e. com, net, org, edu, gov, mil, int, arpa, aero, biz, coop, info, museum, name or a two-letter country code). If the TLD is a country code, it checks that the next level domain is valid (com, net, org, edu, gov, mil, co, ne, or, ed, go, mi -- for example, mydomain.com.au). Level 3 checks to see if there is an MX record for the domain. Level 4 attempts to connect to port 25 on an MX host, and Level 5 checks if there's an answer.

      Level 1 is (as far as I know) bulletproof: if the address fails level 1, it's invalid. Level 2 is still pretty solid, but might fail a valid address if there's a TLD I didn't know about (not likely) or others are added (could happen). Levels 3-5 are less reliable, the higher you go. Factually, in the end there is no completely foolproof way to check the validity of an email address except to send something to it and see whether it bounces. For this reason, I don't recommend that you flatly reject an email address if it fails level 3, 4 or 5. You may want to ask the visitor to confirm that it's correct, but then you should accept it. There are simply too many ways a valid email address could fail levels 3, 4 or 5 at any given time, and still work at another time. 
   CRIT: EMAIL
   ARGS: 2
   FFLD: PHORM_FROM
   MESG:
   The email address you entered is not valid. Please correct it and
   re-submit the form.
   ###
      The EMAIL criterion has one argument -- the level of checking to perform. If no level is specified, it defaults to level 2.

CCARD    <<
      Important: Validation with the CCARD criterion checks format only and does not guarantee that the credit card itself is valid or that it has sufficient credit for the transaction being processed.

      However, with that said, CCARD does do more than simply check for a certain number of digits. A valid credit card number has a certain pattern depending on what type of card it is, and conforms to an specific mathematical formula, and Phorm checks these things. More information on the criteria Phorm uses to validate credit card numbers can be found at http://www.paylib.net/ccval.html

      The CCARD criterion requires one argument -- the name of a field that specifies what kind of card it is. Valid contents for this field are the full name of the card or a 3-letter abbreviation:

   Mastercard MCD
   Visa VIS
   American Express AMX
   Discover DSC
   Diners Club DNC
   JCB JCB
   Delta DLT
   Switch SWI
   EnRoute ENR

      So, for example, your form might look like this: 
   Card Type:
   <INPUT TYPE=RADIO NAME="CType" VALUE="MCD"> Mastercard
   <INPUT TYPE=RADIO NAME="CType" VALUE="VIS"> Visa

   Card Number:
   <INPUT TYPE=TEXT NAME="CNum" SIZE=20 MAXLENGTH=20>
      In your rules file, then, you would have: 
   CRIT: CCARD
   ARGS: CType
   FFLD: CNum
   MESG:
   The credit card number you entered is not valid. Please correct it and
   re-submit the form.
   ###
PHONE    <<
      The PHONE criterion checks that the field contains a valid U.S. phone number. Acceptable formats are:

     (###) ###-####
     (###) ### ####
     ###-###-####
     ### ###-####
     ### ### ####
     ###-####
     ### #### 
   CRIT: PHONE
   FFLD: PhoneNum
   MESG: 
   Please enter a phone number in the format ### ###-####
   and re-submit the form.
   ###
      Unfortunately, the PHONE criterion is not able to support phone numbers in other countries. Any suggestions for this are welcome. In the meantime, refer to the PHONEC and REGEX criteria.

PHONEC    <<
      The PHONEC (phone characters) criterion checks for valid phone number characters: 0-9, parentheses, plus sign, hyphen and space.

DATECMP    <<
      The DATECMP criterion allows you to compare a date against today's date or a specified range of dates. It can have one or two arguments. The first argument can be a comparison operator or a date. The second argument, if present, must be a date.

      Valid comparison operators are = < > <= >= != (the != operator means "is not equal"). If there is only one argument and it is a comparison operator, the comparison is made against the current date. If there is a second argument, the comparison is made against that date. If both arguments are dates, the date in the form field must be in the range of the two dates, inclusive.

      To specify only a starting date and no ending date, enter only one date argument. To specify only an ending date and no starting date, use 0/0/0000 for the starting date. Dates are specified in m/d/y format; if the year is two digits, it is assumed to be for the current century. I know this is a bit confusing, so some examples should help: 
   CRIT: DATECMP
   ARGS: =
   (today's date)

   CRIT: DATECMP
   ARGS: <=
   (on or before today's date)

   CRIT: DATECMP
   ARGS: < 2/19/02
   (before Feb 19, 2002)

   CRIT: DATECMP
   ARGS: >= 2/19/1957
   (on or after Feb 19, 1957)

   CRIT: DATECMP
   ARGS: 2/19/01 2/19/02
   (Feb 19, 2001 - Feb 19, 2002)

   CRIT: DATECMP
   ARGS: 2/10/01
   (on or after Feb 19, 2001)

   CRIT: DATECMP
   ARGS: 0/0/0000 2/19/02
   (on or before Feb 19, 2002)
RANGE    <<
      The RANGE criterion checks that the field contents are within a specified range: 
   CRIT: RANGE
   ARGS: 35 40
   FFLD: AGE
   MESG:
   I'm sorry, this survey is for people between the ages of 35 and 40.
   ###
      The RANGE criterion requires two arguments -- the lower and upper bounds of the range, inclusive. You can also specify a character or string range.

ONEOF    <<
      The ONEOF criterion allows you to specify a set of strings, which the contents of the field must match one of. 
   CRIT: ONEOF
   ARGS: US UK CA AU
   FFLD: Country
   MESG:
   Sorry, we only have tour packages for the US, UK, Canada and Australia.
   ###
      The ONEOF criterion can have any number of arguments, all separated by spaces.

FLDLEN    <<
      The FLDLEN criterion allows you to specify a minimum and maximum length of data for a field. This criterion is unique in that if it fails, you have the option of altering the data, or generating an error like other criteria. This criterion requires three arguments: a minimum length, a maximum length, and an operation flag. If you set the maximum length to zero, it indicates there is no maximum. The operation flag indicates whether to generate an error, or truncate the data if it's too long. A ! flag indicates to generate an error; a = flag indicates to truncate. 
   CRIT: FLDLEN
   ARGS: 3 9 !
   FFLD: Password
   MESG:
   Your password must be 3 to 9 characters long.
   ###
   (validation will fail)

   CRIT: FLDLEN
   ARGS: 3 9 =
   FFLD: UserName
   MESG:
   This message will not be displayed.
   ###
   (data will be truncated if > 9 characters, but will pass validation)

   CRIT: FLDLEN
   ARGS: 5000 0
   FFLD: Essay
   MESG:
   The essay answer must be at least 5,000 characters.
   ###
   (no maximum length)
REGEX    <<
      The REGEX criterion allows you to check a field against a regular expression. If you are not familiar with regular expressions, they are a very powerful method of pattern matching. You can find a good reference at http://virtual.park.uga.edu/humcomp/perl/regular_expressions.HTML 
   CRIT: REGEX
   ARGS: ^[A-Za-z0-9]*$
   FFLD: Answer
   MESG:
   Your answer must contain only letters and numbers.
   ###
      The REGEX criterion requires one argument -- the expression to be evaluated.

UNIQUE    <<
      The UNIQUE criterion allows you to check that the value of a field doesn't already exist in a MySQL table. This criterion requires two arguments: the first is the name of the MySQL column to check; the second is the table to look in. Examples: 
   CRIT: UNIQUE
   ARGS: UserName Customers
   FFLD: Name

   CRIT: UNIQUE
   ARGS: CustID CustomerTable
   FFLD: CustomerID
      The first example checks the field Name against the column UserName, in the table Customers. The second compares CustomerID against the column CustID in the table CustomerTable.

      You can check two or more fields against two or more database columns. For example, if you have separate fields for first name and last name in your form, and want to compare them both against their respective database columns and fail only if they both match, you would concatenate the fields in the FFLD component and the table names in the ARGS component: 
   CRIT: UNIQUE
   ARGS: dbFirstName+dbLastname CustomerTable
   FFLD: FirstName.LastName
This concatenates the database fields dbFirstName and dbLastName and compares the result to the concatenated values of $FirstName and $LastName.

EXISTS    <<
      The EXISTS criterion is the opposite of the UNIQUE criterion -- it checks that the value of a field does already exist in a MySQL table. It uses the same arguments as the UNIQUE criterion. It also can check against multiple columns like the UNIQUE criterion.

FILEREQ    <<
      The FILEREQ criterion indicates that the visitor must upload a file for the specified field. This rule is triggered only if the visitor leaves the file field blank - entering a non-existent file will trigger the NOFILE criterion. For all file upload validation criteria, specify only the numeric portion of the field name (see the File Upload section for more information): 
   CRIT: FILEREQ
   FFLD: 01
   MESG:
   You must upload a diagram file with your specification
   ###
NOFILE    <<
      The NOFILE criterion indicates a message to be displayed if the visitor attempts to upload a file which does not exist on his or her system. It is recommended that you have one NOFILE rule for each file field on your form. For all file upload validation criteria, specify only the numeric portion of the field name (see the File Upload section for more information): 
   CRIT: NOFILE
   FFLD: 01
   MESG:
   The file you specified could not be found on your system.
   Please check the path and name.
   ###
FILEDSC    <<
      The FILEDSC criterion triggers if the visitor uploads a file with the same name as an existing file, and $PHORM_CMODE is set to ph_DISCARD for the specified field. For all file upload validation criteria, specify only the numeric portion of the field name (see the File Upload section for more information): 
   CRIT: FILEDSC
   FFLD: 01
   LEVL: 0
   MESG:
   The file you uploaded already exists. The existing copy was retained.
   ###
The error level of 0 means that validation will not fail, and the message will be available for insertion in the acknowledgement template (see Displaying Validation Error Messages below).

FILEEXT    <<
      The FILEEXT criterion specifies a list of acceptable file extensions for the specified field. The extensions are specified as arguments to the criterion. For all file upload validation criteria, specify only the numeric portion of the field name (see the File Upload section for more information): 
   CRIT: FILEEXT
   ARGS: jpg jpeg jpe gif pdf ppt
   FFLD: 01
FILESIZ    <<
      The FILESIZ criterion specifies a maximum size for an uploaded file. It requires one argument, the size in bytes. If it is exceeded, the uploaded file will be discarded. Note that, if there is insufficient space on your system to store the uploaded file, you will get a FILERR condition, rather than this one. For all file upload validation criteria, specify only the numeric portion of the field name (see the File Upload section for more information): 
   CRIT: FILESIZ
   ARGS: 1000000
   FFLD: 01
   The maximum file size is 1MB.
   ###
There is a special hidden field you can add to your form to specify the maximum file size. The name of the field is MAX_FILE_SIZE: 
   <INPUT TYPE="HIDDEN" NAME="MAX_FILE_SIZE" VALUE="30000">
The file must come before the file input field, and the value is specified in bytes. You should not rely on this field to limit your upload size, though - it only serves to advise the browser, and is easily circumvented. The FILESIZ criterion cannot be fooled. However, it is good to use the MAX_FILE_SIZE field, as it saves the visitor the trouble of uploading a large file, only to find out it was too big.

FILERR    <<
      The FILERR criterion indicates a message to be displayed if there is an error saving the specified file on your system. This could be due to any number of things, such as insufficient disk space, no access to the upload directory, etc. It is recommended that you have one FILERR rule for each file field on your form. For all file upload validation criteria, specify only the numeric portion of the field name (see the File Upload section for more information): 
   CRIT: FILERR
   FFLD: 01
   There was a problem saving your file. Please try again.
   ###
Other Criteria    <<
      The remaining criteria -- REQ, ALPHA, NUMERIC, GT, LT, EQ, GE, LE, NE -- are pretty self-explanatory. See the example rule file below for...well...examples. Keep in mind that the space and tab characters are significant.

Example rule file: 
FILES
error1.html
error2.html
###

CRIT: EMAIL
ARGS: 2
FFLD: PHORM_FROM
MESG:
It appears that the email address {{PHORM_FROM}} is invalid.
Please use the BACK button on your browser to correct it,
and re-submit the form.
###

CRIT: CCARD
ARGS: CardType
FFLD: CardNum
LEVL: 2
MESG:
The credit card number you entered is not valid. Please use the 
BACK button on your browser to correct it, and re-submit the form.
###

CRIT: PHONE
FFLD: PhoneNum
LEVL: 2
MESG:
Please enter your phone number in the format (###) ###-####. Use the
BACK button on your browser to correct this, and re-submit the form.
###

CRIT: RANGE
ARGS: 35 40
FFLD: Age
LEVL: 2
MESG:
I'm sorry, this survey is for people between the ages of 35 and 40.
###

CRIT: ONEOF
ARGS: MI HI
FFLD: State
LEVL: 2
MESG:
I'm sorry, this offer is only available in Michigan and Hawaii.
###

CRIT: LT
ARGS: 4
FFLD: Qty
LEVL: 2
CMNT: Delete this rule after the summer special.
MESG:
I'm sorry, the maximum quantity at the special price is 3. Use the BACK
button on your browser to correct this, and re-submit the form.
###

CRIT: GT
ARGS: 20
FFLD: Age
MESG:
I'm sorry, you must be at least 21.
###

CRIT: FILEREQ
FFLD: 01
MESG:
You must upload a diagram file along with your specification
###

CRIT: FILEEXT
ARGS: jpg jpeg jpe gif pdf ppt
FFLD: 01
MESG:
Uploaded files must be in JPEG, GIF, PDF or PowerPoint format.
###
If you prefer, component tags can be spelled out: 
Criterion: LT
Arguments: 4
Field    : Qty
Level    : 2
Comment  : Delete this rule after the summer special.
Message  :
I'm sorry, the maximum quantity at the special price is 3. Use the BACK
button on your browser to correct this, and re-submit the form.
###
      Blank lines are ignored. Note that an empty field will pass all validations except REQ and FLDLEN (if you want an empty field to pass FLDLEN, specify a minimum length of zero). It is acceptable to specify more than one rule for a field.

Displaying Validation Error Messages
      To display the error message(s), create a regular HTML file, with variable substitutions if desired, and with message indicators where you want the messages displayed. The name of this file goes at the top of the rules file, under the FILES header. You can have different files for different error levels. The first file listed will be used for Level 1, the second file for Level 2, etc. If the error level of a rule exceeds the number of files in the list, the last file will be used. If no files are specified, a generic error page will be displayed.

      A message indicator has one of the following forms: 
   <!-- Phorm Messages -->
   <!-- Phorm Messages [field|rule] -->
      If you use the first form, all of the data validation error messages will be inserted at that point in the file, separated by a <BR> tag. In this form, only the message(s) of the highest level will be displayed. For example, in the above rule file, if the visitor enters an invalid phone number and is out of the age range, only the age message will be displayed.

      In the second form, put a field name or a rule identifier in the place of [field|rule]. If you use a field name, all messages from rules that failed for that field will be inserted at that point. If you use a rule number or name, then the message for just that rule (if it failed) will be inserted.

      Processing ceases after any validation error greater than zero. It is perfectly acceptable to have an error level 0. In this case, processing proceeds as usual, and if there is a message indicator in the ack template, any messages will be displayed there. This can be used for warnings or special notifications. Only the first form of the indicator can be used in the ack template.

PHP Code
      If you know PHP, you can include PHP code in your error template, and it will be executed. Simply give your template a PHP extension (.php, .php3 or .php4) and set the variable $PHORM_PARSPHP to true. For security reasons, variable substitution is performed after the file is passed to the PHP parser. There are a number of Phorm variables and functions available to you. For more details, see the plugin programming documentation.

Data Recycling
      If there are <INPUT>, <TEXTAREA> or <SELECT> tags in the file used to display the validation error messages, their VALUE attribute will be set to the value of any variable with the same name. For example, if the variable $Name has the value "Albert Einstein", and the file has the following tag: 
   <INPUT TYPE=TEXT NAME="Name">
then that tag will be given a VALUE="Albert Einstein" attribute. If the tag already has a value attribute, it will be overridden by the variable value. The purpose of this is to allow "data recycling". If a visitor submits a form and it fails validation, you can have a copy of the form as the error template, and the visitor's values will be filled in in the fields. You actually could even use the original form file as your error template; since the <!-- Phorm Messages --> flag is an HTML comment, it won't appear when the form is initially displayed.

0101000001101000011011110111001001101101010010010111001101000011011011110110111101101100