README

Model-driven form rendering and input validation.

Model-driven means it's driven by models - that means, step one is building a model that describes details of the rendered inputs on the form, and how the input gets validated.

Model-driven in this library does not mean "baked into your domain model", it means building a dedicated model describing aspects of form input/output.

Concepts

The library consists of the following types, with the following responsibilities:

Field classes describe the possible input elements on a form - what they are, what they look like, and how they behave; not their state.
InputModel contains the state of the form - the values in the input elements and any error-messages. This is a thin wrapper around raw $_GET or $_POST data, combined with error state - it can be serialized, which means you can safely store it in a session variable.
InputRenderer renders HTML elements (basic inputs, labels, etc.) and/or delegates more complex rendering to Field instances - it provides fields with an InputModel instance (form values and errors) at the time of rendering.
InputValidation manages the validation process by running validators against fields.
ValidatorInterface defines the interface of validator types, which implement validation logic for e.g. e-mail addresses, numbers, date/time, etc.

Most Field types are capable of producing some built-in validators - these can be created and checked by calling InputValidation::check(). For example, setting the $min_length property of a TextField will cause it to create a CheckMinLength validator.

This design is based on the idea that there are no overlapping concerns between form rendering and input validation - one is about output, the other is about input.

Assuming you use PRG, when the form is rendered initially, there is no user input, thus nothing to validate; if the form fails validation, the validation occurs during a POST request, and the actual form rendering occurs during a separate GET request. In other words, form rendering and validation never actually occur during the same request.

Usage

A basic form model might look like this:

class UserForm
{
    /** @var TextField */
    public $first_name;

    /** @var TextField */
    public $last_name;

    public function __construct()
    {
        $this->first_name = new TextField('first_name');
        $this->first_name->setLabel('First Name');
        $this->first_name->setRequired();

        $this->last_name = new TextField('last_name');
        $this->last_name->setLabel('Last Name');
        $this->last_name->setRequired();
    }
}

Use the model to render form inputs:

$form = new InputRenderer(@$_POST['user'], 'user');

$t = new UserForm();

?>
<form method="post">
    <?= $form->labelFor($t->first_name) . $form->render($t->first_name) . '<br/>' ?>
    <?= $form->labelFor($t->last_name) . $form->render($t->last_name) . '<br/>' ?>
    <input class="btn btn-lg btn-primary" type="submit" value="Save" />
</form>

Reuse the form model to validate user input:

$model = InputModel::create($_POST['user']);

$validator = new InputValidation($model);

$validator->check([$t->first_name, $t->last_name]);

if ($model->isValid()) {
    // no errors!
} else {
    var_dump($model->errors); // returns e.g. array("first_name" => "First Name is required")
}

Note that only one error is recorded per field - the first one encountered.

Once the input has passed validation, you can extract values from the individual fields:

$first_name = $form->first_name->getValue($model);
$last_name = $form->last_name->getValue($model);

To implement editing of existing data with a form, you can also inject state into the form model:

$form->first_name->setValue($model, "Rasmus");
$form->last_name->setValue($model, "Schultz");

Note that the getValue() and setValue() methods of every Field type are type-aware - for example, the IntField returns int, CheckboxField returns bool, and so on.

Only valid values of the appropriate types can be exchanged with Fields in this manner - if you need access to possiby-invalid, raw input-values, use the getInput() and setInput() methods of InputModel instead.

This demonstrates the most basic patterns - please see the demo for a working example of the post/redirect/get cycle and CSRF protection.

Other Features

This library has other expected and useful features, including:

Comes preconfigured with Bootstrap class-names as defaults, because, why not.
Adds class="has-error" to inputs that have an error message.
Adds class="is-required" to inputs that are required.
Creates name and id attributes, according to really simple rules, e.g. prefix/suffix, no name mangling or complicated conventions to learn.
Field titles get reused, e.g. between <label> tags and error messages, but you can also customize displayed names in error messages, if needed.
Default error messages can be localized/customized.
A basic error-summary can be generated with InputRenderer::errorSummary().

It deliberately does not implement any of the following:

Trivial elements: things like <form>, <fieldset> and <legend> - you don't need code to help you create these simple tags, just type them out; your templates will be easier to read and maintain.
Form layout: there are too many possible variations, and it's just HTML, which is really easy to do in the first place - it's not worthwhile.
A plugin architecture: you don't need one - just use everyday OO patterns to solve problems like a thrifty programmer. Extend the renderer and validator as needed for your business/project/module/scenario/model, etc.

This library is a tool, not a silver bullet - it does as little as possible, avoids inventing complex concepts that can describe every detail, and instead deals primarily with the repetitive/error-prone stuff, and gets out of your way when you need it to.

There is very little to learn, and nothing needs to fit into a "box" - there is little "architecture" here, no "plugins" or "extensions", mostly just simple OOP.

You can/should extend the form renderer with your application-specific input types, and more importantly, extend that into model/case-specific renderers - it's just one class, so apply your OOP skills for fun and profit!

Why input validation, as opposed to (domain) model validation?

Because domain validation is usually specific to a scenario - you might as well do it with simple if-statements in a controller or service, and then manually add errors to the validator.
Because input validation is simpler - it's just one class, and you can/should extend the class with case-specific validations, since you're often going to have validations that pertain to only one scenario/model/case. Bulding reusable domain validation rules as components would be a lot more complicated - many of these would be applicable to only on scenario/case and would never actually get reused, so they don't even benefit from this complexity.
There are simple scenarios in which a domain model isn't even useful, such as contact or comment forms, etc.

mindplay / kissform

Maintainers

Details

README

Concepts

Usage

Other Features

Why input validation, as opposed to (domain) model validation?