From version 7.06, FormMail supports a server-side INI file. This How-To guide describes the function of an INI file and how to use it to improve the security of your forms.
What is an INI file?
"INI file" is short for "initialization file". Historically, INI files have been used to provide configuration settings for software packages.
FormMail's configuration is stored in the formmail.php file itself. We have implemented an INI file feature so that you can store your HTML forms' configuration information on the server instead of or as well as in the HTML form itself.
A FormMail INI file provides information about your form, not FormMail.
Why do I need an INI file?
Most forms do not need an INI file. However, some advanced users have requested features that provide more protection for their forms and for their servers.
In particular, many users want complete protection against Spambots. FormMail has always supported the AT_MANGLE feature. This allows you to hide email addresses in your HTML forms, so that it's virtually impossible for a Spam Bot to find your email addresses.
However, this is not a perfect solution because a human being may be able to decipher your email address by deducing your AT_MANGLE string.
By using an INI file, you never have to include an email address inside your HTML forms.
Below are some reasons you might want to use an INI file:
- you want to completely hide your email addresses from people and bots (automated programs) viewing your HTML forms.
- you want to enforce fields to be required when your forms are submitted. You want to ensure that bots cannot bypass your form validations.
- you want to guarantee that no malicious person or bot can submit forms in a way that can annoy you or put junk into your databases or CSV files.
Apart from the problem with spammers and email address, history shows that there is little danger from people or bots bypassing the validation in your HTML forms. For example, if you had a CSV file that is written to by FormMail under the instruction of your HTML form, it would be a relatively simple matter to construct a fake form submission that writes an invalid row into your CSV file. However, we have never had a report of malicious activity such as this.
But, if you are concerned about this type of activity, an INI file provides you with complete protection.
How does an INI file work?
An INI file is a simple text file that contains field definitions for FormMail to use in addtion to any fields provided by the form. You provide values for FormMail special fields in your INI file. Data fields (non-special fields) only come from your HTML form.
After accepting the data and special fields from a submission of your HTML form, FormMail parses your INI file and adds the special fields from the INI file to the special fields submitted from the form. If a special field is specified in your HTML form as well as in your INI file, the INI file takes precedence and the HTML form's special value is ignored.
Creating an INI file
You can create an INI file using any simple text editor. A program such as Windows Notepad is ideal, as is vi on Linux.
An INI file contains one or more sections. Each section contains a number (zero or more) of name-value pairs, one per line:
[section]
name1 = value1
name2 = value2Currently, FormMail uses the standard PHP function parse_ini_file to read the contents of your INI file. You can read the full details of parse_ini_file.
One downside of using this standard function is that, if you have a version of PHP earlier than version 5, you cannot include new lines (line breaks) in the values. For complex field definitions, such as conditions, this means they can be difficult to read because they must be defined on one long line.
FormMail accepts two sections in your INI file: email_addresses and special_fields. These sections are each described below.
Configuring FormMail to use your INI file
By default, FormMail does not use an INI file. You need to configure it to load your INI file.
In the configuration section of FormMail, you must provide the full pathname to your INI file in the setting called $FORM_INI_FILE:
$FORM_INI_FILE = "/path/to/formmail.ini";You can only have one INI file for FormMail. So, if you have multiple HTML forms and each needs its own special INI file, you must create multiple FormMail scripts.
To do this, just copy formmail.php to formmail-form1.php, formmail-form2.php, and so on. Each FormMail can have a different value for $FORM_INI_FILE, which is specific to the HTML form.
email_addresses Section
You can define names as email address aliases. The alias can be used instead of the email address. This means you can use an alias in your HTML form's recipients, cc, and bcc fields instead of using the email address. An alias can be used anywhere that FormMail is expecting and email address (including the value to the FromAddr option in mail_options). Here's an example...
In later versions of FormMail, we recommend you use the EMAIL_ADDRS configuration setting instead of an INI file for creating email address aliases. This is because it's easier to setup and use than creating an INI file. However, if you're creating an INI file for other reasons, then there's no difference in difficulty.
In the INI file you can have:
[email_addresses]
me = "russrobinson@tectite.com"then in the HTML form you can have:
<input type="hidden" name="recipients" value="me" />You can create any number of aliases in the email_addresses section and each alias can have any number of email addresses in its value. For example,
[email_addresses]
sales = "jack@yahoo.com,mary@my-sales-force.com,president@my-company.com"
me = "russrobinson@tectite.com"and in the form:
<input type="hidden" name="recipients" value="sales" />
<input type="hidden" name="mail_options" value="FromAddr=me" />special_fields Section
If you've already used FormMail, you'll be aware that it uses special fields (which are usually hidden form fields) from your HTML forms to tell it what you want done.
Instead of defining the special fields in your HTML form, you can define them in your INI file. This means you can keep your form validation and control secret, because it's not defined inside the HTML that any browser can show.
For example, here's another way to keep your email addresses secret:
[special_fields]
recipients = "russrobinson@tectite.com,jack@yahoo.com"In this example, we enforce entry of some fields (using required), and define how to write to a CSV file:
[special_fields]
required = "email,realname,Mesg"
csvfile = "contacts.csv"
csvcolumns = "email,realname,Mesg,Date,Time"Note that some special fields cannot be set in the INI file. Please refer to the Limitations section below.
A Complete Example
The following is a more complex example of an INI file:
[special_fields]
required = "EmailAddr,FirstName,LastName,Mesg"
csvfile = "contacts.csv"
csvcolumns = "EmailAddr,FirstName,LastName,Mesg,Date,Time"
[email_addresses]
sales = "jack@yahoo.com,mary@my-sales-force.com,president@my-company.com"Note that derive_fields cannot be placed in the INI file. This limitation may be removed in a later version of FormMail.
Remember that field definitions will need to be on one long line unless you have PHP version 5 or later.
Email Addresses
Prior to version 8.10 of FormMail, any email addresses you provided in your INI file would also need to be permitted for sending with FormMail's TARGET_EMAIL setting.
From version 8.10 onwards, FormMail automatically permits email addresses it finds in your INI file. This applies to addresses found in the [email_addresses] section and in the special fields recipients, cc, and bcc.
Protecting the INI File
If your INI file contains email addresses or other information you don't want visible from the Internet, you need to protect it from web access.
The easiest way to do this is to place it outside your website's Document Root. For example, the directory/folder immediately above your "public_html" or "www" directory/folder.
If you can't do this or there's some other reason to place it within the Document Root, and you use Apache Web Server Software, you can use a .htaccess file to protect your INI file.
First, use a browser to test if you can view your INI file:
http://www.yoursite.co/formmail.iniIf you cannot view your INI file this way, we recommend you ask your hosting provider why. You should be concerned that this might change without your knowledge in the future. That is, it's protected now, but might not be later.
If you can view your INI file, then add these lines to the .htaccess file for your Document Root:
<Files "formmail.ini">
Order Deny,Allow
Deny from all
Allow from none
</Files>Now test again with your browser. If you can no longer view your INI file, then it's protected!
You can also place your INI file below your Document Root (in a sub-directory/folder). In this case, you should be able to protect the entire sub-directory/folder from web access (using .htaccess).
Some hosting providers don't allow you to use .htaccess directives. In this case, contact your hosting provider and ask them how to protect your INI file on their servers.
If all else fails, you can use a unusual name for your INI file. If no one can guess the name of your INI file, then it's at least partially protected.
Try using a "dot name"
.formmail.iniThat might cause it to be automatically protected on your server.
Otherwise, invent something like this
84ms2198dm3.iniLimitations
PHP's parse_ini_file function does not have a documented size limit for values. This may mean there is no limit. If in doubt refer to the section on Debugging below.
Tectite FormMail uses the MAXSTRING configuration to limit the size of all fields, including fields loaded from the INI file. This logic will be altered in a future version, as it makes little sense to limit the size of fields loaded from an INI file.
Until then, ensure you set MAXSTRING to a value large enough for your fields, including special fields, and fields loaded from the INI file.
Certain special fields cannot be set in the INI file due to the order of processing. Fields that will be ignored from the INI file are:
- mail_options
- crm_options
- autorespond
- filter_options
- derive_fields
- file_names
- fields related to multi-page form processing
Some of these fields will be settable in the INI file in a future version of FormMail.
Debugging
You can tell FormMail to show you the contents of your INI file. In FormMail's configuration section, look for the setting called DB_SEE_INI and set it to true.
define("DB_SEE_INI",true); // set to true to just see the ini fileWhen this is true, FormMail will not take any action on your form submission other than to show you the contents of your INI file.
