Built-in validators and the
#[Validate] attribute
Extbase ships a set of validators that cover the most common input constraints.
They are attached to action parameters and model properties using the
# attribute. Multiple
# attributes on the
same target are treated as a conjunction. All of them must pass.
On this page
Syntax of the
#[Validate] attribute
The attribute takes the validator name as its first argument and an optional
options array:
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:
// 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
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:
#[Validate('NotEmpty')]
#[Validate('EmailAddress')]
protected string $contactEmail = '';Without NotEmpty, an empty string can silently pass EmailAddress
validation above.
Built-in validator 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.
NotEmpty
Rejects
null, empty strings, empty arrays, and
Countable 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\
| 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
Checks that a string's character count (measured in UTF-8 characters) is
within the given bounds. Objects with a
__ method are
accepted and cast automatically.
Class:
\TYPO3\
| Option | Default | Description |
|---|---|---|
minimum | 0 | Minimum number of characters required. |
maximum | PHP_INT_MAX | Maximum number of characters allowed. |
NumberRange
Checks that a numeric value falls within a given range (inclusive). If
minimum is greater than maximum, the values are swapped silently.
Class:
\TYPO3\
| Option | Default | Description |
|---|---|---|
minimum | 0 | Minimum value accepted. |
maximum | PHP_INT_MAX | Maximum value accepted. |
RegularExpression
Validates a value against a
PCRE regular expression.
The expression is passed to
preg_. Include the
delimiters.
Class:
\TYPO3\
| Option | Default | Description |
|---|---|---|
regularExpression | (required) | The full PCRE pattern including delimiters, for example, '/^[a-z]+$/i'. |
#[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:
#[Validate('RegularExpression', options: [
'regularExpression' => '/^[a-z0-9\-]+$/',
'message' => 'my_extension.messages:error.slug.invalidCharacters',
])]
protected string $slug = '';EmailAddress
Checks that the value is a syntactically valid email address using
General.
Class:
\TYPO3\
No options beyond the optional message override (see
Customising error messages).
Url
Checks that the value is a valid URL using
General.
Class:
\TYPO3\
No options beyond the optional message override.
Text
Checks that the value does not contain HTML or XML tags (that is, the value equals
strip_). Useful for plain-text fields that should not accept
markup.
Class:
\TYPO3\
No options beyond the optional message override.
Alphanumeric
Checks that a value contains alphanumeric characters only (letters and digits). The exact character set depends on the locale.
Class:
\TYPO3\
No options beyond the optional message override.
Integer
Checks that a value is a valid integer (or a string that represents one).
Class:
\TYPO3\
No options beyond the optional message override.
Float
Checks that a value is a valid floating-point number (or a string that represents one).
Class:
\TYPO3\
No options beyond the optional message override.
Number
Checks that a value is numeric. It accepts both integers and floats.
Class:
\TYPO3\
No options beyond the optional message override.
Boolean
Checks that a value is a boolean. Useful for checkboxes where the mapping
must produce exactly
true or
false.
Class:
\TYPO3\
No options beyond the optional message override.
DateTime
Checks that a value is a
\Date or
\Date
instance. Typically used after property mapping has converted a string
to a date object.
Class:
\TYPO3\
No options beyond the optional message override.
File upload validators
The following validators are specifically designed for
\TYPO3\ instances or
Object collections of uploaded
files. They are used in conjunction with the
# attribute on
action parameters.
FileExtension
Checks that the uploaded file has an allowed file extension.
Class:
\TYPO3\
| Option | Description |
|---|---|
allowedExtensions | Comma-separated list of allowed file extensions without the leading dot,
for example 'jpg,jpeg,png'. |
FileSize
Checks that the uploaded file size falls within a given range.
Class:
\TYPO3\
| 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
Checks that the uploaded file's MIME type is in the allowed list.
Class:
\TYPO3\
| Option | Description |
|---|---|
allowedMimeTypes | Array of allowed MIME type strings, for example
['image/jpeg', 'image/png']. |
ImageDimensions
Checks that an uploaded image's width and height fall within the given bounds.
Class:
\TYPO3\
| Option | Description |
|---|---|
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
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\
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
Rejects uploaded files whose name matches dangerous executable extensions
(such as .php, .phar, .exe). The default pattern is derived from
TYPO3's fileDenyPattern configuration.
Class:
\TYPO3\
| Option | Description |
|---|---|
regularExpression | A PCRE pattern the file name must match. |
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 (FileExtension)
instead, which is designed for that purpose.
See also
File uploads in Extbase domain models — how to wire up upload handling with
#, configure validators, and handle deletion.
Customising error 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
$exceed becomes the exceedMessage option,
$null becomes nullMessage. Validators with only one error
condition use the generic message key. To find all available keys for a
given validator, check its
$supported array in the source at
EXT:.
#[Validate('NotEmpty', options: [
'nullMessage' => 'my_extension.messages:error.title.required',
])]
protected string $title = '';#[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
- Writing a custom Extbase validator — write a validator for domain rules that the built-in validators cannot express.
- Validation in Extbase — how validation fits into the request
lifecycle and how
erroris triggered.Action ()