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));

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

Parameters:

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)
• hideOnSuccess: true (default) hides form after successful submission
• hideOnSuccess: false keeps form visible with success message above it

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
• 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');

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']);

Form Helpers

submitted

Checks if the form has been submitted.

if ($form->submitted()) {
    // Process form data
}

Returns true only when the posted _id matches this form's id config, and — on a POST — the CSRF _token is valid (unless CSRF is disabled).

A GET form works the same way. Flick renders a hidden _id field into every form it builds, so a GET form submits ?_id=myForm&... and is recognized. Arriving on a page with an unrelated query string, like a link carrying ?utm_source=newsletter, is not a submission.

<input type="hidden" name="_id" value="myForm">

A missing or invalid token makes submitted() return false — it does not throw. It also puts a message in the error bag under the _token key, so a visitor sees why nothing happened instead of a form that silently re-renders.

hasService

Checks if a service is available.

if ($form->hasService('mail')) {
    $form->mail->send($to, $subject, $message);
}

hasProPackage

Checks if the Pro package is installed and available.

if ($form->hasProPackage()) {
    // Pro features are available
}

clear

Empties the $_POST and $_GET arrays after a successful submission. Only acts when the form was submitted and validation passed — on a failed submission it leaves the request data alone (so fields stay repopulated).

$form->clear();

flushCache

Deletes the compiled views under <assets>/cache/views. Prints a success alert into the page when it finishes.

$form->flushCache();