gregwar / dsd
Formidable, the pragmatic forms library
Requires
- php: >=7.0
- gregwar/cache: ~1.0.9
- symfony/property-access: ~2.8.0
Requires (Dev)
- gregwar/captcha: ~1.1.6
- phpunit/phpunit: ^6.4
Suggests
- gregwar/captcha: To implement Captcha capability into forms
README
Formidable is a PHP library to handle forms. It parses an HTML form and allows you to manipulate it from your PHP code, and then render it.
How does it work?
Step 1: Download & install Formidable
Via composer:
{ "require": { "gregwar/formidable": "dev-master" } }
Or with a clone of the repository:
git clone https://github.com/Gregwar/Formidable.git
Or downloading it:
Step 2: Write your form in HTML
First, you have to write your code in HTML, for instance:
<!-- forms/example.html --> <form method="post"> Enter your name: <input type="text" name="name" /><br /> <input type="submit" /> </form>
Step 3: Give it to Formidable
In your PHP code, give your form to Formidable:
<?php session_start(); include('vendor/autoload.php'); // Formidable will parse the form and use it to check integrity // on the server-side $form = new Gregwar\Formidable\Form('forms/example.html'); $form->handle(function() { echo "Form OK!"; }, function($errors) { echo "Errors: <br/>"; foreach ($errors as $error) { echo "$error<br />"; } }); echo $form;
Simple, right?
Step 4: Enjoy the magic
You can then use the Formidable API to play with your form:
<?php // Will set the value of the field $form->name = "Bob"; // Will get the value of the field $name = $form->name; // Adds a constraint on the name $form->addConstraint('name', function($value) { if (strlen($value) < 10) { return 'Your name should be at least 10 characters!'; } }); // Adds a constraint on the whole form $form->addConstraint(function($form) { if ($form->getValue('pass1') != $form->getValue('pass2')) { return 'The passwords are different'; } });
You can also try to change your form and add constraint directly in the HTML code:
<input type="text" name="name" minlength="10" />
This will force the text to be at least 10 characters long when the server-side constraints will be checked.
Want a CAPTCHA to secure your form?
<input type="captcha" name="code" />
This will generate an image and an input field on the client-side, and use session on the server-side to check that the code is correct.
Note that this will use the dependency with Gregwar/Captcha library (you will have to install dependencies using composer).
Types
The following input types are supported:
input
tags, with types:text
number
ornumeric
, seemin
andmax
attributesint
orinteger
, seemin
andmax
attributesfile
checkbox
radio
hidden
password
captcha
, will automatically generate an imagedate
, will generate three selects, and return aDateTime
as datamultiradio
andmulticheckbox
(see the source section)
textarea
select
Attributes
Note that some attributes are not HTML-valid, like maxlength
:
<input type="text" name="name" maxlength="10" />
It will not be rendered in the HTML form, but will be used to check integrity.
Here is the list of available attributes:
minlength
: the minimum length of the valuemaxlength
: the maximum length of the valueregex
: the regexp that the value should respectmin
(for numbers): the minimum valuemax
(for numbers): the maximum valuerequired
: tell that the field is requiredreadonly
: the field is readonly and should not be modifiervalue
: the default value for the fieldmin-entries
: specify the minimum number of entries that you should provide for a multiple (see below)max-entries
: specify the maximum number of entries that you can provide for a multiple (see below)entries
: specify both minimum and maximum number of entries for a multiple (see below)
API
You can call these method on your $form
object:
posted()
: return true if the form was postedcheck()
: check the form and return an array of validity errorshandle($callback, $errorCallback)
, this shortcut method call posted and check(), and will call$callback
if the form is valid,$errorCallback
elsesetAttribute($field, $attr, $value)
: sets an extra attribute on a fieldgetAttribute($field, $attr)
: gets an extra attribute on a fieldsource($source, $values)
: feed a source (see the "Source" section)setPlaceholder($name, $value)
: sets a placeholder value (see below)addConstraint($field, $callback)
: adds a custom constraint on a field, thecallback
will be called with the field value and should return false if no problem, or an error string. If you just pass a closure to it, the closure will be called with the form passed as argument and can then do some tests involving multiple fields or form information.setValue($field, $value)
: set the value of a fieldgetValue($field)
: gets the value of a fieldsetValues(array $values)
: set the values for some fieldsgetValues()
: get the values of all fields
CSRF protection
An additional CSRF token is automatically inserted in the form and checked when it's submitted. Thus, all your forms will be secured.
The presence and validity of CSRF token is used to check that a form was
posted when calling posted
method (it's used internally in handle
)
If you specify the name
attribute in the form
, the CSRF token will be
different for this specific form, this will allow Formidable to make the
difference of which form is submitted if there is multiple form on the same
page.
Languages
The language for the errors can be set with setLanguage()
:
<?php // Will set the language to french for errors $form->setLanguage(new Gregwar\Formidable\Language\French);
Check that your language is supported in the Language
directory, don't hesitate
to participate!
Source
You can use the sourcing system to populate dynamically a select
, a multiradio
or
a multicheckbox
:
<input type="multicheckbox" name="colours" source="colours" />
Then populate it with source
:
<?php $form->source('colours', array('red', 'yellow', 'blue'));
This will be rendered by some checkboxes.
You can do it this way with select
:
<select name="colour"> <options source="colours" /> <option value="other">Other</option> </select>
And then source it with the same method
Creating form from string
You can create form from a file or from a string, this will be detected automatically:
<?php $form = new Gregwar\Formidable\Form('<form method="post"> <select name="colour"> <option value="blue">Blue</option> <option selected value="red">Red</option> <option value="green">Green</option> </select> </form>'); echo $form->getValue('colour') . "\n"; // red // Sets the color to blue $form->setValue('colour', 'blue'); echo $form; /* Will display: <form method="post"> <select name="colour" > <option selected="selected" value="blue">Blue</option> <option value="red">Red</option> <option value="green">Green</option> </select> <input type="hidden" name="posted_token" value="d293dc38017381b6086ff1a856c1e8fe43738c60" /> </form> */
Mapping
You can also use mapping
attribute to populate your form or to get back the form data in an array or
in an object, for instance:
<?php class Person { protected $name; public function getName() { return $this->name; } public function setName($name) { $this->name = $name; } } $person = new Person; $person->setName('Jack'); $form = new Gregwar\Formidable\Form('<form method="post"> <input type="text" name="name" mapping="name" /> </form>'); $form->setData($person); echo $form; /* Will output something like: <form method="post"> <input required="required" type="text" name="name" value="Jack" /> <input type="hidden" name="posted_token" value="aa27f437cc6127c244db14361fd614af51c79aac" /> </form> */
Note that the mapping uses the Symfony PropertyAccessor, you can then use accessor as in the example above to populate properties.
You can use:
getData($entity = array())
: populate and return entity with data populatedsetData($entity)
: populate the form with the entity attributes
Creating multiple sub-forms
You can add multiple sub-forms to a page using the <multiple>
tag:
<form method="post"> Film name: <input type="text" name="film_name" mapping="name" /> <h2>Actors</h2> <multiple name="actors" mapping="actors"> First name: <input name="first_name" mapping="firstName" /><br /> Last name: <input name="last_name" mapping="lastName" /><br /> </multiple> <input type="submit" /> </form>
With this, the <multiple>
can be used exactly like a field, but it will
contains an array of elements.
Some JS will be injected in the page and allow you to add/remove some elements.
You can use min-entries
and max-entries
constraint to set limits on the
number of entries in a multiple.
If you specify the same value for min-entries
and max-entries
, or specify
a value for entries
(which is actually an alias to do it), the number ofr inputs
will be fixed and no javascript will be required.
Adding dynamic data into the form
In some case, you'll want to add custom data into the form, there is two way to do this.
First way: using the placeholders
The {{ something }}
syntax allow you to simply inject data from the code, like this:
<?php $form = new Gregwar\Formidable\Form('<form method="post"> Hello {{ name }}! </form>'); $form->setPlaceholder('name', 'Bob'); echo $form;
In the example above, the {{ name }}
will be rendered as Bob
.
Note that placeholders may be used anyway excepted in the <form>
and input tags:
<?php $form = new Gregwar\Formidable\Form('<form method="post"> <span style="color:{{ color }}">Hello</span> </form>'); $form->setPlaceholder('color', 'red'); echo $form;
Second way: using PHP form
You can also write your form using PHP, like a template, for instance:
<form> <?php echo $label; ?>: <input type="text" name="name" /> <input type="submit" /> </form>
And then instanciate your form passing the template variables as a second argument:
<?php $form = new Gregwar\Formidable\Form('the-above-form.php', array('label' => 'Your name'));
The $label
will be interpreted using PHP.
Caching
For performances reasons, you may want to cache the parsed forms.
To do this, simply pass true
as the third argument of the constructor:
<?php /** * Parsed data for the form will be serialized and stored in a cache file, * if you use this form often, this will offer you better performances. */ $form = new Gregwar\Formidable\Form('form.html', null, true);
This will use the Gregwar/Cache system, you will need to get
the composer dependencies of this repository or install it manually. By default, cache files
will be wrote in the cache
directory from where the script is run.
Try to run the performances.php
script in the examples/
directory, this will give you an
example of performance gain with cache.
You can also pass an instance of Gregwar\Cache\Cache
as the third parameter, which will allow you
to set the cache directory.
License
Gregwar\Formidable
is under MIT License, have a look at the LICENSE
file for more information.
History
V2.0.0 End support for PHP <5.6
V2.1.0 Remove hard dependency on Captcha library