Custom Messages and Placeholders

This page documents how to define custom validation error messages and create custom placeholder replacers for the hypervel/validation package. It covers inline messages, translation file integration, standard and custom placeholders, custom attribute display names, and the creation of custom message replacers.

For information about the message retrieval hierarchy and the overall formatting system, see Message Retrieval and Formatting. For information about extending validation with custom rules, see Custom Validation Rules.

---

Message Definition Methods

Custom validation messages can be defined through multiple mechanisms, each with different priority and use cases.

Message Definition Hierarchy

The validation system searches for messages in the following order:

Sources: src/Concerns/FormatsMessages.php20-73

Inline Messages

Inline messages are passed directly when creating a validator and have the highest priority:

Inline messages are retrieved via getInlineMessage() and getFromLocalArray() methods.

Sources: src/Concerns/FormatsMessages.php78-130

Custom Translation Messages

Messages can be defined in translation files under the validation.custom key:

The system constructs the translation key as validation.custom.{attribute}.{rule} and retrieves it via getCustomMessageFromTranslator().

Sources: src/Concerns/FormatsMessages.php135-161

Wildcard Pattern Matching

Both inline messages and translation messages support wildcard patterns for array validation:

Wildcard matching is implemented in getFromLocalArray() and getWildcardCustomMessages() using pattern matching.

Sources: src/Concerns/FormatsMessages.php90-130 src/Concerns/FormatsMessages.php163-176

Fallback Messages for Custom Rules

When registering custom rules, you can provide fallback messages:

These fallback messages are stored in Factory::$fallbackMessages and used when no other message is found.

Sources: src/Factory.php154-185

---

Standard Placeholders

The validation system provides several standard placeholders that are automatically replaced in all error messages.

Placeholder Replacement Pipeline

Sources: src/Concerns/FormatsMessages.php214-233

:attribute Placeholder

The :attribute placeholder is replaced with the displayable name of the attribute. It supports three case variants:

Placeholder	Replacement
:attribute	Lowercase/original form
:Attribute	First letter capitalized
:ATTRIBUTE	All uppercase

Example message: "The :attribute must be a valid email address."

The attribute name is determined by getDisplayableAttribute() which checks:

1. Custom attributes array ($validator->customAttributes)
2. Translation file (validation.attributes.{attribute})
3. Implicit attributes formatter (for wildcard expansions)
4. Snake case conversion with underscores replaced by spaces

Sources: src/Concerns/FormatsMessages.php238-272 src/Concerns/FormatsMessages.php312-320

:input Placeholder

The :input placeholder is replaced with the actual value of the attribute being validated:

The value is formatted via getDisplayableValue() which:

• Returns custom value if defined in $validator->customValues
• Checks translation file validation.values.{attribute}.{value}
• Returns 'array' for array values
• Returns 'true'/'false' for boolean values
• Returns 'empty' for null values
• Returns string representation otherwise

Sources: src/Concerns/FormatsMessages.php400-409 src/Concerns/FormatsMessages.php414-439

:index and :position Placeholders

These placeholders are used for array validation to indicate the numeric index of the failing element:

Placeholder	Description	Example
:index	Zero-based index	0, 1, 2
:position	One-based position	1, 2, 3
:first-index	First numeric segment (index)	0
:second-index	Second numeric segment (index)	1
:first-position	First numeric segment (position)	1
:second-position	Second numeric segment (position)	2

The replacements are calculated in replaceIndexOrPositionPlaceholder() which parses the attribute path and applies modifiers.

Sources: src/Concerns/FormatsMessages.php325-376

---

Custom Attribute Names

You can customize how attribute names are displayed in error messages.

Via Custom Attributes Array

Pass custom attribute names when creating the validator:

This array is stored as $validator->customAttributes and checked first by getDisplayableAttribute().

Sources: src/Concerns/FormatsMessages.php289-308

Via Translation Files

Define attribute names in translation files:

The system retrieves these via getAttributeFromTranslations().

Sources: src/Concerns/FormatsMessages.php277-284

Wildcard Attribute Names

Custom attribute names support wildcards for array validation:

Wildcard matching is performed in getAttributeFromLocalArray() using pattern matching.

Sources: src/Concerns/FormatsMessages.php289-308

Implicit Attributes Formatter

For wildcard-expanded attributes that don't have custom names defined, you can set a formatter:

This formatter is used as a fallback in getDisplayableAttribute() when the attribute exists in $validator->implicitAttributes.

Sources: src/Concerns/FormatsMessages.php265-269

---

Custom Value Display

Similar to attribute names, you can customize how values are displayed in error messages.

Via Custom Values Array

Define custom value representations:

This is checked first in getDisplayableValue().

Sources: src/Concerns/FormatsMessages.php414-439

Via Translation Files

Define value display names in translation files:

The system constructs the translation key as validation.values.{attribute}.{value}.

Sources: src/Concerns/FormatsMessages.php424-428

---

Creating Custom Replacers

Custom replacers allow you to define placeholder replacement logic for custom validation rules or to override built-in behavior.

Custom Replacer Registration Flow

Sources: src/Factory.php188-193 src/Concerns/FormatsMessages.php214-233

Registering Closure-Based Replacers

Register a custom replacer using a closure:

The closure receives:

• $message - The current message string
• $attribute - The attribute being validated
• $rule - The rule name
• $parameters - Array of rule parameters
• $validator - The Validator instance

Sources: src/Concerns/FormatsMessages.php461-473

Registering Class-Based Replacers

Register a replacer using a class reference:

The class is resolved from the container and the specified method is called. The default method name is replace if not specified.

Sources: src/Concerns/FormatsMessages.php478-484

Built-in Replacer Examples

The ReplacesAttributes trait contains numerous built-in replacers demonstrating common patterns:

Simple Parameter Replacement

Sources: src/Concerns/ReplacesAttributes.php118-121

Multi-Parameter Replacement

Sources: src/Concerns/ReplacesAttributes.php42-45

Cross-Attribute References

Sources: src/Concerns/ReplacesAttributes.php16-23

List Formatting

Sources: src/Concerns/ReplacesAttributes.php330-333

Conditional Value Display

Sources: src/Concerns/ReplacesAttributes.php216-223

Size-Based Replacement

Sources: src/Concerns/ReplacesAttributes.php380-387

---

Advanced Placeholder Features

Named Parameters Parsing

Some rules use named parameters that can be referenced in messages:

Sources: src/Concerns/ReplacesAttributes.php622-633

Ordinal Word Conversion

For nested array validation, numeric segments can be converted to ordinal words:

This enables placeholders like :first-position, :second-index, etc.

Sources: src/Concerns/FormatsMessages.php381-395

Decimal Range Formatting

The decimal rule supports range formatting:

Sources: src/Concerns/ReplacesAttributes.php62-71

---

Complete Example

Here's a comprehensive example demonstrating multiple customization features:

Sources: src/Factory.php154-193 src/Concerns/FormatsMessages.php214-439