Forms

Building complete forms, and the helpers that support them.

Form Parts

open

Creates an opening form tag.

$form->open('/submit', 'POST', ['id' => 'myForm', 'class' => 'form-horizontal']);

openMultipart

Creates an opening form tag with multipart encoding for file uploads.

$form->openMultipart('/upload', 'POST', ['id' => 'uploadForm']);

The multipart encoding is always applied — pass any attributes you like and the form still renders with enctype="multipart/form-data".

close

Creates a closing form tag.

$form->close();

submit

Creates a submit button.

$form->submit('Send Message', ['class' => 'btn btn-primary']);

csrf

Returns the CSRF hidden token field for a hand-written <form>. Forms built with open()/create() already include it automatically, so use this only when you write your own form markup.

<form method="POST">
    <?= $form->csrf() ?>
    <input type="hidden" name="_id" value="myForm">
    <input name="email" value="<?= $form->value('email') ?>">
</form>

Returns an empty string when CSRF is disabled ('csrf' => false); uses a framework token generator when one is configured. Native CSRF requires an active session.

Hand-written forms also need the hidden _id field shown above (matching the form's id config, 'myForm' by default) — without it, submitted() never returns true for this form.

value

Returns the value of a form field.

echo $form->value('username', 'Default Username');

value() is for fields that hold one value. A field that submits several at once — a checkbox group, or a selectMultiple, anything whose name ends in [] — returns an empty string here. Use request() to read those, and keep the [] in the name: $form->request('colors[]', ['required']) gives you the array. The bare name ('colors') treats the field as a single value and fails validation.

labelOpen / labelClose

Creates label tags for custom layouts.

echo $form->labelOpen('email', 'Email Address:');
echo $form->email('email');
echo $form->labelClose();

---

Form Builders

create

Creates a complete form using a string or array configuration.

// Using a string
$form->create('Name, Email|email, Password|password');

// Using an array
$form->create([
    'fields' => [
        'name' => ['label' => 'Name'],
        'email' => ['type' => 'email', 'label' => 'Email']
    ]
]);

// Loading from a file
$form->create('/login');

createAndValidate

Creates a form with automatic validation and messaging - the simplest way to build a validated form.

// Simplest - just show form and messages
$form->createAndValidate('Name[required], Email[email, required]');

// With callback - process data on success
$form->createAndValidate('Name, Email', onSuccess: fn($data) => $form->sql->save('contacts', $data));

// With an upload - $data['photo'] is the saved file
$form->createAndValidate('Name, Photo|image[required, width:400]',
    onSuccess: fn($data) => $form->sql->save('members', ['name' => $data['name'], 'photo' => $data['photo']->url])
);

// Without callback - check ok() yourself
$data = $form->createAndValidate('Name, Email');
if ($data && $form->ok()) {
    $form->sql->save('contacts', $data);
}

Parameters:

Parameter	Type	Default	Description
$fields	array|string	(required)	Field definitions
$attributes	array|string	[]	Form attributes (action, method, id)
$onSuccess	callable|null	null	Callback when validation passes
$successMessage	string	'Thank you for filling out our form!'	Message shown on success
$errorMessage	string	'Please fix the errors'	Message on failure
$hideOnSuccess	bool	true	Hide form after successful submission

Behavior:

• Returns null when form not submitted (initial page load)
• Returns data when submitted (use $form->ok() to check validity)
• Shows success message when valid, error message when invalid
• Callback runs before success message (if provided)
• If the callback adds an error (a failed $form->sql->save() does), the error message is shown instead and the form stays on the page
• hideOnSuccess: true (default) hides form after successful submission
• hideOnSuccess: false keeps form visible with success message above it
• A field typed image, pdf or file is saved by the Upload service, and the form is made multipart for you. See File Uploads

renderValidated

The Blade-friendly companion to createAndValidate(). Returns the form's HTML (instead of the data) so it can be echoed in a template, and delivers the validated data through the onSuccess callback. Use this when echo is false — the default in Laravel.

{!! $form->renderValidated('Name[required], Email[email, required]',
    onSuccess: fn($data) => User::create($data)
) !!}

Parameters: identical to createAndValidate.

Behavior:

• Returns the rendered form markup (in echo: true mode it echoes the output and returns an empty string)
• The validated data is delivered to the onSuccess callback, never returned
• Shows success message when valid, error message when invalid
• If the callback adds an error, the error message is shown instead and the form stays on the page
• hideOnSuccess: true (default) hides the form after a successful submission; false keeps it visible with the success message above it

createMultipart

Creates a form with multipart encoding for file uploads.

$form->createMultipart('Name, Profile Picture|file');

A form with a file, image or pdf field is already multipart, so create() works just as well for those. Use createMultipart() when the form doesn't declare a file field but still needs the encoding.

createMultistep

Creates a multistep form.

$form->createMultistep($formArray, [
    'auto' => true,
    'reviewTitle' => 'Review Your Information',
    'nextText' => 'Next',
    'submitText' => 'Submit'
]);

request

Processes and validates submitted form data.

// Recommended: uses the same rules from create()
$data = $form->request();

// Single field with array of rules
$email = $form->request('email', ['required', 'email']);

// Multiple fields using string syntax with inline rules
$data = $form->request('Name[required, min:3], Email[required, email]');

When called without arguments, request() automatically uses the validation rules defined in create(). See Auto-Rules for details.

For a field that submits several values at once — a checkbox group, or a selectMultiple — keep the [] in the name so the value is validated as an array:

// Multi-value field: the [] tells request() to expect an array
$colors = $form->request('colors[]', ['required']);

---