Add Custom Validation

This tutorial walks you through adding server-side validation for a custom field type. Building on the phone field from the previous guide, we'll add a validator that enforces an E.164-style phone number on the server, a semantic check no regex pattern configured in the editor can express as reliably.

You'll do three things:

1. Decide which rule keys your descriptor's extractRules() emits.
2. Implement Hyva\FormBuilder\Api\FieldValidatorInterface.
3. Register it in FieldValidatorPool via di.xml, keyed by your descriptor's type token.

Step 1: Decide Your Rule Keys

The descriptor's extractRules() output is the contract: SchemaCompiler builds the FieldRule straight from it, and PayloadValidator enforces it. Reuse the built-in keys wherever you can so the storefront pre-flight stays aligned with the server:

• required
• min_length
• max_length, which every shipped free-text descriptor always sets. Each one declares a MAX_LENGTH_CEILING constant and clamps through FieldRuleNormaliser::maxLengthWithin($merchantValue, self::MAX_LENGTH_CEILING), so an editor-configured limit can lower the ceiling but never raise it. A custom free-text descriptor should do the same.
• pattern
• pattern_message
• allowed_values

For the phone field, the pattern already lives in a built-in key, so the descriptor from the previous guide needs no changes. Its extractRules() already emits pattern and pattern_message. Your validator applies the E.164 check first, then hands the FieldRule to the shipped TextValidator so the editor-configured pattern and length limits still run.

Step 2: Implement the Validator

Implement Hyva\FormBuilder\Api\FieldValidatorInterface. Its single method validate(FieldRule $rule, mixed $rawValue): ?string returns the error message string when the value is invalid, or null when it passes.

<?php
declare(strict_types=1);

namespace Acme\FormBuilderPhoneField\Model\Submission\FieldValidator;

use Hyva\FormBuilder\Api\FieldValidatorInterface;
use Hyva\FormBuilder\Model\Submission\FieldRule;
use Hyva\FormBuilder\Model\Submission\Validator\TextValidator;

class PhoneValidator implements FieldValidatorInterface
{
    // Composing the shipped text validator keeps the editor's pattern and length rules in force.
    public function __construct(private readonly TextValidator $textValidator)
    {
    }

    public function validate(FieldRule $rule, mixed $rawValue): ?string
    {
        $value = is_string($rawValue) ? trim($rawValue) : '';

        if ($value === '') {
            return $rule->required ? (string)__('This field is required.') : null;
        }

        // E.164: optional leading +, 8 to 15 digits, nothing else.
        if (!preg_match('/^\+?[0-9]{8,15}$/', preg_replace('/[ .\-]/', '', $value))) {
            return $rule->patternMessage ?: (string)__('Enter a valid phone number.');
        }

        // Length ceiling and the editor-configured pattern, matched exactly as the text field does.
        return $this->textValidator->validate($rule, $rawValue);
    }
}

Step 3: Register the Validator

Add the validator to FieldValidatorPool, keyed by the type token your descriptor's getType() returns. PayloadValidator dispatches each field to pool->get($rule->type)->validate(...), falling back to the text validator for unknown tokens.

For this to fire, the phone descriptor from the previous guide must return the matching token from getType(). Change it from text to phone:

public function getType(): string
{
    return 'phone';
}

Then register the validator under the same phone key:

<type name="Hyva\FormBuilder\Model\Submission\FieldValidatorPool">
    <arguments>
        <argument name="validators" xsi:type="array">
            <item name="phone" xsi:type="object">
                Acme\FormBuilderPhoneField\Model\Submission\FieldValidator\PhoneValidator
            </item>
        </argument>
    </arguments>
</type>

This is the same merge-by-item-name mechanism as FieldDescriptorPool, so your validator slots in alongside the built-ins without colliding.

Cross-Field Checks

The validator pool is per-field: each validator sees one field's rule and one raw value, never the whole payload. When a rule spans fields (confirm-email must equal email, a total must sum its parts), a plugin on Hyva\FormBuilder\Model\Submission\PayloadValidator::validate() remains the option, since it sees the full submitted set. Reach for the pool for per-type rules and the plugin only for genuinely cross-field logic.

Reference Implementation

In the module-form-builder package:

• src/Api/FieldValidatorInterface.php - the interface you implement in Step 2.
• src/Model/Submission/FieldValidatorPool.php and the shipped validators alongside it - the per-type validators the pool ships with, and the text fallback.
• src/Model/Submission/Validator/UrlValidator.php - a validator that adds its own check, then composes TextValidator for length and pattern.
• src/Model/Submission/MerchantPattern.php - how editor-configured patterns are delimited, compile-checked and matched.
• src/Model/Submission/PayloadValidator.php - where the pool is dispatched, and the method to plug into for cross-field checks.
• src/Model/Submission/SchemaCompiler.php and FieldRule - how extractRules() output becomes the FieldRule your validator reads.
• src/etc/di.xml - the pool wiring to mirror in Step 3.

These show the patterns from this tutorial in shipped code.

Related Topics

• Create a Custom Field - build the field and descriptor this validation attaches to.
• Create a Custom Form Root - ship a root that admits your validated field.
• Add a Security Gate - the security checks that run before validation, in front of email dispatch.
• How Validation Works - the client pre-flight, the server schema, and the 400 error envelope your messages travel in.
• Architecture - the map of every extension surface.
• Building Forms - the fields you validate as they appear in the editor.
• Creating Components
• the Hyvä CMS component model your field declarations build on.