README

Form Model for PHP

Form metadata and validation errors for model-driven PHP forms
Hints, labels, placeholders, field configuration, nested field metadata, and field-scoped error handling

Features

Installation

composer require ui-awesome/form-model:^0.2

Quick start

<?php

declare(strict_types=1);

namespace App\FormModel;

use UIAwesome\FormModel\BaseFormModel;
use UIAwesome\FormModel\Attribute\{FieldConfig, Hint, Label, Placeholder};

final class SignInForm extends BaseFormModel
{
    #[Hint('Use your account email address.')]
    #[Label('Email address')]
    #[Placeholder('name@example.com')]
    #[FieldConfig(['class' => ['w-full rounded-md border border-slate-300 px-3 py-2']])]
    public string $email = '';

    public string $password = '';

    public function getHints(): array
    {
        return [
            'password' => 'Use at least 8 characters.',
        ];
    }

    public function getLabels(): array
    {
        return [
            'password' => 'Password',
        ];
    }

    public function getPlaceholders(): array
    {
        return [
            'password' => 'Enter your password',
        ];
    }

    public function getRules(): array
    {
        return [
            'email' => ['required', 'email'],
            'password' => ['required', 'string'],
        ];
    }

    public function getFieldConfigs(): array
    {
        return [
            'password' => [
                'class' => ['w-full rounded-md border border-slate-300 px-3 py-2'],
            ],
        ];
    }
}

$form = new SignInForm();

$form->addError('email', 'Email is required.');
$errors = $form->getErrors();
/*
[
    'email' => ['Email is required.'],
]
*/

$summary = $form->getErrorSummary();
// ['Email is required.']

$label = $form->getLabel('email');
// 'Email address'

Nested field metadata

You can request metadata using dot notation when a field contains another BaseFormModel.

$hint = $form->getHint('profile.address.city');
$label = $form->getLabel('profile.address.city');
$placeholder = $form->getPlaceholder('profile.address.city');
$rules = $form->getRule('profile.address.city');

Property attributes

Property attributes are resolved first for metadata (Hint, Label, Placeholder, FieldConfig). Map methods (getHints(), getLabels(), getPlaceholders(), getFieldConfigs()) remain as fallback.

$emailHint = $form->getHint('email');
$emailLabel = $form->getLabel('email');
$emailPlaceholder = $form->getPlaceholder('email');
$emailFieldConfig = $form->getFieldConfig('email');

Error collection and first-error mode

Use first-error mode when you need one message per field.

$form->setErrors(
    [
        'email' => ['Email is required.', 'Email is invalid.'],
        'password' => ['Password is required.'],
    ],
);

$firstErrors = $form->getFirstErrors();
/*
[
    'email' => 'Email is required.',
    'password' => 'Password is required.',
]
*/