INI Files

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.

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.

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 = value2

Currently, 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 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,

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.

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.

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.ini

If 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.

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:

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 file

When this is true, FormMail will not take any action on your form submission
other than to show you the contents of your INI file.

Email the webmaster (email to "webmaster at tectite dot com")
with questions or comments about this web site |
Email for information (email to "enquiries at tectite dot com")
about our products
By using our software or services you are agreeing to our standard
Terms and Conditions.