I have been working on developing a website with the newest PHP framework on the block — Fuel, which describes itself as “a simple, flexible, community driven PHP 5.3 web framework based on the best ideas of other frameworks with a fresh start”.

Initial progress with the framework was quite swift, as it takes the common MVC approach, something you will be familiar with if you know any decent frameworks, PHP or otherwise. Although Fuel is a new framework, it borrows a lot of ideas from two very popular PHP frameworks, CodeIgniter and CodeIgniter’s PHP5 fork Kohana (although it has since been rewritten in version three) and the core team; Dan Horrigan, who is lead developer, Phil Sturgeon, Harro Verton and Jelmer Schreuder; all work heavily within the CodeIgniter community.

However, there were a couple of times I came unstuck due to the lack of documentation. Good documentation is a major driving force behind any framework, something that CodeIgniter is superb with, and Kohana has been working on since the release of version three. Fuel is no different, there is some core documentation to get you started on common topics but currently it is lacking in a few areas — this is going to change very soon, currently Fuel is in beta, but with version one release candidate being released on April 1st documentation completion is a high priority for the official release date.

A side effect of a new framework is also the lack of blog articles documenting “how-tos”, which are often more useful than documentation. Phil Sturgeon has a couple of articles and a screencast and you might find some luck on Google, but I became frustrated when I wanted to know the best and framework way to implement a simple form with validation. Luckily, FuelPHP already has a good community and a few minutes on the IRC channel (#fuelphp on freenode) I was up and running. Below is my brief run through of what I did.

The HTML

Although there are magic methods to automatically create forms with validation already baked in to the framework, the missing documentation means that working it out for yourself is likely to be more hassle and stress than the reward you get. I like to be in tight control of my HTML, so the best solution was to combine HTML and form helpers. Although the form helpers aren’t yet documented, a quick look in to the code shows that they’re incredibly simple to use.

Below is an example email input (using the HTML5 email type), which uses the Form::input helper. The first argument is the name attribute, the second is the value — this is taken from the $validation class (set up in the controller, see below) — and finally an array of other attributes. $validation->errors is a method which outputs any error messages which have been set.

<div class="text email required">
    <label for="contact-email">Email <abbr title="Required">*</abbr></label>
    <?php echo Form::input('email', $validation->input('email'), array(
        'type'     => 'email',
        'id'       => 'contact-email',
        'required' => 'required'
    )); ?>
    <?php echo $validation->errors('email'); ?>
</div>

Form Validation

For any user generated content you should be validating the input, this is something which frameworks make incredibly easy to do. FuelPHP comes with a useful validation class.

You start by setting up the fields which need validating and their corresponding rules, which are chain-able. Example below for the email input.

$validation = \Validation::factory('contact');
$validation->add('email', 'Email')
    ->add_rule('required')
    ->add_rule('valid_email');

Optionally, you can set up custom error messages for each rule. For the email input validation rules, I used the following messages.

$validation->set_message('required', ':label is required.');
$validation->set_message('valid_email', ':label must be a valid email address');

To run the validation, simply do the following, adding success code within the if statement.

if($validation->run()) {
    // success, form is valid
}

Finally, assign the validation to the view.

$this->_view->validation = $validation;

Success Handling

Once you’ve got your form validated, you need to do something useful with the data and then redirect the user to avoid multiple POST requests. Usually you will be saving the information in to a database, so load up the correct model, assign the values and let the ORM save the object. Below is an example of how I save a basic contact form, this is within the success if statement defined above.

if($validation->run()) {
    $contact = new Model_Contact();
    $contact->name    = $validation->validated('name');
    $contact->email   = $validation->validated('email');
    $contact->message = $validation->validated('message');
    $contact->save();
}

Finally, redirect the user to a confirmation page.

Response::redirect('contact/confirmation');

input vs validated

The code documented above uses two methods on the $validation class to get the value of the POST request. They behave slightly differently, so it is useful to know the difference.

$validation->input is used in the view form helper and populates the form with the value the user typed.

$validation->validated returns a sanitised value that has been passed through all the validation rules. For example, if you use trim or strip_tags then the validated value will be trimmed with no HTML elements. Importantly, if you use valid_email and the user inputs an invalid email address, the validated value will be blank — this would be annoying and unexpected behaviour if used with the view form helper.