Static forms FormHandler library

Small library to validate simple html forms data and send requests to email. Furthermore you can write your own "handler" to process valid data, for example if you need to save it through API to a 3d-party service like Mailchimp, SalesForce, CRM system, etc.).

Why FormHandler

It's very easy to find some ready-to-use solution to process a contact form. Usually this is pure PHP script, which collect data and send email with php mail() function. It's not bad, but you can find numerous problems with such scripts:

• mail() function can be blocked on production server, because it's not secure. Also it's often goes to SPAM folder, when you use mail() function.
• You need to validate, that the data is valid. Manual validation of the $_POST array is time consuming and require knowledge of PHP, RegExp's, etc.

We decide to create small library, which fix all these issues, so to process a form you need:

• set validation rules with simple configuration array
• set your Mail settings (SMTP settings OR Mandrill API key)
• set your message params (From, To, Subject, Body template)

And that's it!

Requirements

• PHP 7.0+
• Composer
• Working SMTP server to send emails, or Mandrill account with configured mail domain.

Usage

Imagine you have simple html website with a contact form and you want to process it. We have name, email, and message form fields.
We will guide you through the whole process of creating PHP script to process a form request.

1. Init your environment

We suggest to create separate folder to place code into it. Let's call it form. File structure will looks like this:

|- /form/        # folder for our code
|- contact.php   # simple HTML page with a form

Inside /form/ folder we need to create composer.json file to set our library requirement:

{
    "require": {
        "justcoded/form-handler": "*"
    }
}

Now we need to download all required files with a composer, by running a bash command:

composer install

2. Entry file

You must create entry file, which will handle the form request. You can copy one of our examples examples/basic.php or examples/advanced.php inside package folder.

Let's call our file form.php and create it from scratch. It should be accessible from browser (for example: http://MY-DOMAIN.COM/form/form.php).

After that you need to include composer autoloader script and then set use part for library classes:

3. Form processing

Form processing idea is super easy. We have main FormHandler object, which will validate data and run some handler (right now we have only one Handler - email sender). And as the result we can get info about errors found during the whole process.

All this code is placed at the end of the form.php and looks like this:

4. Set Configurations

As you can see above we need to set 3 configuration arrays:

• $validationRules - defines validation rules and messages
• $mailerConfig - defines mailer component (PHPMailer or Mailchimp) and it's params
• $messageConfig - defines From/To/Body fields

4.1. Validation Rules

For validation we use popular Valitron PHP library. We use mapFieldsRules() method to set fields rules and labels() method to set field labels to show error messages correctly. So what you need to do is to set 'fields' and 'labels' keys in $validationRules array:

4.2. Mailer Config

There are two options for Mailer: PHPMailer and implementation of Mandrill API.

• PHPMailer is used to send through SMTP protocol or PHP mail() function.
• Mandrill API is used to send through Mandrill mail service using it's API.

Below you can find examples of configuration arrays for both methods:

4.3. Message configuration

The latest configuration you have to set is options for your email: From, To addresses; Subject and Body. Optional you can set CC and BCC headers as well.

Example:

For each address field you can set numerous emails in such format:

[ email1 => name1, email2 => name2, ... ]
OR
[email1, email2, email3 ...]

bodyTemplate and altBodyTemplate are paths to usual PHP template files, which will be used to generate email message (HTML and plain versions accordingly).

5. All together

If we combine all parts we can get file similar to this one:

In this example we write errors to cookies to be able to get them on the HTML page via JavaScript or PHP code.

6. Body templates

Templates are usual PHP files, which can print any PHP code you leave inside. However to make editing easier we added tokens support. So any keys, which are passed as data to FormHandler can be used as a token like this: {key}.

template-html.php example:

template-plain.php example:

Response formats

FormHandler can return response as ARRAY or as JSON. By default it return a JSON string. To change this behavior you need to add one more parameter to FormHandler object creation:

Once you get a response, you need to pass it to the page with a form to show errors. This can be done in several ways:

Pass response as JSON object

We recommend to send form request with AJAX request. In this case you will need single JSON object as server side response:

Pass response through COOKIES

If you use cookies - you can use JavaScript to display errors on the site and don't need PHP knowledge in this case.

Pass response through SESSION

In case you want to process errors with PHP code - then better option of passing errors is using a session:

Response array

In case of success

In case of errors:

File uploads and mail attachments

Form handler also supports File uploads and sending them as email attachments.

To add this feature you will need one more class, called FileManager:

After that you need to specify which files should be uploaded in $messageConfig:

input_file_name1, input_file_name2 are the name attributes of file inputs:

Of course each mail server has a limit of maximum attachments size. Usually it's not more than 10MB. To set this limit correctly you need to update $mailerConfig with additional option:

All attachments are uploaded to the specified directory and we recommend to add links to them inside body/alternativeBody templates. To print file link to a file you need to write a token with input file name. Like this:

If you need to validate your file with specific type or size you can use our custom "file" validator:

Multiple fields

Some forms may have multiple fields, like checkboxes, multiple selects or dynamically created inputs.

Example:

You can validate each input using wildcard field name inside *validation rules:

Same as file attachments you can use tokens to print all values at once. They will be comma separated.

Template usage:

Examples

You can check working examples inside examples folder of the package, start your investigate from index.php file (contains forms HTML). There you can find which files loaded next, when you submit forms.