Forms
Build a form: a fragment in the template, a POST route that validates, and the same fragment sent back with errors under each field.
On this page
A form is a page, a route and a block. The page's template holds the form as a fragment, a POST route reads and validates the input, and a failed POST renders the same fragment again with what was posted and what went wrong. No JSON passes between the browser and the server, and the form works the same on a full page load.
The form
The form is a self-targeting fragment: n:fragment on an element with an id makes the whole element a block named contact, reachable at /contact:contact and swapped back over #contact. hx-post sends the form to that block URL. {ui field} wraps a control with its label, a hint and an error, which replaces the hint. The control inside it takes the posted value and invalid, which marks it.
{default $values = [], $errors = []}
<form
id="contact"
n:fragment
hx-post="{$page->url()}:contact"
class="flex flex-col gap-4"
>
{ui field,
name: 'email',
label: 'Email',
error: $errors['email'] ?? null,
}
{ui input,
name: 'email',
type: 'email',
value: $values['email'] ?? '',
invalid: (bool) ($errors['email'] ?? null),
required: true,
/}
{/ui}
{ui field,
name: 'message',
label: 'Message',
error: $errors['message'] ?? null,
}
{ui textarea,
name: 'message',
value: $values['message'] ?? '',
invalid: (bool) ($errors['message'] ?? null),
required: true,
/}
{/ui}
{ui button, title: 'Send', type: 'submit' /}
</form>
{default} gives the first render empty values and no errors, so the template needs no controller.
The route
The handler reads each value through $app->request->post() and cleans it with San, then collects every failing field with V::check(). Each field maps to [passes, message] pairs and keeps the first message that fails, which is the shape {ui field} shows. When any field fails, $app->send() renders the current page again. It takes the block from the request URL, so only the form comes back, and its data is merged over the template's variables:
<?php
use Phlat\App;
use Phlat\Page;
use Phlat\Toolkit\San;
use Phlat\Toolkit\V;
return function (App $app, Page $page): void {
$page->router->get('', fn() => $page);
$page->router->post('', function () use ($app, $page) {
$values = [
'email' => San::text($app->request->post('email') ?? ''),
'message' => San::text($app->request->post('message') ?? ''),
];
$errors = V::check([
'email' => [
[V::required($values['email']), 'Required'],
[V::email($values['email']), 'Not an email address'],
],
'message' => [[V::required($values['message']), 'Required']],
]);
if ($errors)
$app->send(data: ['values' => $values, 'errors' => $errors]);
$app->email()
->to('[email protected]')
->replyTo($values['email'])
->subject('Contact form')
->text($values['message'])
->send();
$page->session()->flash('flash', 'Thanks, your message is sent.');
$app->redirect($page->url());
});
};
A form that works is finished with a redirect. A flash message survives it, and over HTMX $app->redirect() sends HX-Redirect, so the browser loads the page that shows the result.
Errors that are not field errors
Throw a typed exception for a request that no valid form could have sent, such as a missing record or a forbidden action. ValidationException takes a message, which the error template shows in an alert. It also carries an errors array keyed by field, but the error template does not place those under their fields, so a form that wants inline errors catches the failure or runs V::check() itself and renders the fragment again, as above.
Forms for fields you have declared
A form for a page or a user needs no rules of its own: the record's field set validates itself. $user->fields()->fill($app->request) returns the set with the posted values, valid() says whether every rule passed, and withErrors() adds a failure of your own, such as a password that does not match. The dash edits pages and profiles this way. Use V::check() for a form that is not backed by a record.