---
title: "Built-in validators and the #[Validate] attribute"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:extbase-validator-disjunction@main"
source: "ExtensionArchitecture/Extbase/Validation/BuiltIn.rst"
rendered: "2026-09-20T15:52:37+00:00"
---

# Built-in validators and the `#[Validate]` attribute {#extbase-validator-disjunction}

Extbase ships a set of validators that cover the most common input constraints.
They are attached to action parameters and model properties using the
`#[Validate]` attribute. Multiple `#[Validate]` attributes on the
same target are treated as a conjunction. All of them must pass.

**On this page**

-   [Syntax of the #[Validate] attribute](https://docs.typo3.org/permalink/t3coreapi:syntax-of-the-validate-attribute@main)
-   [Empty values and the acceptsEmptyValues flag](https://docs.typo3.org/permalink/t3coreapi:empty-values-and-the-acceptsemptyvalues-flag@main)
-   [Built-in validator reference](https://docs.typo3.org/permalink/t3coreapi:built-in-validator-reference@main)
-   [File upload validators](https://docs.typo3.org/permalink/t3coreapi:file-upload-validators@main)
-   [Customising error messages](https://docs.typo3.org/permalink/t3coreapi:customising-error-messages@main)
-   [What to read next](https://docs.typo3.org/permalink/t3coreapi:what-to-read-next@main)

## Syntax of the `#[Validate]` attribute {#extbase-validator-multiple-example}

The attribute takes the validator name as its first argument and an optional
`options` array:

**EXT:my_extension/Classes/Domain/Model/Conference.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Model;

use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

class Conference extends AbstractEntity
{
  #[Validate('NotEmpty')]
  #[Validate('StringLength', options: ['minimum' => 3, 'maximum' => 255])]
  protected string $title = '';

  #[Validate('EmailAddress')]
  protected string $contactEmail = '';
}

```

The validator name can be either a short name (for built-in validators listed
below) or a fully qualified class name for [custom validators](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-custom@main):

**Short name vs. fully qualified class name**

```php
// Short name — built-in validators only
#[Validate('NotEmpty')]

// Fully qualified class name — required for custom validators
#[Validate(\MyVendor\MyExtension\Validation\Validator\SlugValidator::class)]
```

## Empty values and the `acceptsEmptyValues` flag {#extbase-validation-builtin-empty}

Most built-in validators skip validation if the value is `null` or an
empty string. This is intentional: a blank field is different
to a field being in the wrong format. Add `NotEmpty` to make sure
a field exists *and* that it is well-formed:

**Requiring a non-empty, correctly formatted email address**

```php
#[Validate('NotEmpty')]
#[Validate('EmailAddress')]
protected string $contactEmail = '';
```

Without `NotEmpty`, an empty string can silently pass `EmailAddress`
validation above.

## Built-in validator reference {#extbase-validation-builtin-reference}

The following validators are provided out of the box. This list covers the
validators available for general use. File upload validators are listed
separately in [File upload validators](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-builtin-file@main).

### `NotEmpty` {#extbase-validator-notempty}

Rejects `null`, empty strings, empty arrays, and
[Countable](https://www.php.net/manual/en/class.countable.php) objects with
a count of zero. This is the only built-in validator that does not accept
empty values. It is always executed.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\NotEmptyValidator`

| Option | Default | Description |
| --- | --- | --- |
| `nullMessage` | built-in | Translation key or message shown when the value is `null`. |
| `emptyMessage` | built-in | Translation key or message shown when the value is empty. |

### `StringLength` {#extbase-validator-stringlength}

Checks that a string's character count (measured in UTF-8 characters) is
within the given bounds. Objects with a `__toString()` method are
accepted and cast automatically.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\StringLengthValidator`

| Option | Default | Description |
| --- | --- | --- |
| `minimum` | `0` | Minimum number of characters required. |
| `maximum` | `PHP_INT_MAX` | Maximum number of characters allowed. |

### `NumberRange` {#extbase-validator-numberrange-options}

Checks that a numeric value falls within a given range (inclusive). If
`minimum` is greater than `maximum`, the values are swapped silently.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\NumberRangeValidator`

| Option | Default | Description |
| --- | --- | --- |
| `minimum` | `0` | Minimum value accepted. |
| `maximum` | `PHP_INT_MAX` | Maximum value accepted. |

### `RegularExpression` {#extbase-validator-regularexpression-use-cases}

Validates a value against a
[PCRE regular expression](https://www.php.net/manual/en/book.pcre.php).
The expression is passed to `preg_match()`. Include the
delimiters.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\RegularExpressionValidator`

| Option | Default | Description |
| --- | --- | --- |
| `regularExpression` | *(required)* | The full PCRE pattern including delimiters, for example, `'/^[a-z]+$/i'`. |

**Restricting a slug to lowercase letters and hyphens**

```php
#[Validate('RegularExpression', options: ['regularExpression' => '/^[a-z0-9\-]+$/'])]
protected string $slug = '';
```

> [!TIP]
> The default error message for `RegularExpression` is the generic "The
> given subject did not match the pattern". Consider overriding it with a
> `message` option that tells the visitor what the field actually expects:
>
> **RegularExpression with a descriptive error message**
>
> ```php
> #[Validate('RegularExpression', options: [
>     'regularExpression' => '/^[a-z0-9\-]+$/',
>     'message' => 'my_extension.messages:error.slug.invalidCharacters',
> ])]
> protected string $slug = '';
> ```

### `EmailAddress` {#extbase-validator-emailaddress}

Checks that the value is a syntactically valid email address using
`GeneralUtility::validEmail()`.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\EmailAddressValidator`

No options beyond the optional `message` override (see
[Customising error messages](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-builtin-custom-messages@main)).

### Url {#extbase-validator-url-use-cases}

Checks that the value is a valid URL using `GeneralUtility::isValidUrl()`.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\UrlValidator`

No options beyond the optional `message` override.

### Text {#extbase-validator-text}

Checks that the value does not contain HTML or XML tags (that is, the value equals
`strip_tags($value)`). Useful for plain-text fields that should not accept
markup.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\TextValidator`

No options beyond the optional `message` override.

### Alphanumeric {#extbase-validator-alphanumeric}

Checks that a value contains alphanumeric characters only (letters and
digits). The exact character set depends on the locale.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\AlphanumericValidator`

No options beyond the optional `message` override.

### Integer {#extbase-validator-integer}

Checks that a value is a valid integer (or a string that represents one).

Class: `\TYPO3\CMS\Extbase\Validation\Validator\IntegerValidator`

No options beyond the optional `message` override.

### Float {#extbase-validator-float}

Checks that a value is a valid floating-point number (or a string that
represents one).

Class: `\TYPO3\CMS\Extbase\Validation\Validator\FloatValidator`

No options beyond the optional `message` override.

### Number {#extbase-validation-builtin-number}

Checks that a value is numeric. It accepts both integers and floats.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\NumberValidator`

No options beyond the optional `message` override.

### Boolean {#extbase-validator-boolean}

Checks that a value is a boolean. Useful for checkboxes where the mapping
must produce exactly `true` or `false`.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\BooleanValidator`

No options beyond the optional `message` override.

### `DateTime` {#extbase-validator-datetime}

Checks that a value is a `\DateTime` or `\DateTimeImmutable`
instance. Typically used after property mapping has converted a string
to a date object.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\DateTimeValidator`

No options beyond the optional `message` override.

## File upload validators {#extbase-validation-builtin-file}

<!-- TODO: no Markdown rendering for "versionadded" -->

See Feature: #104526 - Provide validators for PSR-7 UploadedFile objects in Extbase.

The following validators are specifically designed for
`\TYPO3\CMS\Core\Http\UploadedFile` instances or
`ObjectStorage` collections of uploaded
files. They are used in conjunction with the `#[FileUpload]` attribute on
action parameters.

### `FileExtension` {#extbase-validation-builtin-fileextension}

Checks that the uploaded file has an allowed file extension.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\FileExtensionValidator`

| Option | Description |
| --- | --- |
| `allowedExtensions` | Comma-separated list of allowed file extensions without the leading dot, for example `'jpg,jpeg,png'`. |
| `useStorageDefaults` | If set to `true`, also allows the file extensions configured in `$GLOBALS['TYPO3_CONF_VARS']['SYS']['textfile_ext']`, `['mediafile_ext']` and `['miscfile_ext']`. |

At least one of `allowedFileExtensions` or `useStorageDefaults` must be
set.

### `FileSize` {#extbase-validator-file-size}

Checks that the uploaded file size falls within a given range.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\FileSizeValidator`

| Option | Description |
| --- | --- |
| `minimum` | Minimum file size as a string with unit, for example `'0B'`. |
| `maximum` | Maximum file size as a string with unit, for example `'5M'`. |

### `MimeType` {#extbase-validator-mime-type}

Checks that the uploaded file's MIME type is in the allowed list.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\MimeTypeValidator`

| Option | Description |
| --- | --- |
| `allowedMimeTypes` | Array of allowed MIME type strings, for example `['image/jpeg', 'image/png']`. |
| `ignoreFileExtensionCheck` | If set to `true`, disables the check that the file extension matches the detected MIME type. Defaults to `false`. Be aware of the security implications of setting this to `true`. |

### `ImageDimensions` {#extbase-validator-image-dimensions}

Checks that an uploaded image's width and height fall within the given bounds.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\ImageDimensionsValidator`

| Option | Description |
| --- | --- |
| `width` | Exact required image width in pixels. Unset by default. |
| `height` | Exact required image height in pixels. Unset by default. |
| `minWidth` | Minimum image width in pixels. |
| `maxWidth` | Maximum image width in pixels. |
| `minHeight` | Minimum image height in pixels. |
| `maxHeight` | Maximum image height in pixels. |

### `FileExtensionMimeTypeConsistency` {#extbase-validation-builtin-fileextensionmimetypeconsistency}

Cross-checks that the file's extension and its detected MIME type are
consistent with each other, guarding against disguised file uploads (for
example, a PHP file renamed to `image.jpg`).

Class: `\TYPO3\CMS\Extbase\Validation\Validator\FileExtensionMimeTypeConsistencyValidator`

No configurable options.

> [!IMPORTANT]
> This validator is enforced automatically for every `#[FileUpload]`
> parameter. You do not need to declare it — and declaring it manually has
> no effect since Extbase only adds it once.

### `FileName` {#extbase-validator-file-name}

Rejects uploaded files whose name matches dangerous executable extensions
(such as `.php`, `.phar`, `.exe`). It delegates to Core's
`\TYPO3\CMS\Core\Resource\Security\FileNameValidator`, which is
driven by the global `fileDenyPattern` configuration and is not
configurable per validator instance.

Class: `\TYPO3\CMS\Extbase\Validation\Validator\FileNameValidator`

| Option | Description |
| --- | --- |
| `regularExpression` | A PCRE pattern the file name must match. |
| `message` | Error message to be shown if the validation fails. |

> [!IMPORTANT]
> `FileName` is enforced automatically for every `#[FileUpload]`
> parameter — you do not need to declare it manually. If you want to
> restrict uploads to specific extensions, use
> [FileExtension](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-builtin-fileextension@main) (`FileExtension`)
> instead, which is designed for that purpose.

> [!NOTE]
> **See also**
>
> [File uploads in Extbase domain models](https://docs.typo3.org/permalink/t3coreapi:extbase-domain-fileupload@main) — how to wire up upload handling with
> `#[FileUpload]`, configure validators, and handle deletion.

## Customising error messages {#extbase-validation-builtin-custom-messages}

Every built-in validator accepts one or more message options that replace the
default error text. Pass a plain string or a translation key.

The option key for each message is the name of the corresponding
`protected string $…Message` property in the validator class — for
example `$exceedMessage` becomes the `exceedMessage` option,
`$nullMessage` becomes `nullMessage`. Validators with only one error
condition use the generic `message` key. To find all available keys for a
given validator, check its `$supportedOptions` array in the source at
`EXT:extbase/Classes/Validation/Validator/`.

**Custom message via translation key**

```php
#[Validate('NotEmpty', options: [
    'nullMessage' => 'my_extension.messages:error.title.required',
])]
protected string $title = '';
```

**Custom inline message (useful during development)**

```php
#[Validate('StringLength', options: [
    'maximum' => 255,
    'exceedMessage' => 'The title must not exceed 255 characters.',
])]
protected string $title = '';
```

Using translation keys is strongly recommended for anything visible to site
visitors.

## What to read next {#extbase-validation-builtin-next}

-   [Writing a custom Extbase validator](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-custom@main) — write a validator for domain rules that
    the built-in validators cannot express.
-   [Validation in Extbase](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-overview@main) — how validation fits into the request
    lifecycle and how `errorAction()` is triggered.