Bootstrap 4 forms builder for Laravel 5.8+
This package uses in background Laravel Collective HTML
to simplify Bootstrap 4 forms creation into Laravel applications.
Model form binding and automatic error display are supported, as well as most of Bootstrap forms features : form layouts, custom fields, input groups, ...
This package was mainly inspired by Dwight Watson's and
Michael Burgin's awesome work.
Credits and many thanks to them :-)
Any contribution or feedback is highly welcomed, please feel free to create a pull request
or submit a new issue.
Installation
Simply install the package using Composer:
composer require bgaze/bootstrap-form
There are a various configuration options available, publish the configuration file to customize them:
php artisan vendor:publish --provider="Bgaze\BootstrapForm\BootstrapFormServiceProvider"
That's it, you can start to build forms.
But if you use PhpStorm IDE, you can also check this gist
to easily configure syntax highlighting and live templates for this package's custom Blade directives.
Quick start
The BF facade provides many methods to create forms and form inputs.
All of them have a Blade directive alias.
In this doc, we'll mainly use blade directives as it is probably the most common way to use BF.
Blate template:
@open(['novalidate' => true])
@text('login')
@email('email')
@checkbox('remember_me', null, 1, null, ['switch' => true, 'inline' => true])
@submit('Login')
@close
PHP code:
echo BF::open(['novalidate' => true])
echo BF::text('login')
echo BF::email('email')
echo BF::checkbox('remember_me', null, 1, null, ['switch' => true, 'inline' => true])
echo BF::submit('Login')
echo BF::close()
Submit the form with errors to test automatic errors management ;-)
<form method="POST" action="https://packages.bgaze.fr/bootstrap-form" accept-charset="UTF-8" role="form" novalidate>
<input name="_token" type="hidden" value="J3LqnfKabRxznKAbEQmLy9vursyvKlrc5jpz1rRK">
<div id="login_group" class="form-group">
<label for="login">Login</label>
<div>
<input id="login" class="form-control" name="login" type="text">
</div>
</div>
<div id="email_group" class="form-group">
<label for="email">Email</label>
<div>
<input id="email" class="form-control" name="email" type="email">
</div>
</div>
<div id="remember_me_group" class="form-group">
<div>
<div class="custom-control custom-control-inline custom-switch">
<input id="remember_me" class="custom-control-input" name="remember_me" type="checkbox" value="1">
<label for="remember_me" class="custom-control-label">Remember me</label>
</div>
</div>
</div>
<input class="btn btn-primary" type="submit" value="Login">
</form>
Forms
Creating forms
Open a form using BF::open() method, or @open() directive, wich accepts an array of options as argument.
By default, a POST method will be assumed. However, you are free to specify another method.
Close the form using BF::close() method or @close directive.
@open(['route' => 'users.index', 'method' => 'GET', 'id' => 'users-search-form'])
<!-- Add your fields -->
@close
There is three ways to set the form action, priority order is: url > route > action
<!-- Using an url -->
@open(['url' => 'foo/bar'])
<!-- Using a named route -->
@open(['route' => 'route.name'])
<!-- Using a controller action -->
@open(['action' => 'Controller@method'])
<!-- You may pass in parameters too -->
@open(['route' => ['route.name', $id]])
@open(['action' => ['Controller@method', $id]])
If your form is going to accept file uploads, add a files option to your array:
@open(['url' => 'foo/bar', 'files' => true])
Form options
Please find below available form options.
=> Any key that is not in form's options list will be used as HTML attribute.
=> Options take precedence on attributes. To use an option key as HTML attribute, prefix it with a ~.
| Option |
Default value |
Accepted values |
Description |
| files |
null |
null / true |
Configure form enctype for file upload |
| url |
null |
string |
An url to use as form action
Example: /foo/bar |
| route |
null |
string / array |
A route to use as form action
Example: users.update |
| action |
null |
string / array |
A controller action to use as form action
Example: UserController@update |
| store |
null |
string / array |
The store action when using model binding |
| update |
null |
string / array |
The update action when using model binding |
| model |
null |
Illuminate\Database\Eloquent\Model |
A model to bind to the form |
| error_bag |
'default' |
string |
The error bag to use for the form errors, useful when multiple forms exists on the same page. |
| layout |
Inherited 1 |
vertical / horizontal / inline |
The Bootstrap layout of the form (doc) |
| group |
Inherited 1 |
false / array |
A set of HTML attributes for all the form groups (extends group package configuration) |
| custom |
Inherited 1 |
bool |
Use Bootstrap custom style by default when available |
| show_all_errors |
Inherited 1 |
bool |
Show all the errors of an input or just the first one |
| pull_right 2 |
Inherited 1 |
false / HTML class |
Add an empty left column to checkboxes, radios and fields without label to preserve fields alignment |
| left_class 2 |
Inherited 1 |
string |
The default width of left column |
| right_class 2 |
Inherited 1 |
string |
The default width of right column |
| lspace 3 |
Inherited 1 |
false / HTML class |
The horizontal blank space between labels and fields, doesn't apply to checkboxes and radios (CSS needed) |
| hspace 3 |
Inherited 1 |
false / HTML class |
The horizontal blank space between fields |
| vspace 3 |
Inherited 1 |
false / HTML class |
The vertical blank space between fields |
1: Inherited from package configuration.
2: Horizontal layout only.
3: Inline layout only.
Form variations
BF support the three Bootstrap form layouts: vertical, horizontal, inline.
The form layout can be set when opening form using the layout option.
BF provide helpers to open a form with a specific layout:
BF::vertical() / @vertical()BF::horizontal() / @horizontal()BF::inline() / @inline()
They work exactly the same than BF::open() / @open() with the layout option forced.
Several options allow to adjuts horizontal and inline layouts.
Vertical form
Horizontal form
Custom horizontal form
Inline form
Custom inline form
Model binding
Model binding allows to populate a form based on a model attributes.
Fields will be populated with this priority: Session (Old Input) > Explicit value > Model attribute.
To open a model binded form, use the model option.
Passed value must be an instance of Illuminate\Database\Eloquent\Model otherwise it will be ignored.
<!-- Using an url -->
@open(['model' => $user, 'url' => url('users/store')])
<!-- Using a named route -->
@open(['model' => $user, 'route' => 'users.store'])
@open(['model' => $user, 'route' => ['users.update', $user->id]])
<!-- Using a controller action -->
@open(['model' => $user, 'action' => 'UserController@store'])
@open(['model' => $user, 'action' => ['UserController@update', $user->id]])
If you provide store and update options, BF will automatically set form action and method based on model existance.
For update action, model route key will be automatically populated.
<!-- Using named routes -->
@open(['model' => $user, 'store' => 'users.store', 'update' => 'users.update'])
<!-- Using controller actions -->
@open(['model' => $user, 'store' => 'UserController@store', 'update' => 'UserController@update'])
<!-- You may pass parameters too, but remember that model route key will be added in last position -->
@open(['model' => $user, 'store' => ['users.store', $routeParameter], 'update' => ['users.update', $routeParameter]])
@open(['model' => $user, 'store' => ['UserController@store', $routeParameter], 'update' => ['UserController@update', $routeParameter]])
Form inputs
Creating inputs
Most of form input functions accept following four arguments:
- name
-
The name of the field.
Unless they are explicitly provided, name will also be used as id attribute and as base for the form group id attribute.
- label
-
The label of the field.
Please note that HTML escaping is disabled on labels to ease complex label creation.
If label is null, it will be generated based on name value.
If label is false, no label will be inserted.
- value
-
The value of the field.
Field value is automatically evaluated with this priority:
Session (Old Input) > Explicit value > Model attribute (model binded forms only).
Most of times, you just need to set null as value.
- options
-
An array of options.
Any value passed that is not in field options list will be used as HTML attribute.
Options take precedence on attributes, to use an option key as HTML attribute, prefix it with a ~.
Form inputs examples
Common options
All input functions accept following options in addition to their specific ones:
| Option |
Default value |
Accepted values |
Description |
| help |
false |
false / string |
Display a help text under the field (see doc) |
| group |
Inherited 1 |
null / false / array |
array: a set of HTML attributes for the form-group element (extends group form option).
false: return the input element only.
|
| layout 2 |
Inherited 1 |
vertical / horizontal / inline |
The Bootstrap layout of the field |
| show_all_errors |
Inherited 1 |
bool |
Show all the errors of an input or just the first one |
| pull_right 3 |
Inherited 1 |
false / HTML class |
Add an empty left column to checkboxes, radios and fields without label to preserve fields alignment |
| left_class 3 |
Inherited 1 |
string |
The default width of left column |
| right_class 3 |
Inherited 1 |
string |
The default width of right column |
| lspace 4 |
Inherited 1 |
false / HTML class |
The horizontal blank space between label and field, doesn't apply to checkboxes and radios (CSS needed) |
| hspace 4 |
Inherited 1 |
false / HTML class |
The horizontal blank space between fields |
| vspace 4 |
Inherited 1 |
false / HTML class |
The vertical blank space between fields |
1: Inherited from current form options, or package configuration if no opened form.
2: The layout option allows to override the current context layout.
For instance, you can add a horizontal form group into a vertical form.
As this is not a planned Bootstrap feature, you'll probably need to adapt CSS accordingly.
3: Horizontal layout only.
4: Inline layout only.
Text inputs
Text inputs funtions are:
BF::text() / @text()BF::email() / @email()BF::url() / @url()BF::tel() / @tel()BF::number() / @number()BF::date() / @date()BF::time() / @time()BF::color() / @color()BF::textarea() / @textarea()BF::password() / @password()
Signature:
All these functions signature is the same, except password input that doesn't accept a value:
BF::text($name, $label = null, $value = null, array $options = [])
@text($name, $label = null, $value = null, array $options = [])
BF::password($name, $label = null, array $options = [])
@password($name, $label = null, array $options = [])
Text inputs examples
Options:
In addition to common options, following ones are accepted:
| Option |
Default value |
Accepted values |
Description |
| size |
null |
null / sm / lg |
The size of the field (see
doc) |
| append |
false |
false / string / array |
An input group prefix (see Input groups for details)
|
| prepend |
false |
false / string / array |
An input group suffix (see Input groups for details)
|
Checkbox & radio
Single input:
Pass a boolean into checked argument to force input's checked state.
BF::checkbox($name, $label = null, $value = 1, $checked = null, array $options = [])
@checkbox($name, $label = null, $value = 1, $checked = null, array $options = [])
BF::radio($name, $label = null, $value = 1, $checked = null, array $options = [])
@radio($name, $label = null, $value = 1, $checked = null, array $options = [])
Single radios examples
Single checkboxes examples
Inputs group:
- choices
-
A
value => label associative array defining group's inputs.
Example: [1 => 'Yes', 0 => 'No']
- checked
-
An array containing the value(s) of checked input(s).
If only one input is checked, you can pass its value directly.
BF::checkboxes($name, $label = null, array $choices = [], $checked = null, array $options = [])
@checkboxes($name, $label = null, array $choices = [], $checked = null, array $options = [])
BF::radios($name, $label = null, array $choices = [], $checked = null, array $options = [])
@radios($name, $label = null, array $choices = [], $checked = null, array $options = [])
Radios groups examples
Checkboxes groups examples
Options:
In addition to common options, following ones are accepted:
| Option |
Default value |
Accepted values |
Description |
| inline |
false |
bool |
Create inline input(s) (doc) |
| custom |
Inherited 1 |
bool |
Create custom input(s) (doc) |
| switch 2 |
false |
bool |
Create switch custom input(s) (doc) |
1: Inherited from current form options, or package configuration if no opened form.
2: Checkbox inputs and groups only.
Select input
Signature:
- choices
-
The input options as a
value => label associative array:
['L' => 'Large', 'S' => 'Small'].
Options groups can be created using nested array:
['Cats' => ['leopard' => 'Leopard'],'Dogs' => ['spaniel' => 'Spaniel']]
- checked
-
An array of selected option(s) value(s).
If only one option is selected, you can pass its value directly.
BF::select($name, $label = null, $choices = [], $selected = null, array $options = [])
@select($name, $label = null, $choices = [], $selected = null, array $options = [])
Default select examples
Custom select examples
Options:
In addition to common options, following ones are accepted:
| Option |
Default value |
Accepted values |
Description |
| custom |
Inherited 1 |
bool |
Create a custom file input (doc) |
| size |
null |
null / sm / lg |
The size of the field (doc) |
| append |
false |
false / string / array |
An input group prefix (see Input groups) |
| prepend |
false |
false / string / array |
An input group suffix (see Input groups) |
1: Inherited from current form options, or package configuration if no opened form.
File input
Custom file input requires additional JavaScript.
The recommended plugin is bs-custom-file-input.
Signature:
BF::file($name, $label = null, array $options = [])
@file($name, $label = null, array $options = [])
Examples
Options:
In addition to common options, following ones are accepted:
| Option |
Default value |
Accepted values |
Description |
| custom |
Inherited 1 |
bool |
Create a custom file input (doc) |
| text 2 |
"Choose file" |
string |
The placeholder text |
| button 2 |
null |
string |
The button text |
| append 2 |
false |
false / string / array |
An input group prefix (see Input groups) |
| prepend 2 |
false |
false / string / array |
An input group suffix (see Input groups) |
1: Inherited from current form options, or package configuration if no opened form.
2: Custom file inputs only.
Range input
See documentation for more details on range inputs usage.
Signature:
BF::range($name, $label = null, $value = null, array $options = [])
@range($name, $label = null, $value = null, array $options = [])
Examples
Options:
In addition to common options, following option is accepted:
| Option |
Default value |
Accepted values |
Description |
| custom |
Inherited 1 |
bool |
Create a custom range input |
1: Inherited from current form options, or package configuration if no opened form.
Misc
Hidden input
This function is an alias to Form Builder function.
As for other inputs, id attribute base on field name will be added if missing
BF::hidden($name, $value = null, $options = [])
@hidden($name, $value = null, $options = [])
Blate template:
@hidden('hidden1')
@hidden('hidden2', 'some-value', ['id' => 'custom-id'])
Generated HTML:
<input id="hidden1" name="hidden1" type="hidden">
<input id="custom-id" name="hidden2" type="hidden" value="some-value">
Input groups
For compatible input types, set append / prepend options to create a Bootstrap input group.
See documentation for details.
These options accept a HTML string, or an array of HTML strings, so you're free to build your field addons as you want.
Please note that provided HTML is not escaped.
Examples
Label
This function is an alias to Form Builder function with escaping HTML disabled by default.
BF::label($name, $value = null, array $options = [], $escapeHtml = false)
@label($name, $value = null, array $options = [], $escapeHtml = false)
Blate template:
@label('field_name')
@label('field_name', 'Custom label <b>with HTML</b>', ['id' => 'custom-id'])
@label('field_name', 'Custom label <b>with HTML</b>', [], true)
Generated HTML:
<label for="field_name">Field Name</label>
<label for="field_name" id="custom-id">Custom label <b>with HTML</b></label>
<label for="field_name">Custom label <b>with HTML</b></label>
Buttons
To create Bootstrap flavoured buttons, BF provides following helpers.
If you pass a string into the options argument, it will be prefixed by btn btn-.
If you pass an array, it will be merge on ['class' => 'btn btn-xxx'], with xxx the default button style.
Submit button:
Default style is primary.
BF::submit($value = null, $options = null)
@submit($value = null, $options = null)
Examples
Reset button:
Default style is danger.
BF::reset($value = null, $options = null)
@reset($value = null, $options = null)
Examples
Standard button:
Default style is primary.
BF::button($value = null, $options = null)
@button($value = null, $options = null)
Examples
Link button:
Default style is primary.
BF::link($url, $title = null, $options = null)
@link($url, $title = null, $options = null)
Examples
Available methods & directives
Here is the list of available methods and directives.
Each directive is an alias to related BF facade method and works exactly like it.
If you use PhpStorm IDE, please check this gist
to easily configure syntax highlighting and live templates for this package's custom Blade directives.
| Facade methods |
Blade directives |
Description |
| BF::htmlBuilder() |
- |
Get the Laravel Collective form builder instance |
| BF::formBuilder() |
- |
Get the Laravel Collective HTML builder instance |
| BF::open() |
@open() |
Open a form (layout based on default configuration) |
| BF::vertical() |
@vertical() |
Open a vertical form |
| BF::inline() |
@inline() |
Open a inline form |
| BF::horizontal() |
@horizontal() |
Open a horizontal form |
| BF::close() |
@close |
Close a form |
| BF::text() |
@text() |
Create a text input |
| BF::email() |
@email() |
Create an email input |
| BF::url() |
@url() |
Create an url input |
| BF::tel() |
@tel() |
Create a tel input |
| BF::number() |
@number() |
Create a number input |
| BF::date() |
@date() |
Create a date input |
| BF::time() |
@time() |
Create a time input |
| BF::color() |
@color() |
Create a color input |
| BF::textarea() |
@textarea() |
Create a textarea |
| BF::password() |
@password() |
Create a password input |
| BF::file() |
@file() |
Create a file input |
| BF::hidden() |
@hidden() |
Create a hidden input |
| BF::select() |
@select() |
Create a select input |
| BF::range() |
@range() |
Create a range input |
| BF::checkbox() |
@checkbox() |
Create a checkbox input |
| BF::checkboxes() |
@checkboxes() |
Create a checkboxes group |
| BF::radio() |
@radio() |
Create a radio input |
| BF::radios() |
@radios() |
Create a radios group |
| BF::label() |
@label() |
Create a label |
| BF::submit() |
@submit() |
Create a submit input |
| BF::reset() |
@reset() |
Create a reset input |
| BF::button() |
@button() |
Create a button |
| BF::link() |
@link() |
Create a link button |
Packages
Feel free to visit my other packages:
PHP-CS-Fixer for Laravel 5.5+
This package allows to use PHP-CS-Fixer right into Laravel 5.5+ applications to format PHP code.
Github
Documentation
Bootstrap 4 dialogs
BSD is a tiny and flexible collection of dialog popups based on Bootstrap 4 modals.
Custom dialogs can be easily defined, in addition to built-in ones (alert, confirm and prompt).
Github
Documentation
Bootstrap Color Palette
BCP is a simple color palette for Bootstrap 4, like in Google doc, built on the top of Bootstrap 4 Popover plugin.
Github
Documentation
Laravel Kvstore
A simple and easy to use key-value database store for Laravel 5.5+
All values are stored into database and managed using cache to avoid unecessary queries.
Casting is supported to manage values type.
Github
Documentation