PHPackages                             helmut/forms - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. helmut/forms

ActiveLibrary[Templating & Views](/categories/templating)

helmut/forms
============

A customisable and testable form abstraction library.

v1.1.8(9y ago)019MITPHPPHP >=5.5.0

Since Jan 18Pushed 8y ago1 watchersCompare

[ Source](https://github.com/helmut/forms)[ Packagist](https://packagist.org/packages/helmut/forms)[ RSS](/packages/helmut-forms/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (2)Dependencies (5)Versions (4)Used By (0)

Helmut\\Forms
=============

[](#helmutforms)

[![Build Status](https://camo.githubusercontent.com/9ace64f392f5def9f5054ae35f3577dbbd045a6e1311bc73b45679429c17b928/68747470733a2f2f6170692e7472617669732d63692e6f72672f68656c6d75742f666f726d732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/helmut/forms)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/708c2720abe5c14e14ed403d57d37825f9a24e12daabaf52d1a2941282f606f8/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f68656c6d75742f666f726d732f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/helmut/forms/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/fd2561ce3231efbacd5d56af920e19101c8d606a45b999f10dc1336aa58d7ded/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f68656c6d75742f666f726d732f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/helmut/forms/?branch=master)[![Software License](https://camo.githubusercontent.com/074b89bca64d3edc93a1db6c7e3b1636b874540ba91d66367c0e5e354c56d0ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e737667)](LICENSE)

A customisable and testable form abstraction library. Think of it as a request model on steroids. We all handle forms in different ways. Forms reduces the complexity and allows you focus on design. Use the included default fields, or build up your own library of reusable and testable fields, and drop them into every application you build.

- Makes forms testable
- Abstracts the request not the html
- Provides a model for reusing field components
- Design fields exactly the same way you normally would
- Render using mustache, twig, or blade
- Built in validation

Documentation
-------------

[](#documentation)

- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Field Types](#field-types)
    - [Button](#button)
    - [Text](#text)
    - [Name](#user-content-name)
    - [Email](#email)
    - [Number](#number)
    - [Password](#password)
    - [Paragraph Text](#paragraph_text)
    - [Checkbox](#checkbox)
    - [Checkboxes](#checkboxes)
    - [Dropdown](#dropdown)
    - [Search](#search)
- [Customisation](#customisation)
- [Templates](#templates)
- [Language](#language)
- [Plugins](#plugins)
- [Autoloading](#autoloading)
- [Security](#security)
- [License](#license)

Installation
------------

[](#installation)

To get the latest version of Forms, simply require the project using [Composer](https://getcomposer.org):

```
$ composer require helmut/forms
```

Instead, you may of course manually update your require block and run `composer update` if you so choose:

```
{
    "require": {
        "helmut/forms": "~1.0"
    }
}
```

If you are using [Laravel](https://laravel.com) you need to register the service provider. Open up `config/app.php` and add the `Helmut\Forms\Providers\Laravel::class` key to the `providers` array.

Usage
-----

[](#usage)

#### Step 1

[](#step-1)

Create a class that extends `\Helmut\Forms\Form`.

```
// File: app/Forms/Form.php

namespace App\Forms;

class Form extends \Helmut\Forms\Form {

}
```

#### Step 2

[](#step-2)

Now you can create a form.

```
$form = new \App\Forms\Form;
```

Or in Laravel, simply type hint route or controller methods.

```
// File: app/Http/routes.php

Route::any('/', function(\App\Forms\Form $form) {

	// Now you can access $form

});
```

#### Step 2

[](#step-2-1)

Define fields to build the form.

```
$form->email('email')->label('Email Address')->required();
$form->password('password')->label('Password')->required();
$form->checkbox('remember')->label('Remember me');
$form->button('login')->label('Sign In');
```

Or alternatively you can create a class just for this specific form that extends `\App\Forms\Form`. Then fields can be defined within a `define` method and they will be added automatically.

```
// File: app/Forms/Login.php

namespace App\Forms;

class Login extends Form {

	public function define()
	{
		$this->email('email')->label('Email Address')->required();
		$this->password('password')->label('Password')->required();
		$this->checkbox('remember')->label('Remember me');
		$this->button('login')->label('Sign In');
	}

}
```

#### Step 4

[](#step-4)

You can now render the form and handle submissions.

```
$form = new \App\Forms\Login;

if ($form->completed()) {

	// The form has been submitted and passed validation
}

echo $form->render();
```

Or in Laravel:

```
// File: app/Http/Controllers/LoginController.php

class LoginController extends Controller {

    public function handleLoginForm(\App\Forms\Login $form)
    {
    	if ($form->completed()) {

			// The form has been submitted and passed validation

        }

        return view('login.form', compact('form'));
    }

}
```

```
// File: resources/views/login/form.blade.php

@extends('template')

@section('content')

	Sign In

    {!! $form !!}

@endsection

```

#### Step 6

[](#step-6)

Check out the form!

[![login](https://cloud.githubusercontent.com/assets/219623/12343804/fd2186e6-bb71-11e5-94fe-2387833554e8.png)](https://cloud.githubusercontent.com/assets/219623/12343804/fd2186e6-bb71-11e5-94fe-2387833554e8.png)

API Reference
-------------

[](#api-reference)

These methods allow you to interact with your form:

```
	// Fields

	$form->button('register')					// Create a button
	$form->text('foo')							// Create a text field
	$form->name('foo')							// Create a name field
	$form->email('foo')							// Create an email field
	$form->number('foo')						// Create a numeric field
	$form->password('foo')						// Create a password field
	$form->paragraph_text('foo')				// Create paragraph text field
	$form->checkbox('foo')						// Create a checkbox field
	$form->checkboxes('foo')					// Create checkboxes field
	$form->dropdown('foo')						// Create dropdown field
	$form->search('foo')						// Create a search box field

	// Applying Modifiers

	$form->text('foo')->required()				// Make a field required
	$form->text('foo')->default('bar')			// Set a default value
	$form->checkbox('foo')->checked()			// Make it checked
	$form->checkbox('foo')->unchecked()			// Make it unchecked
	$form->dropdown('foo')->options([...])		// Add dropdown options

	// Pre-Filling

	$form->defaults($array)						// Load defaults from an array
	$form->defaults($user, $company, ...)		// Load defaults from model/s

	// Rendering

	$form->render() 							// Generate form
	$form->render('flat') 						// Generate form using flat templates

	// Processing

	$form->valid() 								// Validate the form
	$form->valid('name') 						// Validate a specific field
	$form->invalid()
	$form->invalid('name')
	$form->submitted() 							// Check if the form has been submitted
	$form->submitted('register') 				// Check if submitted using a specific button
	$form->completed() 							// Check if submitted and valid

	// Retrieving Values

	$form->all() 								// Get all the values
	$form->get('foo') 							// Get the foo field values
	$form->get('foo', 'bar') 					// Get the foo[bar] field value

	// Filling Models

	$form->fill($user) 							// Fills all fields in user model
	$form->fill($user, 'name')	 				// Fills just the name fields
	$form->fill($user, ['name', 'email'])	 	// Fills just the name and email fields
```

Field Types
-----------

[](#field-types)

These field types have been included by default:

### button

[](#button)

```
$form->button('foo')->label('Foo')
$form->submitted('foo') // Returns true if form was submitted using this button
$form->completed('foo') // Returns true if form both submitted and valid
```

**Example:**

`$form->button('signup')->label('Sign Up');`

[![button](https://cloud.githubusercontent.com/assets/219623/12344315/dc723b98-bb76-11e5-98bc-c74a7a63a88b.png)](https://cloud.githubusercontent.com/assets/219623/12344315/dc723b98-bb76-11e5-98bc-c74a7a63a88b.png)

---

### text

[](#text)

```
$form->text('foo')->label('Foo')->default('bar')->required()
$form->get('foo') // Returns 'bar'
```

Validations: `between(min, max)`, `min(num)`, `max(num)`, `alpha`, `alpha_num`, `alpha_dash`, `in(array)`, `not_in(array)`

**Example:**

`$form->text('address')->label('Address')->required();`

[![text](https://cloud.githubusercontent.com/assets/219623/12344320/e7bdb630-bb76-11e5-8ab4-7c43b3a5d680.png)](https://cloud.githubusercontent.com/assets/219623/12344320/e7bdb630-bb76-11e5-8ab4-7c43b3a5d680.png)

---

### name

[](#name)

```
$form->name('foo')->label('Foo')->default(['first' => 'Bar', 'surname' => 'Baz'])->required()
$form->get('foo') // Returns ['foo_first' => 'Bar', 'foo_surname' => 'Baz', 'foo' => 'Bar Baz']
$form->get('foo', 'surname') // Returns 'Baz'
```

**Example:**

`$form->name('name')->label('Name')->required();`

[![name](https://cloud.githubusercontent.com/assets/219623/12344329/f59dc24a-bb76-11e5-8b7a-1e425130d516.png)](https://cloud.githubusercontent.com/assets/219623/12344329/f59dc24a-bb76-11e5-8b7a-1e425130d516.png)

---

### email

[](#email)

```
$form->email('foo') // Same as `text` but with email validation added.
```

**Example:**

`$form->email('email')->label('Email Address')->required();`

[![email](https://cloud.githubusercontent.com/assets/219623/12344332/fe70fbd0-bb76-11e5-9671-ee8624f2e3fa.png)](https://cloud.githubusercontent.com/assets/219623/12344332/fe70fbd0-bb76-11e5-9671-ee8624f2e3fa.png)

---

### number

[](#number)

```
$form->number('foo')->label('Foo')->default('123')->required()
$form->get('foo') // Returns '123'
```

Validations: `between(min, max)`, `min(num)`, `max(num)`, `integer`, `in(array)`, `not_in(array)`

**Example:**

`$form->number('age')->label('Age')->integer()->min(18)->required();`

[![number](https://cloud.githubusercontent.com/assets/219623/12344336/072ce306-bb77-11e5-8668-e707780cf166.png)](https://cloud.githubusercontent.com/assets/219623/12344336/072ce306-bb77-11e5-8668-e707780cf166.png)

---

### password

[](#password)

```
$form->password('foo')->label('Foo')->required()
$form->get('foo') // Returns 'hashed_bar'
$form->password('foo')->matches('other_hash') // Returns true/false
```

**Example:**

`$form->password('password')->label('Password')->required();`

[![password](https://cloud.githubusercontent.com/assets/219623/12344346/10c30bf2-bb77-11e5-8b0b-45cf661ae126.png)](https://cloud.githubusercontent.com/assets/219623/12344346/10c30bf2-bb77-11e5-8b0b-45cf661ae126.png)

---

### paragraph\_text

[](#paragraph_text)

```
$form->paragraph_text('foo')->label('Foo')->default('bar')->required()
$form->get('foo') // Returns 'bar'
```

**Example:**

`$form->paragraph_text('comments')->label('Comments');`

[![paragraph_text](https://cloud.githubusercontent.com/assets/219623/12344352/1a29823e-bb77-11e5-9b29-48ee4a80a975.png)](https://cloud.githubusercontent.com/assets/219623/12344352/1a29823e-bb77-11e5-9b29-48ee4a80a975.png)

---

### checkbox

[](#checkbox)

```
$form->checkbox('foo')->label('Foo')->required()
$form->checkbox('foo')->checked() // Check the box
$form->checkbox('foo')->unchecked() // Uncheck the box
$form->get('foo') // Returns true/false
```

**Example:**

`$form->checkbox('subscribe')->label('Subscribe to our newsletter');`

[![checkbox](https://cloud.githubusercontent.com/assets/219623/12344357/229b2526-bb77-11e5-8bde-54f4a4a9c30e.png)](https://cloud.githubusercontent.com/assets/219623/12344357/229b2526-bb77-11e5-8bde-54f4a4a9c30e.png)

---

### checkboxes

[](#checkboxes)

```
$form->checkboxes('foo')->label('Foo')->options(['bar' => 'Bar', 'baz' => 'Baz'])->required()
$form->checkboxes('foo')->checked() // Check all the boxes
$form->checkboxes('foo')->checked(['bar']) // Check some of the boxes
$form->checkboxes('foo')->unchecked() // Uncheck all the boxes
$form->checkboxes('foo')->unchecked(['baz']) // Uncheck some of the boxes
$form->get('foo') // Returns ['foo_bar' => false, 'foo_baz' => false]
```

**Example:**

`$form->checkboxes('interests')->label('Interests')->options(['golf' => 'Golf', 'swimming' => 'Swimming', 'dancing' => 'Dancing', 'reading' => 'Reading'])->required();`

[![checkboxes](https://cloud.githubusercontent.com/assets/219623/12344360/2af0dbb2-bb77-11e5-9008-bfd02d3969ed.png)](https://cloud.githubusercontent.com/assets/219623/12344360/2af0dbb2-bb77-11e5-9008-bfd02d3969ed.png)

---

### dropdown

[](#dropdown)

```
$form->dropdown('foo')->label('Foo')->options(['bar' => 'Bar', 'baz' => 'Baz'])->default('baz')->required()
$form->get('foo') // Returns 'baz'
```

**Example:**

`$form->dropdown('colour')->label('Colour')->options(['red' => 'Red', 'green' => 'Green', 'blue' => 'Blue']);`

[![dropdown](https://cloud.githubusercontent.com/assets/219623/12344363/324a1c66-bb77-11e5-9963-bba7909fe8e7.png)](https://cloud.githubusercontent.com/assets/219623/12344363/324a1c66-bb77-11e5-9963-bba7909fe8e7.png)

---

### search

[](#search)

```
$form->search('foo')
$form->get('foo') // Returns ['foo' => 'bar', 'foo_button' => true]
```

**Example:**

`$form->search('search');`

[![search](https://cloud.githubusercontent.com/assets/219623/12344366/3a4153ee-bb77-11e5-89cd-30f0ced0ea11.png)](https://cloud.githubusercontent.com/assets/219623/12344366/3a4153ee-bb77-11e5-89cd-30f0ced0ea11.png)

---

Customisation
-------------

[](#customisation)

Forms was designed as a framework upon which developers can build a library of modules to simplify the repetitive task of processing complex requests. A basic set of fields and templates are included, however the expectation is that you will use those as a starting point for customisation. By rolling your own, you can design, build and test them once, and drop them into any application.

- [Creating fields](src/Fields/)
- [Creating templates](src/templates/)
- [Creating plugins](src/Plugins/)

Templates
---------

[](#templates)

A few basic template packages are provided by default that are compatible with common css frameworks such as [Bootstrap](http://getbootstrap.com/) and [Foundation](http://foundation.zurb.com/). These should provide a great base for [customisation](#customisation). Forms is compatible with CSS preprocessors and development of base templates for [Jeet](http://github.com/mojotech/jeet), [Singularity](https://github.com/Team-Sass/Singularity) and [Neat](https://github.com/thoughtbot/neat) are in the pipeline.

```
$form->setTemplate('bootstrap') 		// Default
$form->setTemplate('foundation')

$form->setTemplate('jeet')              // Coming soon...
$form->setTemplate('singularity')       // Coming soon...
$form->setTemplate('neat')              // Coming soon...
```

Languages
---------

[](#languages)

```
$form->setLanguage('en') 	// Set language to english
$form->setLanguage('es') 	// Idioma establecida en español
```

Plugins
-------

[](#plugins)

```
$form->addPlugin('feedback');   // Instant validation feedback
$form->addPlugin('memory');   // Autosave as you type
```

Security
--------

[](#security)

If you discover any security related issues, please email helmut.github \[at\] gmail.com instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

26

—

LowBetter than 41% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~222 days

Total

3

Last Release

3366d ago

PHP version history (2 changes)v1.1.6PHP >=5.4.0

v1.1.7PHP >=5.5.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/e4d995a0b45dc54a08574edce5df5fa9c8367fd81f87a6f94dcdec56f56dde06?d=identicon)[helmut](/maintainers/helmut)

---

Top Contributors

[![helmut](https://avatars.githubusercontent.com/u/219623?v=4)](https://github.com/helmut "helmut (145 commits)")

---

Tags

requestsymfonylaraveltwigemailpasswordmodelbladetextmustacheformfielddropdowninputnamecheckboxcheckboxes

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/helmut-forms/health.svg)

```
[![Health](https://phpackages.com/badges/helmut-forms/health.svg)](https://phpackages.com/packages/helmut-forms)
```

###  Alternatives

[silvanite/novafieldcheckboxes

A Laravel Nova field to display a number of multi-select options using checkboxes.

68863.3k1](/packages/silvanite-novafieldcheckboxes)[twig/inky-extra

A Twig extension for the inky email templating engine

16713.2M70](/packages/twig-inky-extra)[nucleos/antispam-bundle

This bundle provides some basic features to reduce spam in symfony forms.

52105.1k](/packages/nucleos-antispam-bundle)[mati365/ckeditor5-symfony

CKEditor 5 integration for Symfony

261.9k](/packages/mati365-ckeditor5-symfony)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)