Configuration Files

Phorm™ v3.5.2

Configuration Files:

      You control Phorm's actions by means of a number of configuration variables. These are discussed throughout this document, and you can find a summary of them in Appendix B.

      Most programs of this type require you to set their variables by means of hidden fields or regular fields in the form. You can set Phorm's configuration variables this way, but this allows them to be seen by anyone viewing the document source, which may not be desirable.

      Phorm's variables can also be set in a configuration file. There are two types of configuration files; the first is the master configuration file phormconfig.php, and the other is a configuration file specified for the individual form. The file phormconfig.php is processed every time Phorm runs, and can be used to set configuration variables that are the same for all of your forms. After phormconfig.php is processed, the form-specific configuration file (if there is one) is processed. You would use it to set configuration variables that apply only to that form.

      To specify a configuration file for a form, use a hidden field:

   <INPUT TYPE=HIDDEN NAME="PHORM_CONFIG" VALUE="myconfig.php">

This form-specific configuration file is also sometimes called the "local" config file.

Config File Locations

Any path info will be stripped from $PHORM_CONFIG -- the file it names must be in the same directory as Phorm. For details on how to have configuration files in locations other than the directory Phorm is in, see the File Locations section.

File Names

A form-specific configuration file can be named anything you like, but I recommend the .php or .php3 extension for security purposes. If the file has a PHP-executable extension, the web server will pass it to the PHP parser rather than simply outputting it to the browser, and since your config files will usually contain just variable settings and no output, anyone snooping will see nothing.

Config File Format

A form-specific configuration file must be in the format of the phormconfig.php file included in the distribution; that is, it must begin with <?php and end with ?>, the variable names must have a dollar sign in front of them, non-numeric values must be in quotes, and each line must end with a semi-colon. The file must be readable by Phorm. On *nix systems, this means running Phorm under your user ID, or making the file world-readable. See Footnote 1 for details.

Master Config File

The master configuration file phormconfig.php is checked regardless of whether a local configuration file has been named; thus, if there are some settings that are the same for all your forms you could set them in phormconfig.php, and set the rest in the local configuration file for each form. Since phormconfig.php is processed first, any settings defined in it that are also defined in the form-specific configuration file will be overridden there. On the other hand, it is not necessary to have a phormconfig.php file at all.

Declaring $PHORM_ Variables

If you set any of the PHORM_ configuration variables in your HTML form, they must be explicitly declared in one of the configuration files. To declare a form variable in a configuration file, assign the value ph_DECLARE to it. For example, if you have the following in your form:

   Your Email address: <INPUT TYPE=TEXT NAME="PHORM_FROM">

then you need to have the following in your configuration file:

   $PHORM_FROM = ph_DECLARE;

Note that there is no $ sign or quotes around ph_DECLARE. Declaring variables applies only to PHORM_ configuration variables, and only if they are set in your HTML form. You do not need to declare any of the other fields from your form, and you do not need to declare $PHORM_ variables that are set in your configuration files. The reason for this is to make it difficult for someone else (such as a spammer) to abuse your installation of Phorm by passing bogus values to it. There are two exceptions to this: one is $PHORM_CONFIG, and the other is $PHORM_NAME, which is described in the File Locations section. These two variables always retain their values.

Requiring a Form-Specific Config File

The normal way to run Phorm is to have it named in the ACTION attribute of your FORM tag on an HTML form, as described above. However, if a visitor should happen to bookmark your acknowledgement page, thinking he or she could come back to it later, what they would really be bookmarking would be Phorm itself. When they return to the bookmark, Phorm would execute, but if you are using PHORM_CONFIG in a field on your form to name a form-specific configuration file, this would be bypassed, and Phorm needs to know what to do in this case. If Phorm starts up and discovers that $PHORM_CONFIG is not defined, the default action is to display the following message:

   I'm sorry, this page only processes the contents of a form.
   You cannot access it directly.

and then terminate. However, if you would rather have Phorm re-direct to a different URL in such a case, you can set $PHORM_URL. If you choose not to use form-specific configuration files, and instead have everything in phormconfig.php, you can tell Phorm not to require $PHORM_CONFIG to be set, by setting the variable $PHORM_RCONFIG to "N". This setting is very strict: it must be an upper-case "N". This is the only setting of $PHORM_RCONFIG. Setting it to "Y" or anything else is meaningless: if $PHORM_RCONFIG is not explicitly set to "N", Phorm will not execute without a local config file.

Note: the operation of $PHORM_RCONFIG is now the opposite of what it was before version 2.5.1. Before that, it was necessary to set $PHORM_RCONFIG to "Y".

0101000001101000011011110111001001101101010010010111001101000011011011110110111101101100