# FormModelInterface

> Defines the contract for form models with validation metadata and field errors.

[API reference](/docs/api/index.md) › [Form Model](/docs/extensions/form-model/reference/index.md) › FormModelInterface

| interface | `UIAwesome\FormModel\FormModelInterface` |
| --- | --- |
| Extends | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| Source | [`src/FormModelInterface.php`](https://github.com/ui-awesome/form-model/blob/main/src/FormModelInterface.php#L23) |

Implemented by 1 type:

- [`BaseFormModel`](/docs/extensions/form-model/reference/baseformmodel/index.md)

Defines the contract for form models with validation metadata and field errors.

Usage example:
```php
final class UserForm extends BaseFormModel
{
    public string $email = '';
}

$form = new UserForm();
$form->addError('email', 'Email is invalid.');
```

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-add"></span>[`add()`](/docs/extensions/model/reference/modelinterface/index.md#method-add) abstract | Adds a new property to the model. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| [`addError()`](#method-addError) abstract | Adds an error for a field. | `FormModelInterface` |
| [`clearError()`](#method-clearError) abstract | Clears errors for one field or all fields. | `FormModelInterface` |
| <span id="method-getData"></span>[`getData()`](/docs/extensions/model/reference/modelinterface/index.md#method-getData) abstract | Returns the raw data for the model. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| [`getError()`](#method-getError) abstract | Returns errors for one field. | `FormModelInterface` |
| [`getErrors()`](#method-getErrors) abstract | Returns validation errors indexed by field name. | `FormModelInterface` |
| [`getErrorSummary()`](#method-getErrorSummary) abstract | Returns a flattened error summary. | `FormModelInterface` |
| [`getFieldConfig()`](#method-getFieldConfig) abstract | Returns the field configuration for one field. | `FormModelInterface` |
| [`getFieldConfigs()`](#method-getFieldConfigs) abstract | Returns field configuration arrays indexed by field name. | `FormModelInterface` |
| [`getFirstError()`](#method-getFirstError) abstract | Returns the first error for one field. | `FormModelInterface` |
| [`getFirstErrors()`](#method-getFirstErrors) abstract | Returns the first validation error indexed by field name. | `FormModelInterface` |
| [`getHint()`](#method-getHint) abstract | Returns the hint text for one field. | `FormModelInterface` |
| [`getHints()`](#method-getHints) abstract | Returns hint text indexed by field name. | `FormModelInterface` |
| [`getLabel()`](#method-getLabel) abstract | Returns the label text for one field. | `FormModelInterface` |
| [`getLabels()`](#method-getLabels) abstract | Returns label text indexed by field name. | `FormModelInterface` |
| <span id="method-getModelName"></span>[`getModelName()`](/docs/extensions/model/reference/modelinterface/index.md#method-getModelName) abstract | Returns the model name that this model class should use. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| <span id="method-getNames"></span>[`getNames()`](/docs/extensions/model/reference/modelinterface/index.md#method-getNames) abstract | Returns the list of property names. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| [`getPlaceholder()`](#method-getPlaceholder) abstract | Returns the placeholder text for one field. | `FormModelInterface` |
| [`getPlaceholders()`](#method-getPlaceholders) abstract | Returns placeholder text indexed by field name. | `FormModelInterface` |
| [`getRule()`](#method-getRule) abstract | Returns validation rules for one field. | `FormModelInterface` |
| [`getRules()`](#method-getRules) abstract | Returns validation rules indexed by field name. | `FormModelInterface` |
| <span id="method-getTypes"></span>[`getTypes()`](/docs/extensions/model/reference/modelinterface/index.md#method-getTypes) abstract | Returns the list of property types indexed by property names. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| <span id="method-getValue"></span>[`getValue()`](/docs/extensions/model/reference/modelinterface/index.md#method-getValue) abstract | Returns the value (raw data) for the specified property. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| <span id="method-has"></span>[`has()`](/docs/extensions/model/reference/modelinterface/index.md#method-has) abstract | Checks if the model has the specified property. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| [`hasError()`](#method-hasError) abstract | Checks whether errors exist. | `FormModelInterface` |
| <span id="method-isEmpty"></span>[`isEmpty()`](/docs/extensions/model/reference/modelinterface/index.md#method-isEmpty) abstract | Whether the model has no loaded raw data. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| <span id="method-isType"></span>[`isType()`](/docs/extensions/model/reference/modelinterface/index.md#method-isType) abstract | Checks if the property is of the specified type. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| [`isValidated()`](#method-isValidated) abstract | Checks whether a field has been validated successfully. | `FormModelInterface` |
| <span id="method-load"></span>[`load()`](/docs/extensions/model/reference/modelinterface/index.md#method-load) abstract | Populates the model with input data. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| [`setErrors()`](#method-setErrors) abstract | Replaces all field errors. | `FormModelInterface` |
| <span id="method-setValue"></span>[`setValue()`](/docs/extensions/model/reference/modelinterface/index.md#method-setValue) abstract | Sets the value for the specified property. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| <span id="method-setValues"></span>[`setValues()`](/docs/extensions/model/reference/modelinterface/index.md#method-setValues) abstract | Sets values for multiple properties. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |
| <span id="method-toArray"></span>[`toArray()`](/docs/extensions/model/reference/modelinterface/index.md#method-toArray) abstract | Returns model properties as an array. | [`UIAwesome\Model\ModelInterface`](/docs/extensions/model/reference/modelinterface/index.md) |

## Method details

### addError() <span id="method-addError"></span>

```php
abstract public function addError(string $field, string $error): void
```

Adds an error for a field.

Usage example:
```php
$form->addError('email', 'Email is invalid.');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |
| `$error` | `string` | Error message to append. |

### clearError() <span id="method-clearError"></span>

```php
abstract public function clearError(string|null $field = null): void
```

Clears errors for one field or all fields.

Usage example:
```php
$form->clearError('email');
$form->clearError();
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string\|null` | Field name, or `null` to clear all fields. |

### getError() <span id="method-getError"></span>

```php
abstract public function getError(string $field): array<int, string>
```

Returns errors for one field.

Usage example:
```php
$errors = $form->getError('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`array<int, string>`: Error list for the field.

### getErrors() <span id="method-getErrors"></span>

```php
abstract public function getErrors(): array<string, array<int, string>>
```

Returns validation errors indexed by field name.

Usage example:
```php
$allErrors = $form->getErrors();
```

**Returns**

`array<string, array<int, string>>`: Errors indexed by field name. Returns an empty array when no errors exist.

### getErrorSummary() <span id="method-getErrorSummary"></span>

```php
abstract public function getErrorSummary(list<string> $onlyFields = [], bool $first = false): array<int|string, string>
```

Returns a flattened error summary.

Usage example:
```php
$summary = $form->getErrorSummary(['email', 'username']);
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$onlyFields` | `list<string>` | Fields to include. Uses all fields when the list is empty. |
| `$first` | `bool` | Whether to return only the first error of each field. |

**Returns**

`array<int|string, string>`: Flat list of error messages when `$first` is `false`; field-indexed first errors when `$first` is `true`.

### getFieldConfig() <span id="method-getFieldConfig"></span>

```php
abstract public function getFieldConfig(string $field): array<string, mixed>
```

Returns the field configuration for one field.

A field configuration maps a method name to the argument, or list of arguments, applied to the field or to the
widget that renders it.

Usage example:
```php
$emailFieldConfig = $form->getFieldConfig('email');
// ['class' => ['w-full rounded-md']]
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`array<string, mixed>`: Field configuration for the field. Returns an empty array when the field has no configuration.

### getFieldConfigs() <span id="method-getFieldConfigs"></span>

```php
abstract public function getFieldConfigs(): array<string, array<string, mixed>>
```

Returns field configuration arrays indexed by field name.

Each configuration maps a method name to the argument, or list of arguments, applied to the field or to the
widget that renders it.

Usage example:
```php
$fieldConfig = $form->getFieldConfigs();
// ['email' => ['class' => ['w-full rounded-md']]]
```

**Returns**

`array<string, array<string, mixed>>`: Field configuration arrays indexed by field name.

### getFirstError() <span id="method-getFirstError"></span>

```php
abstract public function getFirstError(string $field): string
```

Returns the first error for one field.

Usage example:
```php
$firstError = $form->getFirstError('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`string`: First error for the field, or an empty string when no errors exist.

### getFirstErrors() <span id="method-getFirstErrors"></span>

```php
abstract public function getFirstErrors(): array<string, string>
```

Returns the first validation error indexed by field name.

Usage example:
```php
$firstErrors = $form->getFirstErrors();
```

**Returns**

`array<string, string>`: First errors indexed by field name. Returns an empty array when no errors exist.

### getHint() <span id="method-getHint"></span>

```php
abstract public function getHint(string $field): string
```

Returns the hint text for one field.

Usage example:
```php
$hint = $form->getHint('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`string`: Hint text for the field.

### getHints() <span id="method-getHints"></span>

```php
abstract public function getHints(): array<string, string>
```

Returns hint text indexed by field name.

Usage example:
```php
$hints = $form->getHints();
```

**Returns**

`array<string, string>`: Hint text indexed by field name.

### getLabel() <span id="method-getLabel"></span>

```php
abstract public function getLabel(string $field): string
```

Returns the label text for one field.

Usage example:
```php
$label = $form->getLabel('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`string`: Label text for the field.

### getLabels() <span id="method-getLabels"></span>

```php
abstract public function getLabels(): array<string, string>
```

Returns label text indexed by field name.

Usage example:
```php
$labels = $form->getLabels();
```

**Returns**

`array<string, string>`: Label text indexed by field name.

### getPlaceholder() <span id="method-getPlaceholder"></span>

```php
abstract public function getPlaceholder(string $field): string
```

Returns the placeholder text for one field.

Usage example:
```php
$placeholder = $form->getPlaceholder('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`string`: Placeholder text for the field.

### getPlaceholders() <span id="method-getPlaceholders"></span>

```php
abstract public function getPlaceholders(): array<string, string>
```

Returns placeholder text indexed by field name.

Usage example:
```php
$placeholders = $form->getPlaceholders();
```

**Returns**

`array<string, string>`: Placeholder text indexed by field name.

### getRule() <span id="method-getRule"></span>

```php
abstract public function getRule(string $field): array<mixed, mixed>|null
```

Returns validation rules for one field.

Usage example:
```php
$emailRules = $form->getRule('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`array<mixed, mixed>|null`: Validation rules for the field, or `null` when no rules are defined.

### getRules() <span id="method-getRules"></span>

```php
abstract public function getRules(): iterable<string, array<mixed, mixed>>
```

Returns validation rules indexed by field name.

Usage example:
```php
$rules = $form->getRules();
```

**Returns**

`iterable<string, array<mixed, mixed>>`: Validation rules indexed by field name.

### hasError() <span id="method-hasError"></span>

```php
abstract public function hasError(string|null $field = null): bool
```

Checks whether errors exist.

Usage example:
```php
$hasAnyError = $form->hasError();
$hasEmailError = $form->hasError('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string\|null` | Field name, or `null` to check all fields. |

**Returns**

`bool`: `true` if errors exist, otherwise `false`.

### isValidated() <span id="method-isValidated"></span>

```php
abstract public function isValidated(string $field): bool
```

Checks whether a field has been validated successfully.

Usage example:
```php
$isValid = $form->isValidated('email');
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |

**Returns**

`bool`: `true` if the field exists in the error map with no messages, otherwise `false`.

### setErrors() <span id="method-setErrors"></span>

```php
abstract public function setErrors(array<string, array<int, string>> $values): void
```

Replaces all field errors.

Usage example:
```php
$form->setErrors(['email' => ['Email is invalid.']]);
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$values` | `array<string, array<int, string>>` | Error messages indexed by field name. |