FormValidationPreset

Pair framework: FormValidationPreset

Pair\Html\FormValidationPreset provides shared normalization and validation rules for common form fields. It is the server-side source used by FormControl::preset(...), by the preset-backed Form factory methods, and by the matching browser helper in PairValidation.js.

Use it when a field has a reusable, well-known shape such as IBAN, BIC/SWIFT, EAN-13, URL, UUID, IP address, MAC address, slug, or Italian fiscal identifiers.

Main flow

Preset validation has three layers:

• FormValidationPreset normalizes and validates values on the server
• FormControl::preset(...) applies the preset to a control and wires it into Form::isValid()
• /assets/PairValidation.js adds browser-side normalization and setCustomValidity(...) when loaded

Server-side validation does not depend on JavaScript. The browser helper is progressive enhancement.

Presets

Canonical preset	Common aliases	Form helper	What it checks
bic	swift, swift_bic, bic_code	bic()	BIC/SWIFT syntax
e164_phone	e164, phone_e164, international_phone	e164Phone()	international phone number in E.164 format
ean13	ean, ean-13	ean13()	EAN-13 length and checksum; UPC-A style 12-digit values are completed with a leading zero
email	email_address	emailAddress()	email syntax through PHP validation
hex_color	hex_color	hexColor()	#RGB or #RRGGBB hexadecimal color
iban	iban_code	iban()	IBAN syntax and MOD-97 checksum
ip_address	ip	ipAddress()	IPv4 or IPv6 address
ipv4_address	ipv4	ipv4Address()	IPv4 address
ipv6_address	ipv6	ipv6Address()	IPv6 address
mac_address	mac	macAddress()	MAC address with six hexadecimal pairs
slug	slug	slug()	lowercase ASCII words separated by single hyphens
url	url	webUrl()	URL with hierarchical scheme, such as https://example.com
uuid	uuid	uuid()	canonical UUID syntax
it.fiscal_code	codice_fiscale, cf, italian_fiscal_code	italianFiscalCode()	Italian numeric fiscal code or personal fiscal code
it.personal_fiscal_code	italian_personal_fiscal_code	italianPersonalFiscalCode()	Italian personal fiscal code syntax, date, and checksum
it.sdi_recipient_code	codice_destinatario, sdi, italian_sdi_recipient_code	italianSdiRecipientCode()	seven-character Italian SdI recipient code
it.vat_number	partita_iva, piva, italian_vat_number	italianVatNumber()	Italian VAT number checksum

Direct usage

use Pair\Html\FormValidationPreset;

$iban = FormValidationPreset::normalize(FormValidationPreset::IBAN, 'it60 x054 2811 1010 0000 0123 456');

if (!FormValidationPreset::isValid(FormValidationPreset::IBAN, $iban, required: true)) {
    // Reject or report the invalid value in the owning model/request layer.
    throw new \InvalidArgumentException('Invalid IBAN.');
}

Aliases are accepted by canonicalName(...), definition(...), normalize(...), and isValid(...):

$vatNumber = FormValidationPreset::normalize('partita_iva', 'IT 12345678903');
$valid = FormValidationPreset::isValid('partita_iva', $vatNumber, required: true);

Form usage

The most common usage is through Form helpers:

$form = new \Pair\Html\Form();

$form->emailAddress('email')->required();
$form->iban('ibanCode');
$form->webUrl('website');
$form->italianFiscalCode('fiscalCode');
$form->italianVatNumber('vatNumber');

You can also apply a preset to any compatible text-like control:

$form->text('recipientCode')
    // Accepts the Italian alias and stores the canonical preset internally.
    ->preset('codice_destinatario')
    ->validationMessage('Enter a valid SdI recipient code.');

Method reference

canonicalName(string $preset): string

Returns the canonical preset identifier for a canonical name or alias. Unknown presets throw InvalidArgumentException.

definition(string $preset): array

Returns the display and HTML defaults for a preset. Definitions may include minLength, maxLength, pattern, placeholder, inputmode, autocomplete, message, and messageKey.

FormControl::preset(...) applies these defaults non-destructively: explicit values already set on the control win.

normalize(string $preset, mixed $value): string

Returns the normalized string for a preset. Examples:

• IBAN, BIC/SWIFT, fiscal codes, and SdI codes become uppercase alphanumeric strings
• MAC addresses become colon-separated uppercase pairs when enough characters are present
• slugs become lowercase ASCII words separated by hyphens
• E.164 phone numbers keep a leading plus sign and digits
• Italian VAT number values drop the optional IT prefix and separators

isValid(string $preset, mixed $value, bool $required = false): bool

Normalizes the value, accepts an empty value when required is false, enforces preset length constraints, and then runs the preset-specific validator.

The method returns false for invalid values and throws InvalidArgumentException for unknown presets. It does not add errors to Logger by itself. Logging happens when a control validates through FormControl::validate().

Specific validators and normalizers

The class also exposes named helpers such as:

• isValidBic(...), normalizeBic(...)
• isValidE164Phone(...), normalizeE164Phone(...)
• isValidEan13(...), normalizeEan13(...)
• isValidEmail(...), normalizeEmail(...)
• isValidIban(...), normalizeIban(...)
• isValidIpAddress(...), isValidIpv4Address(...), isValidIpv6Address(...)
• isValidMacAddress(...), normalizeMacAddress(...)
• isValidSlug(...), normalizeSlug(...)
• isValidUrl(...), normalizeUrl(...)
• isValidUuid(...), normalizeUuid(...)
• isValidFiscalCode(...), isValidPersonalFiscalCode(...), isValidItalianVatNumber(...)
• normalizeFiscalCode(...), normalizeVatNumber(...), normalizeSdiRecipientCode(...)

Prefer the generic normalize(...) and isValid(...) in application code unless you need a very explicit helper.

Notes

• it.fiscal_code accepts both eleven-digit numeric fiscal codes and sixteen-character personal fiscal codes.
• it.personal_fiscal_code is stricter: it validates personal fiscal-code syntax, birth-date data, and checksum.
• it.vat_number validates the eleven-digit Italian VAT checksum.
• url requires :// and uses PHP URL validation.
• email uses PHP email validation after trimming whitespace.
• Client-side validation must always be treated as a hint; keep the server-side preset or an equivalent model/request rule.

See also: Form, FormControl, PairValidation.js, Email, Url, Text.