# Form Model

> Form metadata and validation errors for model-driven PHP forms

Package entry: `ui-awesome/form-model`. Requires PHP `^8.3`. Checked 2026-10-25. [View the entry in the package directory](</docs/packages/ui-awesome/form-model/index.md>)

**Form metadata and validation errors for model-driven PHP forms**

_Hints, labels, placeholders, field configuration, nested field metadata, and field-scoped error handling_

## Features

![Feature Overview](https://raw.githubusercontent.com/ui-awesome/form-model/main/docs/svgs/features.svg)

## Installation

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

## Quick start

```php
<?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`.

```php
$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.

```php
$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.

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

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

## Documentation

For detailed configuration options and advanced usage.

- 📚 [Installation guide](https://github.com/ui-awesome/form-model/blob/main/docs/installation.md)
- ⚙️ [Configuration reference](https://github.com/ui-awesome/form-model/blob/main/docs/configuration.md)
- 💡 [Usage examples](https://github.com/ui-awesome/form-model/blob/main/docs/examples.md)
- 🧪 [Testing guide](https://github.com/ui-awesome/form-model/blob/main/docs/testing.md)
- 🔄 [Upgrade guide](https://github.com/ui-awesome/form-model/blob/main/UPGRADE.md)

## AI assistance

AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
of a page by appending `index.md` to its URL. The
[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill
installation, client setup and verification.

- 🤖 [`ui-awesome-form-model` skill](https://github.com/ui-awesome/form-model/blob/main/docs/agents.md):
  labels, hints, placeholders, field configuration, nested field
  paths and field-scoped errors.

See the [repository guides](#documentation), the [skill source](https://github.com/ui-awesome/form-model/blob/main/skills/ui-awesome-form-model/SKILL.md), the source PHPDoc and
the [changelog](https://github.com/ui-awesome/form-model/blob/main/CHANGELOG.md). This package stores rules and errors but does not run validation, and it does not depend
on Yii; no Yii application skill is required.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)

## License

[License](https://github.com/ui-awesome/form-model/blob/main/LICENSE)

## Package

- Source code and issues: [ui-awesome/form-model](https://github.com/ui-awesome/form-model). Star the repository if the package is useful to you.
- Composer package: [ui-awesome/form-model](https://packagist.org/packages/ui-awesome/form-model).
- Changelog: [CHANGELOG.md](https://github.com/ui-awesome/form-model/blob/main/CHANGELOG.md).