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.

Blade 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()

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

@vertical(['url' => 'some-url'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Horizontal form

@horizontal(['url' => 'some-url'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Custom horizontal form

@horizontal(['url' => 'some-url', 'pull_right' => false, 'left_class' => 'col-5', 'right_class' => 'col-7'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Inline form

@inline(['url' => 'some-url'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Custom inline form

@inline(['url' => 'some-url', 'lspace' => 'mr-3', 'hspace' => 'mr-5', 'vspace' => 'my-4'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

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 ~.

<!-- Simple -->
@text('simple')

<!-- Disabled -->
@text('disabled', null, 'custom value', ['disabled' => true])

<!-- Custom -->
@text('custom', 'Custom', null, ['id' => 'custom-id', 'placeholder' => 'Enter a value'])

<!-- Help text -->
@text('help_text', 'Field with help text', null, ['help' => 'This is a help text'])

<!-- Custom form group -->
@text('custom_group', 'Custom form group', null, [
    'group' => [
        'id' => 'custom-group-id',
        'class' => 'p-2',
        'style' => 'border: 1px solid #ccc;'
    ]
])

<!-- No form group -->
@text('no_form_group', 'No form group', null, ['group' => false])

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 = [])
BF::password($name, $label = null, array $options = [])

Examples:

@text('text')
@email('email')
@url('url')
@tel('tel')
@number('number')
@date('date')
@time('time')
@color('color')
@textarea('textarea')
@password('password')

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 = [])
BF::radio($name, $label = null, $value = 1, $checked = null, array $options = [])

Single radios examples:

@radio('single_radio_default')
@radio('single_radio_custom', 'Custom radio', null, null, ['custom' => true])

Single checkboxes examples:

@checkbox('single_checkbox_default')
@checkbox('single_checkbox_custom', 'Custom checkbox', null, null, ['custom' => true])
@checkbox('single_checkbox_switch', 'Switch checkbox', null, null, ['switch' => true])

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 = [])
BF::radios($name, $label = null, array $choices = [], $checked = null, array $options = [])

Radios groups examples:

@radios('radios_default', null, ['L' => 'Large', 'S' => 'Small'])
@radios('radios_custom', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true])
@radios('radios_inline', null, ['L' => 'Large', 'S' => 'Small'], null, ['inline' => true])

Checkboxes groups examples:

@checkboxes('checkboxes_default', null, ['L' => 'Large', 'S' => 'Small'])
@checkboxes('checkboxes_custom', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true])
@checkboxes('checkboxes_switch', null, ['L' => 'Large', 'S' => 'Small'], null, ['switch' => true])
@checkboxes('checkboxes_inline', null, ['L' => 'Large', 'S' => 'Small'], null, ['inline' => true])

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, array $choices = [], $selected = null, array $options = [])

Default select examples:

@select('select_default', null, ['L' => 'Large', 'S' => 'Small'])
@select('select_multiple', null, ['L' => 'Large', 'S' => 'Small'], null, ['multiple' => true])
@select('select_optgroup', null, ['Cats' => ['leopard' => 'Leopard'], 'Dogs' => ['spaniel' => 'Spaniel']])

Custom select examples:

@select('select_custom', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true])
@select('select_custom_multiple', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true, 'multiple' => true])

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 = [])

Examples:

@file('file_default')
@file('file_custom', null, ['custom' => true])
@file('file_custom_text', null, ['custom' => true, 'text' => 'Choisir un fichier', 'button' => 'Parcourir'])

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 = [])

Examples:

@range('range_default')
@range('range_custom', null, null, ['custom' => true])
@range('range_minmax', null, null, ['min' => 0, 'max' => 10, 'step' => 0.5])

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 = [])

Examples:

@hidden('hidden_field')
@hidden('hidden_field_value', 'The hidden value')
@hidden('hidden_field_attributes', null, ['data-custom' => 'A custom data attribute'])

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:

@text('input_groups_prepend', 'Prepend example', null, ['prepend' => '@@'])
@text('input_groups_append', 'Append example', null, ['append' => '.00'])
@text('input_groups_both', 'Both example', null, ['prepend' => '$', 'append' => '.00'])
@text('input_groups_array', 'Array example', null, ['prepend' => ['$', '0.'], 'append' => ['.00', '<button class="btn btn-outline-secondary" type="button">Button</button>']])

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)

Examples:

@label('label_field', 'Simple label')
@label('label_html_field', '<b>HTML label</b>')

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 = [])

Examples:

@submit()
@submit('Send')
@submit('Send', 'success')
@submit('Send', ['class' => 'btn btn-outline-primary'])

Reset button:

Default style is danger.

BF::reset($value = null, $options = [])

Examples:

@reset()
@reset('Reset form')
@reset('Reset form', 'warning')

Standard button:

Default style is primary.

BF::button($value = null, $options = [])

Examples:

@button('Click me')
@button('Click me', 'info')

Link button:

Default style is primary.

BF::link($url, $title = null, $options = [])

Examples:

@link('#', 'A link button')
@link('#', 'A link button', 'secondary')

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: