Form

A server-side form wrapper that handles form-group layout, labels with required-field indicators, hint text, automatic CSRF tokens, and an auto-generated client-side Validator — all from a single fluent builder. The Form component is purely PHP; fields with required in their rules automatically display a red asterisk.

Usage pattern: build the form chain, call ->submit() to configure the submit button (returns a Button for fluent chaining), then echo $form to render the complete HTML.

Auto-validating Form

Pass rules as the third argument to ->field(). The Form generates a Validator automatically, deriving error messages from the label text. Override with the optional fourth argument. CSRF token injected by default on POST.

Fill in the form and click Send Message...

// Build the form, configure the submit button (returns Button),
// then echo the Form variable to render the full HTML.
<?php
$form = $m->form('contactForm')
    ->action('/contact/submit')
    ->field(
        $m->textbox('cf-name')->name('name'),
        'Full Name',
        ['required']
    )
    ->field(
        $m->textbox('cf-email')->name('email'),
        'Email Address',
        ['required', 'email']
    )
    ->field(
        $m->textarea('cf-message')->name('message'),
        'Message',
        ['required', ['minLength' => 10]],
        'Message must be at least 10 characters.',
        'Be as specific as you can.'
    );
$form->submit('Send Message', 'fa-paper-plane')->primary();
echo $form;

Cancel & Reset Buttons

->cancel($text, $href, $icon) adds a secondary action button rendered as an anchor link (when $href is given) or a history.back() button when no href is supplied. ->reset($text, $icon) adds a type="reset" button that clears all fields to their initial DOM values. Both methods return the Form for chaining. Action buttons render in the order: submit → cancel → reset.

// ->cancel() returns the Form for chaining.
// Supply a $href to render as an anchor link; omit it for history.back().
<?php
$form = $m->form('newPostForm')
    ->action('/posts/create')
    ->field($m->textbox('title')->name('title'), 'Title', ['required'])
    ->field($m->textarea('body' )->name('body'),  'Body',  ['required'])
    ->cancel('Cancel', '/posts');     // href → renders as <a href="/posts">
$form->submit('Publish Post', 'fa-paper-plane')->primary();
echo $form;

// Without href — renders as onclick="window.history.back()"
$form = $m->form('editForm')
    ->action('/posts/update')
    ->field(...)
    ->cancel();                        // defaults: "Cancel", history.back(), fa-times
$form->submit('Save Changes', 'fa-save')->primary();
echo $form;

Reset Button

Use ->reset() on filter or data-entry forms where users may want to clear all inputs. No JavaScript needed — the browser handles it via type="reset".

// ->reset() adds a <button type="reset"> — the browser clears all fields.
<?php
$form = $m->form('filterForm')
    ->action('/items')
    ->layout('inline')
    ->field($m->textbox('name'  )->name('name'),   'Name')
    ->field($m->dropdown('status')->name('status'), 'Status')
    ->reset('Clear');       // optional icon: ->reset('Reset', 'fa-times')
$form->submit('Filter', 'fa-filter');
echo $form;

All Three Action Buttons

Submit, cancel, and reset can all be combined. They render in one form-actions div in the order: submit → cancel → reset.

// All three action buttons — order: submit → cancel → reset.
<?php
$form = $m->form('profileForm')
    ->action('/profile/save')
    ->field($m->textbox('first_name')->name('first_name'), 'First Name', ['required'])
    ->field($m->textbox('last_name' )->name('last_name'),  'Last Name')
    ->cancel('Discard', '/profile')     // anchor back to profile
    ->reset('Clear All', 'fa-eraser');  // type="reset"
$form->submit('Save Profile', 'fa-save')->primary();
echo $form;

Model Binding

Pass an associative array or object to ->model() to pre-populate field values. Keys are matched to each component's name() attribute via value().

Edit the fields above and click Save Changes...

// Array keys map to each component's name() attribute.
$user = ['display_name' => 'Jane Smith', 'email' => 'jane@example.com', 'bio' => '...'];

<?php
$form = $m->form('editForm')
    ->action('/profile/save')
    ->model($user)
    ->field($m->textbox('ef-name' )->name('display_name'), 'Display Name', ['required'])
    ->field($m->textbox('ef-email')->name('email'),         'Email Address', ['required', 'email'])
    ->field($m->textarea('ef-bio' )->name('bio'),           'Bio',           [['maxLength' => 200]], '', 'Max 200 chars.')
    ->cancel('Cancel', '/profile');
$form->submit('Save Changes', 'fa-save')->primary();
echo $form;

Layouts

->layout('horizontal') places labels and fields side-by-side. ->layout('inline') flows all fields into one row — useful for filter bars. Default is vertical.

Horizontal

// layout() options: vertical (default) | horizontal | inline
<?php
$form = $m->form('settingsForm')
    ->action('/settings/save')
    ->layout('horizontal')
    ->field($m->textbox('s-first')->name('first_name'), 'First Name')
    ->field($m->textbox('s-last' )->name('last_name'),  'Last Name')
    ->field(
        $m->dropdown('s-role')->name('role')->dataSource($roles)->placeholder('Select…'),
        'Role'
    );
$form->submit('Update', 'fa-check')->primary();
echo $form;

No Auto-Validation

->noValidation() suppresses the auto-generated Validator. Use this when the Form is inside a Wizard (which manages validation per-step), or when you want to manage a separate $m->validator() yourself.

// Suppress auto-Validator — e.g. inside a Wizard step
<?php
$stepForm = $m->form('step1-form')
    ->noCsrf()
    ->noValidation()
    ->field($m->textbox('s1-name')->name('name'),  'Full Name')
    ->field($m->textbox('s1-email')->name('email'), 'Email');
$stepForm->submit('Next', 'fa-arrow-right')->primary();

// Attach a separate Validator that the Wizard step references
$stepValidator = $m->validator('step1-form')
    ->field('s1-name',  'Name is required.',              ['required'])
    ->field('s1-email', 'Valid email required.',           ['required', 'email']);

$step = $m->wizardStep('step1', 'Your Details')
    ->content((string)$stepForm . (string)$stepValidator)
    ->useValidator('step1-form');

Hidden Fields & Raw HTML

->hidden() injects a <input type="hidden">. ->html() inserts arbitrary markup — useful for captcha images, card wrappers, or any content that doesn't fit the standard field pattern. Complex multi-section forms can capture their body via ob_start()/ob_get_clean() and pass the result to ->html(), letting the Form manage the outer tag and CSRF.

// hidden() injects a hidden input
<?php
$form = $m->form('editRecord')
    ->action('/records/save')
    ->hidden('record_id', (string)$record['id'])
    ->field($m->textbox('r-title')->name('title'), 'Title', ['required']);
$form->submit('Save', 'fa-save')->primary();
echo $form;

// html() — useful for captcha images or card-wrapped sections
<?php
ob_start();
echo $m->card('sectionCard')->sectionHeader('Details')->content($detailsHtml);
$bodyHtml = ob_get_clean();

$form = $m->form('complexForm')
    ->action('/save')
    ->html($bodyHtml)
    ->cancel('Cancel', '/back');
$form->submit('Save', 'fa-save')->primary();
echo $form;

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->form($id)`	`string`	Create a Form. The `$id` is also used as the form's `name` attribute.
`->action($url)`	`string`	Form `action` URL. Defaults to empty (submits to current page).
`->method($method)`	`string`	HTTP method: `post` (default), `get`, `put`, `delete`. PUT/DELETE emit a hidden `_method` field.
`->name($name)`	`string`	Override the form `name` attribute. Defaults to the ID.
`->model($data)`	`array\|object`	Bind an associative array or object to pre-populate field values. Keys are matched to component `name()` attributes.
`->field($component, $label, $rules, $errorMessage, $hint, $wrapperClass)`	`Component, string, array, string, string, string`	Add a field wrapped in a `form-group` div. `$rules` drive the auto-Validator; `$errorMessage` overrides the label-derived default; `$hint` is small text shown below the field; required fields show a red asterisk.
`->hidden($name, $value)`	`string, string`	Inject a `<input type="hidden">`.
`->html($html)`	`string`	Insert raw HTML at the current position in the field list.
`->submit($text, $icon)`	`string, string`	Add a submit button. Returns a `Button` instance for further fluent configuration (e.g. `->primary()`). Echo the Form variable to render full HTML — not the Button return value.
`->cancel($text, $href, $icon)`	`string, string, string`	Add a cancel action. With `$href`: renders as `<a href="…">`. Without: `onclick="history.back()"`. Defaults: text Cancel, icon `fa-times`. Returns `self`.
`->reset($text, $icon)`	`string, string`	Add a `type="reset"` button. Defaults: text Reset, icon `fa-undo`. Returns `self`.
`->layout($layout)`	`string`	Form layout: `vertical` (default), `horizontal`, `inline`.
`->ajax()`		Set `data-m-ajax="true"` on the form element.
`->noValidation()`		Suppress the auto-generated client-side Validator.
`->noCsrf()`		Suppress the automatic `csrf_token` hidden input (injected by default on POST/PUT/DELETE).
`->formAttr($name, $value)`	`string, string`	Add an arbitrary attribute to the `<form>` element (e.g. `onsubmit`, `enctype`, `autocomplete`).