Writing a custom Extbase validator 

Structure of a custom validator 

Custom validators extend \TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator and implement a single method isValid(mixed $value): void. If a value fails validation, call $this->addError() or $this->addErrorForProperty() — do not throw an exception and do not return anything. The framework reads $this->result after isValid() returns.

Place validators in Classes/Validation/Validator/ inside your extension, following the naming convention <Subject>Validator:

<?php

namespace MyVendor\MyExtension\Validation\Validator;

use TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator;

class ConferenceDateValidator extends AbstractValidator
{
    protected string $message = 'my_extension.messages:validator.conference.endBeforeStart';

    protected array $translationOptions = ['message'];

    protected $supportedOptions = [
        'message' => [null, 'Custom translation key or message text', 'string'],
    ];

    protected function isValid(mixed $value): void
    {
        if ($value->getEndDate() <= $value->getStartDate()) {
            $this->addErrorForProperty(
                'endDate',
                $this->translateErrorMessage($this->message),
                1716299001,
            );
        }
    }
}

Key points:

• Do not declare the class as final — the same convention that applies to controllers applies here. Third parties can extend the validator.
• $acceptsEmptyValues = true (the default) means isValid() is skipped when a value is null or an empty string. Set it to false only if a validator should explicitly reject empty values (as NotEmptyValidator does).
• The error code is an arbitrary integer that must be unique across your extension. Using the Unix timestamp at the time of writing is a convenient way to generate a unique number.
• Translation keys use the domain syntax introduced in TYPO3 v14: my_extension.messages:some.key resolves to EXT:my_extension/Resources/Private/Language/locallang.xlf. See Translation domain syntax as shorter alternative to LLL:EXT: (TYPO3 v14) for the full syntax including non-default language files.

Reporting errors on a specific property 

$this->addErrorForProperty() attaches the error to a named property of the validated object rather than to the object itself. The Form.validationResults ViewHelper <f:form.validationResults> view helper can then display the message adjacent to the right form field:

<f:form.validationResults for="conference.endDate">
    <f:for each="{validationResults.errors}" as="error">
        <p class="error">{error.message}</p>
    </f:for>
</f:form.validationResults>

Use $this->addError() instead when the error applies to the whole object and does not belong to any single field.

Supporting options and substitution values in messages 

If your validator needs to be configured, for example, there needs to be a minimum seat count, declare the options in $supportedOptions. Each option contains an array with values [default, description, type]. Access resolved values using $this->options:

<?php

namespace MyVendor\MyExtension\Validation\Validator;

use TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator;

class SeatCountValidator extends AbstractValidator
{
    protected string $message = 'my_extension.messages:validator.conference.notEnoughSeats';

    protected array $translationOptions = ['message'];

    protected $supportedOptions = [
        'minimum' => [1, 'Minimum number of available seats required', 'integer'],
        'message' => [null, 'Custom translation key or message text', 'string'],
    ];

    protected function isValid(mixed $value): void
    {
        $minimum = $this->options['minimum'];
        if ($value->getAvailableSeats() < $minimum) {
            $this->addError(
                $this->translateErrorMessage($this->message, '', [$minimum]),
                1716300001,
                [$minimum],
            );
        }
    }
}

The error message in locallang.xlf uses a %s placeholder:

<trans-unit id="validator.conference.notEnoughSeats">
    <source>At least %s seat(s) must be available for registration.</source>
</trans-unit>

translateErrorMessage() accepts the values to be substituted as its third argument and passes them through vsprintf(). The same values are passed as the third argument to addError(). They are stored in the Error object for programmatic access:

$this->addError(
    $this->translateErrorMessage($this->message, '', [$minimum]),
    1716300001, // An arbitrary unique number, for example the timestamp when writing the code
    [$minimum],
);

Attach the validator with its option on the action parameter:

use MyVendor\MyExtension\Validation\Validator\SeatCountValidator;
use TYPO3\CMS\Extbase\Attribute\Validate;

public function registerAction(
    #[Validate(SeatCountValidator::class, options: ['minimum' => 1])]
    Conference $conference,
): ResponseInterface {
    // Only reached when SeatCountValidator passes
}

Making the error message overridable 

To allow callers to override the message text via the options array without having to subclass (the same mechanism used by built-in validators) declare a protected string $message property, add it to $translationOptions, and list it in $supportedOptions. The SeatCountValidator above follows this pattern. A caller can then replace the message at the call site:

#[Validate(SeatCountValidator::class, options: [
    'minimum' => 1,
    'message' => 'my_extension.messages:validator.conference.notEnoughSeats.short',
])]

What to read next 

• Built-in validators and the #[Validate] attribute — check whether a built-in validator already covers a constraint before writing a custom one.
• Validation in Extbase — how the framework triggers errorAction() and how to display errors in Fluid templates.