# FieldError

> Stores and queries validation errors by field.

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

| final class | `UIAwesome\FormModel\FieldError` |
| --- | --- |
| Source | [`src/FieldError.php`](https://github.com/ui-awesome/form-model/blob/main/src/FieldError.php#L22) |

Stores and queries validation errors by field.

Usage example:
```php
$errors = new FieldError();
$errors->add('email', 'Email is invalid.');
$firstEmailError = $errors->getField('email', true);
```

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`add()`](#method-add) | Adds an error message for a field. | `FieldError` |
| [`clear()`](#method-clear) | Clears errors for one field or all fields. | `FieldError` |
| [`get()`](#method-get) | Returns validation errors indexed by field name. | `FieldError` |
| [`getAll()`](#method-getAll) | Returns all errors indexed by field name. | `FieldError` |
| [`getAllFirst()`](#method-getAllFirst) | Returns the first error for each field. | `FieldError` |
| [`getField()`](#method-getField) | Returns errors for a single field. | `FieldError` |
| [`getFirstForField()`](#method-getFirstForField) | Returns the first error for one field. | `FieldError` |
| [`getForField()`](#method-getForField) | Returns all errors for one field. | `FieldError` |
| [`getSummary()`](#method-getSummary) | Returns a flattened error summary. | `FieldError` |
| [`has()`](#method-has) | Checks whether errors exist. | `FieldError` |
| [`isValidated()`](#method-isValidated) | Checks whether a field has been validated successfully. | `FieldError` |
| [`set()`](#method-set) | Replaces the full error collection. | `FieldError` |

## Method details

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

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

Adds an error message for a field.

Usage example:
```php
$errors->add('username', 'Username is required.');
```

**Parameters**

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

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

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

Clears errors for one field or all fields.

Usage example:
```php
$errors->clear('email');
$errors->clear();
```

**Parameters**

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

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

```php
public function get(bool $first = false): array<string, array<int, string>|string>
```

Returns validation errors indexed by field name.

Usage example:
```php
$allErrors = $errors->get();
$firstErrors = $errors->get(true);
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$first` | `bool` | Whether to return only the first error for each field. |

**Returns**

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

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

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

Returns all errors indexed by field name.

**Returns**

`array<string, array<int, string>>`: Non-empty errors indexed by field name.

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

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

Returns the first error for each field.

**Returns**

`array<string, string>`: First errors indexed by field name.

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

```php
public function getField(string $field, bool $first = false): array<int, string>|string
```

Returns errors for a single field.

Usage example:
```php
$emailErrors = $errors->getField('email');
$firstEmailError = $errors->getField('email', true);
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` | Field name. |
| `$first` | `bool` | Whether to return only the first error. |

**Returns**

`array<int, string>|string`: Error list for the field, or the first error when `$first` is `true`.

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

```php
public function getFirstForField(string $field): string
```

Returns the first error for one field.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` |  |

**Returns**

`string`

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

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

Returns all errors for one field.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$field` | `string` |  |

**Returns**

`array<int, string>`: Errors for the requested field.

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

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

Returns a flattened error summary.

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

**Parameters**

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

**Returns**

`array<int|string, string>`: Flat list of error messages.

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

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

Checks whether errors exist.

Usage example:
```php
$hasAny = $errors->has();
$hasEmailErrors = $errors->has('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
public function isValidated(string $field): bool
```

Checks whether a field has been validated successfully.

Usage example:
```php
$isValidated = $errors->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`.

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

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

Replaces the full error collection.

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

**Parameters**

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