PHP library to create and validate html forms

Oscar Otero

Last update: Sep 20, 2022

Related tags

Miscellaneous forms form-builder

Overview

FormManager

Note: this is the documentation of FormManager 6.x

For v5.x version Click here

Installation:

This package requires PHP>=7.1 and is available on Packagist:

composer require form-manager/form-manager

Create a field

FormManager is namespaced, but you only need to import a single class into your context:

use FormManager\Factory as F;

Use the imported factory to create all form elements:

'name-field']); //Add or remove attributes $name->setAttribute('title', 'This is the name input'); $name->removeAttribute('class'); $name->setAttributes([ 'required', 'readonly', 'tabindex' => 2, 'maxlength' => 50 ]); //Set the value $name->setValue('MyName'); //Use magic properties to get/set/remove attributes $name->class = 'name-field'; $name->required = false; unset($name->readonly); ">

//Create an input type="text" element
$name = F::text();

//Create the input with a label
$name = F::text('Please, introduce your name');

//Or with extra attributes
$name = F::text('Please, introduce your name', ['class' => 'name-field']);

//Add or remove attributes
$name->setAttribute('title', 'This is the name input');
$name->removeAttribute('class');
$name->setAttributes([
    'required',
    'readonly',
    'tabindex' => 2,
    'maxlength' => 50
]);

//Set the value
$name->setValue('MyName');

//Use magic properties to get/set/remove attributes
$name->class = 'name-field';
$name->required = false;
unset($name->readonly);

List of all available inputs:

All HTML5 field types are supported:

F::checkbox($label, $attributes)
F::color($label, $attributes)
F::date($label, $attributes)
F::datetimeLocal($label, $attributes)
F::email($label, $attributes)
F::file($label, $attributes)
F::hidden($value, $attributes)
F::month($label, $attributes)
F::number($label, $attributes)
F::password($label, $attributes)
F::radio($label, $attributes)
F::range($label, $attributes)
F::search($label, $attributes)
F::select($label, $options, $attributes)
F::submit($label, $attributes)
F::tel($label, $attributes)
F::text($label, $attributes)
F::textarea($label, $attributes)
F::time($label, $attributes)
F::url($label, $attributes)
F::week($label, $attributes)

Note that all inputs accepts the same arguments except hidden and select.

Validation

This library uses internally symfony/validation to perform basic html5 validations and error reporting. HTML5 validation attributes like required, maxlength, minlength, pattern, etc are supported, in addition to intrinsic validations assigned to each input like email, url, date, etc.

$email = F::email();

$email->setValue('invalid-email');

//Validate the value
if ($email->isValid()) {
    return true;
}

//Get errors
$error = $email->getError();

//Print the first error message
echo $error;

//Iterate through all messages
foreach ($error as $err) {
    echo $err->getMessage();
}

//You can also customize/translate the error messages
$email->setErrorMessages([
    'email' => 'The email is not valid',
    'required' => 'The email is required',
    'maxlength' => 'The email is too long, it must have {{ limit }} characters or less',
]);

//And add more symfony validators
$ip = F::text();
$ip->addConstraint(new Constraints\Ip());

See all constraints supported by symfony

Render html

$name = F::text('What is your name?', ['name' => 'name']);

echo $name;

What is your name? ">

<label for="id-input-1">What is your name?label> <input id="id-input-1" type="text" name="name">

Set a custom template using {{ label }} and {{ input }} placeholders:

'); echo $name; ">

$name->setTemplate('{{ label }} {{ input }}
');
echo $name;

What is your name?

<label for="id-input-1">What is your name?label> <div class="input-content"><input id="id-input-1" type="text" name="name">div>

If you want to wrap the previous template in a custom html, use the {{ template }} placeholder:

$name->setTemplate('{{ template }}
');
echo $name;

What is your name?

<fieldset><label for="id-input-1">What is your name?label> <div class="input-content"><input id="id-input-1" type="text" name="name">div>fieldset>

Grouping fields

Group the fields to follow a specific data structure:

Group

Groups allow to place a set of inputs under an specific name:

$group = F::group([
    'name' => F::text('Username'),
    'email' => F::email('Email'),
    'password' => F::password('Password'),
]);

$group->setValue([
    'name' => 'oscar',
    'email' => '[email protected]',
    'password' => 'supersecret',
]);

Radio group

Special case for radios where all inputs share the same name with different values:

$radios = F::radioGroup([
    'red' => 'Red',
    'blue' => 'Blue',
    'green' => 'Green',
]);

$radios->setValue('blue');

Submit group

Special case to group several submit buttons under the same name but different values:

$buttons = F::submitGroup([
    'save' => 'Save the row',
    'duplicate' => 'Save as new row',
]);

$buttons->setName('action');

Group collection

Is a collection of values using the same group:

$groupCollection = F::groupCollection(
    f::group([
        'name' => F::text('Name'),
        'genre' => F::radioGroup([
            'm' => 'Male',
            'f' => 'Female',
            'o' => 'Other',
        ]),
    ])
]);

$groupCollection->setValue([
    [
        'name' => 'Oscar',
        'genre' => 'm'
    ],[
        'name' => 'Laura',
        'genre' => 'f'
    ],
])

Multiple group collection

Is a collection of values using various groups, using the field type to identify which group is used by each row:

$multipleGroupCollection = F::multipleGroupCollection(
    'text' => f::group([
        'type' => F::hidden(),
        'title' => F::text('Title'),
        'text' => F::textarea('Body'),
    ]),
    'image' => f::group([
        'type' => F::hidden(),
        'file' => F::file('Image file'),
        'alt' => F::text('Alt text'),
        'text' => F::textarea('Caption'),
    ]),
    'link' => f::group([
        'type' => F::hidden(),
        'text' => F::text('Link text'),
        'href' => F::url('Url'),
        'target' => F::select([
            '_blank' => 'New window',
            '_self' => 'The same window',
        ]),
    ]),
]);

$multipleGroupCollection->setValue([
    [
        'type' => 'text',
        'title' => 'Welcome to my page',
        'text' => 'I hope you like it',
    ],[
        'type' => 'image',
        'file' => 'avatar.jpg',
        'alt' => 'Image of mine',
        'text' => 'This is my photo',
    ],[
        'type' => 'link',
        'text' => 'Go to my webpage',
        'href' => 'https://oscarotero.com',
        'target' => '_self',
    ],
]);

Datalist

Datalist are also allowed, just use the createDatalist() method:

$input = F::search();

$datalist = $input->createDatalist([
    'female' => 'Female',
    'male' => 'Male'
]);

echo $input;
echo $datalist;

Forms

We need a form to put all this things together.

{$input}

"; } echo $loginForm->getClosingTag(); ">

$loginForm = F::form([
    'username' => F::text('User name'),
    'password' => F::password('Password'),
    '' => F::submit('Login'),
]);

$loginForm->setAttributes([
    'action' => 'login.php',
    'method' => 'post',
]);

//Load data from globals $_GET, $_POST, $_FILES
$loginForm->loadFromGlobals();

//Load data passing the arrays
$loginForm->loadFromArrays($_GET, $_POST, $_FILES);

//Or load from PSR-7 server request
$loginForm->loadFromServerRequest($serverRequest);

//Get loaded data
$data = $loginForm->getValue();

//Print the form
echo $loginForm;

//Access to specific inputs:
echo $loginForm->getOpeningTag();
echo 'Login:
';

echo $loginForm['username'];
echo '
';
echo $loginForm['password'];
echo '
';
echo $loginForm[''];
echo $loginForm->getClosingTag();

//Iterate with all inputs
echo $loginForm->getOpeningTag();
echo 'Login:
';

foreach ($loginForm as $input) {
    echo "{$input}
";
}
echo $loginForm->getClosingTag();

Comments

6.1.0 version break compatibility with Select optgroups handling
In version 6.0.1 if you have in form:

F::select( 'TestSelect', [ 'Group1' => ['1' => 'one', '2' => 'two' ], 'Group2' => ['1' => 'one', '2' => 'two' ], 'Group3' => ['1' => 'one', '2' => 'two' ] ] ,[ 'id' => 'county', 'multiple' => 'multiple', 'class' => 'select2' ] ),

you will got select with optgroups like:

But in version 6.1 there was no any erros, but select will look like (got only groups):

If such breaking chenge made intentionally there should be check and exception with hint how developer must adjust their code. But really it is is bug on my mind. There was no any deprecation in Select interface, so breaking change should not be happened in stable versions (e.g. 6.*).
opened by Hubbitus 7
fix array normalizing

in case when Select::val($value) $value is not integer or string, eg bool : Select::applyValues(array $value) will not apply old normalize method, array_flip() will raise warning

opened by andrdru 7
Examples System

I've added the basis for being able to easily show example of using FormManager alongside their PHP and HTML output.

To add an example simple create a file in the examples/example directory with a short example at the top, and the form code below.

To really see the examples it's best to be able to run the code, I've hosted a copy of the examples here:

http://pata.cat/tools/form-manager/examples/index.php

which should be online for the foreseeable future. but anybody is welcome to host a new copy (or perhaps setup a git-pages).

Feel free to suggest better ways to achieve any of these examples.

opened by Patabugen 6

Field::duplicate error

If I try to add a duplicate field (as per the example in the docs):

'friends' => Field::duplicate([
    'name' => Field::text()->label('Name'),
    'email' => Field::email()->label('email'),
    'age' => Field::number()->label('Age')
])->addDuplicate(),

I get this error:

PHP 3. FormManager\\Fields\\Duplicable->add() /var/www/html/fmtest2/index.php:37
PHP 4. FormManager\\Fields\\Collection->add() /var/www/html/fmtest2/vendor/form-manager/form-manager/src/Fields/Duplicable.php:27
PHP Fatal error: Call to a member function addDuplicate() on a non-object in /var/www/html/fmtest2/index.php on line 41

opened by m1 6

Add Group without prefixing the name
Hey,

I'd like to be able to add FormGroups but have the FormManager not put fields in those groups into arrays.

For example:

<?php $fieldContainer = \FormManager\Builder::group(); $fieldContainer->add($arrayOfFields); $form->add( [ $someKey => $fieldContainer ] );

I'm trying to use groups for visual separating decoration and I'm adding a $fieldContainer->render() function to do that.

Perhaps a fix would be to not group the field names if the keys are numeric, and not defined?
opened by Patabugen 5
How to get "name" attribute

Before version 4.3, I could get the name attribute using $input->attr('name') because name is a tag attribute, but now returns null.

There are a new method to get the input name?

opened by eusonlito 4
Message error
Hi,

How can I redefine an error message?

FormManager\Inputs\Email::$error_message = "foo";

I'm not sure that's correct...

And, other question, can you add a CSRF token?
opened by TonyLight 4

The attribute "name" is read only!

How can I create a new Input and assign him a name without add function?

Using README example I can't:

//Create an input type="text" element
$name = F::text();

//Use the jQuery syntax to set/get/remove attributes:
$name->attr('name', 'username');

InvalidArgumentException in InputTrait.php line 107:
The attribute "name" is read only!

Thanks.

opened by eusonlito 3

How I can clear previous "select" options
I need to clear the current options with new options (differents). How can I do it?

There are some empty method like jQuery?

My example:

$form['states_id']->options([1 => 'aaaa']); ... very long process ... $form['states_id']->options([2 => 'bbbb']);

After last step, $form['status_id'] has first and second assignment, but I need to clear first options without define again or other field redefinitions. Something like:

$form['states_id']->options([1 => 'aaaa']); ... very long process ... $form['states_id']->empty()->options([2 => 'bbbb']);

Thanks :)
opened by eusonlito 3

Default values are lost after load call

I have this definition:

$form = new FormManager\Containers\Form;

$form->add([
    'action' => F::hidden()->val('edit'),
    'id' => F::hidden()
]);

Then, I load a default value to id:

$form->load(['id' => 1]);

After that, I lost action value:

var_dump($form['action']);

Hidden {#183 ▼
  +input: Input {#184 ▼
    #name: "input"
    #parent: Form {#180 ▶}
    #close: null
    #attributes: array:2 [▼
      "type" => "hidden"
      "value" => ""
    ]
    #data: []
    #vars: []
    #html: null
    #sanitizer: null
    #validators: []
    #error: null
    #key: "action"
  }
  #labelPosition: 0
  #render: null
  #rendering: false
}

opened by eusonlito 3

Select input value issue
Thanks for the great library.

I came across an issue where I had the following options in my select

'' => ' -- Any --', '0' => 'Studio', '1' => '1 Bedroom', '2' => '2 Bedrooms',

Unfortunately because php treats '' == 0 as true, both of the top two options are treated as selected.

I've updated the comparison to $val === $value to fix this issue.
opened by davidrushton 3

FR: Please add {{id}} placeholder in template

Said I have form:

	$filterRealtyTypeTemplate = '<li>{{ input }}{{ label }}</li>';

	$form = F::form([
		'filter_realty_type' => F::radioGroup(
			[
				'residential'	=> F::radio('Residential real estate')->setTemplate($filterRealtyTypeTemplate)
				,'rural'	=> F::radio('Rural properties')->setTemplate($filterRealtyTypeTemplate)
				,'commercial'	=> F::radio('Commercial real estate')->setTemplate($filterRealtyTypeTemplate)
			]
		)
        )

And I would like access values residential, rural and so on in my template like:

$filterRealtyTypeTemplate = '<li><a href="#tab_realty_type_{{ id }}">{{ input }}{{ label }}</a></li>';

In my case for use with jQuery tabs plugin, but I think it would be helpfull in other cases too.

Change seams trivial like do in Input.php:

    public function __toString()
    {
        if ($this->label) {
            return strtr($this->template, [
                '{{ label }}' => (string) $this->label,
                '{{ input }}' => parent::__toString(),
                '{{ id }}' => $this->getAttribute('value') // !!!
            ]);
        }

        return parent::__toString();
    }

If you wish I could prepare PR.

P.S. Is it possible to provide the template for all radio objects once at radioGroup level?

opened by Hubbitus 3

Fix PHPStan Level 5 problems

@oscarotero This is all I could do.

The last one on Level 5 may be a Symfony problem

 ------ ----------------------------------------------------------------------------------------------------------
  Line   ValidationError.php
 ------ ----------------------------------------------------------------------------------------------------------
  43     Call to an undefined method Symfony\Component\Validator\ConstraintViolationListInterface::getIterator().
 ------ ----------------------------------------------------------------------------------------------------------

opened by szepeviktor 1

Use Symfony File constraints

Hi,

I tried to add a maxSize constraint from Symfony on a file input. Turns out it's not working because Symfony expect a Symfony\Component\HttpFoundation\File\File object.

Is there any way to make file constraints work? If not, that would probably deserves a mention in the docs.

opened by nlemoine 2

Releases(v6.1.2)

v6.1.2(Jul 19, 2021)

See CHANGELOG
Source code(tar.gz)
Source code(zip)
v6.1.1(Jan 13, 2021)

See CHANGELOG
Source code(tar.gz)
Source code(zip)
v6.1.0(Nov 14, 2020)

See CHANGELOG
Source code(tar.gz)
Source code(zip)
v6.0.1(Mar 24, 2019)

See CHANGELOG
Source code(tar.gz)
Source code(zip)
v6.0.0(Dec 24, 2018)

New version fully rewritten with a lot of breaking changes. See CHANGELOG
Source code(tar.gz)
Source code(zip)
v5.1.3(Sep 27, 2017)

Fixed select with attributes multiple and required #74 #75
Source code(tar.gz)
Source code(zip)
v5.1.2(May 11, 2017)

Validate file extensions from accept attribute #70
Source code(tar.gz)
Source code(zip)
v5.1.1(Sep 27, 2016)

Fixed the attribute name if the attribute multiple is set, adding a [] at the end. (ex: name="authors[]" instead name="authors")
Source code(tar.gz)
Source code(zip)

v5.1.0(Sep 12, 2016)

Added labelAttr and wrapperAttr methods to allow to add attributes to these properties chaining the fields:

$form = F::form([
    'name' => F::text()
        ->label('Your name')
        ->labelAttr(['class' => 'field-label'])
        ->wrapperAttr(['class' => 'field-row'])
]);

//This is the same than
$form['name']->label->attr(['class' => 'field-label']);
$form['name']->wrapper->attr(['class' => 'field-label']);

Source code(tar.gz)
Source code(zip)

v5.0.4(Jun 28, 2016)

Removed the <div> wrapping hidden inputs.
Source code(tar.gz)
Source code(zip)
v5.0.3(May 18, 2016)
Fixed name losing issue #61

Fixed validators of children elements not being executed

Source code(tar.gz)
Source code(zip)
v5.0.2(May 11, 2016)
Fixed select attributes

Ignored tests and development files on export

Source code(tar.gz)
Source code(zip)
v5.0.1(May 4, 2016)
Fixed Range field

Source code(tar.gz)
Source code(zip)
v5.0(May 4, 2016)
Breaking changes:

Renamed $field->isValid() to $field->validate().

Removed the distinction between Fields and Containers. Now all elements are Fields.

Added a wrapper (<div>) to all fields.

Changed the locales of some validators.

Source code(tar.gz)
Source code(zip)
v4.7.3(Apr 14, 2016)

Fixed select containing options with values like "000", "001", etc... #60
Source code(tar.gz)
Source code(zip)
v4.7.2(Oct 6, 2015)
Fixed checkboxes loading the value 0

Source code(tar.gz)
Source code(zip)
v4.7.1(Oct 6, 2015)
Fixed min attribute with the value ""

Fixed checkboxes with the value 0

Number/Range inputs returns integer/float values instead strings

Source code(tar.gz)
Source code(zip)

4.7.0(Aug 12, 2015)

The builder is instantiable. Example:

use FormManager\Builder as F;
use FormManager\Factory;

//Static mode:
$text = F::text();

//Object oriented mode:
$f = new F(new Factory());

$text = $f->text();

Source code(tar.gz)
Source code(zip)

v4.6.2(Jul 12, 2015)

$input->error() no longer execute $input->validate() automatically. This prevent display required inputs with errors on empty form
Source code(tar.gz)
Source code(zip)
v4.6.1(Jul 12, 2015)

Bug fixes, renamed some classes/interfaces/traits, etc
Source code(tar.gz)
Source code(zip)

v4.6.0(Jul 8, 2015)

Added support for datalist elements #58

Example:

$text = F::text()
    ->label('Your favorite colour')
    ->datalist([
        'red' => 'Red',
        'blue' => 'Blue'
    ]);

Source code(tar.gz)
Source code(zip)

v4.5.0(Jun 16, 2015)

Added support for PSR-7. Now you can load the values with the new method loadFromPsr7():

$form->loadFromPsr7($serverRequestInstance);

Added support for fieldsets in forms. This fixes #56

$form = F::form()->fieldsets([
    'fieldset-1' => [
        'name' => F::text()->label('Name'),
        'surname' => F::text()->label('Surname')
    ]
]);

//You can access to the fields in the same way:
echo $form['name'];

//But also get the fields grouped:
foreach ($form->fieldsets() as $fieldset) {
    echo $fieldset;
}

Source code(tar.gz)
Source code(zip)

v4.4.0(May 30, 2015)
The label and errorLabel of fields are always available but only will be printed if they have any content. This allows to configure the label and errorLabel in a more flexible way (#53). Example:

$input->errorLabel->addClass('my-custom-error-class');

Improved accesibility adding some aria-* attributes #54

Added support for optgroup in selects #55 . Usage example:

$select->optgroups(); //returns all opgroups $select->optgroups([ 'odd' => [ //opgroup label 1 => 'One' //options inside this optgroup 3 => 'Three' ], 'even' => [ 2 => 'Two' 4 => 'Four' ] ]);

Source code(tar.gz)
Source code(zip)
v4.3.9(May 23, 2015)

Builder::addFactory() accepts FactoryInterface instead Factory (#52)
Source code(tar.gz)
Source code(zip)
v4.3.8(May 19, 2015)
Fixed data-* attributes with boolean values.

Added a directory with examples (thanks @Patabugen )

Source code(tar.gz)
Source code(zip)
v4.3.7(May 13, 2015)

On load strings such "0", the value returned is "". Fixed that.
Source code(tar.gz)
Source code(zip)
v4.3.6(May 8, 2015)
Fixed modified variables using an array

Source code(tar.gz)
Source code(zip)
v4.3.5(Apr 30, 2015)

Fixed select with attribute multiple on load empty values #47
Source code(tar.gz)
Source code(zip)
v4.3.4(Apr 18, 2015)
The name attribute of an input is writtable if it has not parents #46

Source code(tar.gz)
Source code(zip)
v4.3.3(Apr 16, 2015)
New method clear() to delete the children of an element. #45

Source code(tar.gz)
Source code(zip)