inMail

Web Gadget: inMail

inMail is a general purpose form processor that provides many features including mandatory fields, field format checking, MySQL injection, captcha codes, file uploads (with virus scanning), and more.

Download it now

Note that you can check the version of a web gadget by loading it directly in your browser with the "version" keyword. For example, loading "inmail.php?version" will display the current version and tell you if there is a newer version available.

Installation

To install this web gadget, simply place a copy of inmail.phpin your web space. You can change the name to anything you'd like, as long as it ends with ".php". Note that this is an encoded and encrypted PHP file. It will look like gibberish to you, but the web server will know what to do with it. If you make any changes to this file it will cease to function, so be careful to upload it to your site in BINARY mode.

Configuration

When this web gadget runs it will expect to find a configuration file to load settings from. The filename depends on the name that you gave to the web gadget itself. If you named it "inmail.php" then the configuration file must be named "inmail_config.php" (that's an underscore in the middle). If you named it "feedback.php" then the configuration file must be named "feedback_config.php", and so on.

The configuration file is a PHP script that contains a list of values in the "CONFIG" array. It will look something like this (but normally with many more settings):

Please note that this is a PHP file, and as such it must start with thetag and there must be nothing else before or after these tags and each setting must be terminated with a semicolon. String values need to be enclosed in quotes, numeric values do not need quotes. Putting any other PHP code in this file may cause the web gadget to function incorrectly.

Basic Configuration Settings

$CONFIG['To']This is the e-mail address to which the form results will be e-mailed. If you don't set this then the web gadget will use your Islandnet.com address by default. You may specify multiple recipients by separating them with a comma.

$CONFIG['From'] This is the address to use in the From: header of the e-mail message that is sent. This is treated as a template, so it may contain variables. For example, if your form asks visitors to enter their e-mail address into a field named 'email', then you might set this value to "{email}". If you don't set this then the default is "nobody@islandnet.com".

$CONFIG['Subject'] This is the value to put in the Subject: header of the e-mail message. This is treated as a template, so it may contain variables. If you don't set this then the default is to look for an input form value called 'Subject' and use that, otherwise it defaults to "Form Submission".

$CONFIG['EmailTemplate'] This is a templatethat is used to format the body of the e-mail message that is sent. If this is not set then a default template is used wich is suitable for most purposes.

$CONFIG['SuccessTemplate'] This is a templatethat is displayed when the form is processed successfully. If this is not set then the default action is to display a simple "Your submission has been processed." message. If this value happens to start with "http://" or "https://", then it is assumed to be an URL and the visitor will be redirected to it.

$CONFIG['ErrorTemplate'] This is a template that is displayed when there is an error while processing the form. If this is not set then the default template is a rather plain screen that explains the error(s). If this value happens to start with "http://" or "https://", then it is assumed to be an URL and the visitor will be redirected to it.

$CONFIG['BannedWords']This is a list of words, separated with commas, that should never appear in any form fields. This is normally used to block visitors from submitting profanity-laden entries. The default is blank.

$CONFIG['MySQLHostname'], $CONFIG['MySQLUsername'], $CONFIG['MySQLPassword'], $CONFIG['MySQLDatabase']These settings provide the hostname, username, password, and database name for a MySQL database. This database is used by this web gadget for tracking such things as captcha codes and rate limiting. You must create this database, but you do not need to create any tables in it as the web gadget will automatically create what it needs. It is recommended that you create one database and use it for all your web gadget configurations (as opposed to creating a new database for each web gadget). This is not necessary if you don't use Rate Limiting or Captcha Codes.$CONFIG['MySQLTablePrefix']Normally this value will be left empty, but if you are using an existing database and you want to make sure that there are no table name conflicts, this value will be prepended to the name of any tables used by the web gadget.

$CONFIG['RateLimitMax'], $CONFIG['RateLimitPeriod']A handy technique for eliminating abuse is rate limiting, which prevents a visitor from posting more than a given number of times within a given time period. To enable rate limiting, set the 'RateLimitMax' value to the maximum number of allowed posts, and the 'RateLimitPeriod' setting to the time period (in seconds). You can also use values like '5 minutes', '2 hours', etc. For example, using values of "1" and "5 minutes" means a visitor can post no more often than once every five minutes.

$CONFIG['ACL'] This is the name of an ACL fileto use to control who can and can't post through this web gadget. If this is not set then anybody can post.

$CONFIG['SaveFile']This is the name of a file to which a copy of the form data should be appended. If this is set then you must also define the SaveTemplate option.

$CONFIG['SaveTemplate'] If you want to save form submissions to a file in your account, then you must set this value to be a templatethat defines the format to write the data with.

$CONFIG['SaveMySQLHostname'], $CONFIG['SaveMySQLUsername'], $CONFIG['SaveMySQLPassword'], $CONFIG['SaveMySQLDatabase']If you would like to save data from each form submission into a MySQL database, then these values specify the hostname, username, password, and database name for a MySQL database to use. You must also set the following "SaveMySQLTemplate" value. Note that this is unrelated to the MySQL... settings mentioned previously.

$CONFIG['SaveMySQLTemplate'] This is a templatethat is used to insert data into the MySQL database. After all the variable placeholders are processed, it must be a valid MySQL INSERT query that works for your database. For security, make sure you use the "mysqlescape" template function on any placeholder variables.

Field Configuration

In addition to the basic configuration settings listed above, you can optionally specify a variety of options for each input field in your form. The name of each settings is based on the input field name. For example, if you have a field named "firstname" in your form and you wanted to ensure that it was always at least 2 characters long, you could set $CONFIG['firstname_MinLength'] = 2;in your configuration file. Here are the different settings you can apply to individual input fields:

$CONFIG['fieldname_MinLength']The input field 'fieldname' must be at least this many characters in length to be accepted. If the field is a file upload, then this is the minimum size of the file in bytes.

$CONFIG['fieldname_MaxLength']The input field 'fieldname' must be no longer than this many characters to be accepted. If the field is a file upload, then this is the maximum size of the file in bytes.

$CONFIG['fieldname_SavePath'] This indicates that 'fieldname' is a file upload field instead of a regular form field, and it is the name of a directorywhere the uploaded file will be stored. The file name used for the file will be the same as provided by the visitor. If a file by that name already exists, a ".2", ".3", ".4", etc. will be appended to the filename. Uploaded files are scanned for malware (viruses, trojans, etc.) and rejected if one is found. For security reasons, a ".txt" extension is added to any ".php" or ".php3" files that are uploaded.

$CONFIG['fieldname_LessThan']The input field 'fieldname' must be less than this value.

$CONFIG['fieldname_MoreThan']The input field 'fieldname' must be more than this value.

$CONFIG['fieldname_LegalValues']This is a list of one or more legal values for the input field 'fieldname', separated with commas. The input field must match one of them to be accepted.

$CONFIG['fieldname_Test']This setting performs the specified test on the input field 'fieldname'. The available tests are:

• "email" - the value is tested to ensure that it is a valid email address.

   

• "url" - the value is tested to ensure that it is a valid URL.

   

• "ccnumber" - the value is tested to see if it is a technically valid credit card number.

   

• "captcha" - the value is tested to see if it is a valid captcha code (see the captcha codespage for more details)

   

• A value enclosed in slashes - the value is tested to see if it matches the regular expression between the slashes.

   

The Form Itself

After installing the web gadget and creating the configuration file, you need to create the web form that will invoke the web gadget. This is a normal web form and we assume that you know how to create one. All you need to do is make sure that the "action" attribute in the

tag points to your copy of the web gadget PHP file.

 

Using Captcha Codes

A captcha code is a great way to prevent the "spamming" of your form through automated means. To add one to your form you need to add an image that displays the code, and an input field where the visitor can type the code. You also need to add several settings to your configuration file as explained in the captcha codepage.

To generate and display a captcha code image, simply add an image tag like this one:

If you changed the name of the PHP file, then you'll need to change the name in the image link as well.

Sometimes the generated image will be difficult to read, so it's useful to give the visitor a way to generate a new one. Here is an alternative image tag that allows the visitor to generate a new one simply by clicking on the image:

This works by changing the image 'src' value to point to a new image. Since it's actually the same URL, we add the current date and time to the end of it to make it unique so that the browser will reload it (setting it to the same value would have no affect).

In addition to the image itself, you need to add an input field whre the visitor can type in the code they see. This is a normal input field and can be named anything you want. But in order to make the web gadget check it against the generated code you'll need to have a $CONFIG['fieldname_Test'] = "captcha";line in your configuration file, where 'fieldname' is the actual name of the input field.

 

Example:

To view a working example, click here.

To view the HTML form used in this example, click here.

To view the configuration file used in this example, click here.