rkr/forms

dev-master 2020-08-10 20:39 UTC

This package is auto-updated.

Last update: 2024-10-11 05:53:46 UTC


README

Build Status

Introduction

There are many php based form classes out there. I have used many of them and visited even more before I decided to develop my own approach. So this project is based on some experience and covers mostly my own needs.

Installation

composer require rkr/forms

Example

First Render

We first have to create a structure that will later represent our form, and subsequently convert the entered data and perform the validation:

use Forms\Form;

$section = new Form\Section('Section', ['xyz' => 123],
    new Form\Checkbox(['data', 'active'], 'Active'),
    new Form\Input(['data', 'name'], 'Name', ['required' => true, 'minlenght' => 5, 'maxlength' => 64]),
    new Form\Email(['data', 'email'], 'Email')
);

Then we can create a data structure from the structure:

$structure = $section->render([], false);
print_r(json_encode($structure, JSON_PRETTY_PRINT));
{
    "type": "section",
    "elements": [{
        "name": ["data", "active"],
        "title": "Active",
        "value": null,
        "messages": [],
        "attributes": [],
        "type": "checkbox"
    }, {
        "name": ["data", "name"],
        "title": "Name",
        "value": null,
        "messages": [],
        "attributes": {
            "required": true,
            "minlenght": 5,
            "maxlength": 64
        },
        "type": "input"
    }, {
        "name": ["data", "email"],
        "title": "Email",
        "value": null,
        "messages": [],
        "attributes": [
            "required": true
        ],
        "type": "email"
    }],
    "attributes": {"xyz": 123},
    "title": "Section"
}

If we already have data, then this data is included in the generated data structure. That's it for the first step, actually. The output can now be made with any template engine. I mainly use PHP and Twig in my projects, but any template engine can be used.

Conversion

Instructions follow...

Validation and second Render

Instructions follow...

Zen of Forms

  • It should be easy to reason about data
  • Building forms should be as intuitive as possible
  • Forms should be built using declarative data and user defined templates
  • Ability to replace existing components and build your own
  • I18N and L10N is crucial
  • Need as few external dependencies as possible
  • PHP-Code must be statically clean

TODO

  • Tested base components

  • Handling for I18N and L10N

  • Usage example

  • Every component must not change internal state by design by calling convert, validate or render, after the component was initialized.