 |
VOOZH | about |
|
VOOZH | about |
This page documents the extension system in hypervel/validation, which allows developers to register custom validation rules and message replacers beyond the 50+ built-in rules. The extension system supports three types of custom rules (regular, implicit, and dependent), custom message replacers, and fallback messages.
For information about using extensions within validators, see Creating Validators. For documentation on custom rule objects and the Rule interface, see Custom Validation Rules.
The extension system operates through a two-tier architecture where the Factory serves as the central registry for extensions, which are then applied to individual Validator instances upon creation.
Sources: src/Factory.php80-108 src/Factory.php134-149 src/Validator.php1139-1222
The validation system supports three distinct types of custom extensions, each with different validation behavior.
| Extension Type | Runs When Field Missing | Runs When Field Null | Use Case |
|---|---|---|---|
| Regular | No | No (unless not nullable) | Standard validation rules |
| Implicit | Yes | Yes | Rules that require field presence (like required) |
| Dependent | Depends | Depends | Rules that reference other fields in parameters |
Regular Extensions are standard validation rules that only execute when the field is present and not null (unless marked as nullable). They are registered via Factory::extend() src/Factory.php154-161
Implicit Extensions always execute regardless of whether the field exists or is null. They are used for rules that determine field presence requirements, similar to the built-in required rule. Registered via Factory::extendImplicit() src/Factory.php166-173
Dependent Extensions are rules that reference other field names in their parameters (like same:other_field). The validator automatically expands wildcard parameters for these rules. Registered via Factory::extendDependent() src/Factory.php178-185
Sources: src/Factory.php154-185 src/Validator.php1139-1172 src/Validator.php163-188 src/Validator.php195-236
Extensions are registered on the Factory instance, which then applies them to all validators it creates.
Extensions can be defined as either closures or class-based strings:
Closure-based Extension:
Class-based Extension:
The extension receives four parameters:
$attribute - The attribute name being validated$value - The value being validated$parameters - Array of rule parameters$validator - The Validator instanceWhen registering an extension, an optional fallback message can be provided as the third parameter. This message is used when no custom message is defined:
The fallback message is stored in snake_case format in the fallbackMessages array src/Factory.php159
Sources: src/Factory.php152-193 src/Factory.php22-53
When the Factory creates a validator via make(), it applies all registered extensions through the addExtensions() method.
The Validator class provides both singular and plural methods for adding extensions at the instance level:
| Method | Purpose | Key Behavior |
|---|---|---|
addExtensions(array) | Add multiple regular extensions | Converts keys to snake_case src/Validator.php1139-1148 |
addExtension(string, $ext) | Add single regular extension | Converts rule name to snake_case src/Validator.php1177-1180 |
addImplicitExtensions(array) | Add multiple implicit extensions | Calls addExtensions() then adds to implicitRules src/Validator.php1152-1160 |
addImplicitExtension(string, $ext) | Add single implicit extension | Converts to snake_case, adds to implicitRules src/Validator.php1185-1190 |
addDependentExtensions(array) | Add multiple dependent extensions | Calls addExtensions() then adds to dependentRules src/Validator.php1165-1172 |
addDependentExtension(string, $ext) | Add single dependent extension | Converts to snake_case, adds to dependentRules src/Validator.php1195-1200 |
addReplacers(array) | Add multiple message replacers | Converts keys to snake_case src/Validator.php1205-1214 |
addReplacer(string, $rep) | Add single message replacer | Converts rule name to snake_case src/Validator.php1219-1222 |
All extension keys are normalized to snake_case during registration to ensure consistent lookup.
Sources: src/Validator.php1139-1222 src/Factory.php134-149
When a validator encounters a custom rule during validation, it invokes the extension through a dynamic method call mechanism.
The Validator::__call() magic method handles dynamic method calls for custom extensions src/Validator.php1416-1429:
The callExtension() method determines whether the extension is a closure or class-based and invokes it accordingly src/Validator.php1385-1397:
array_values($parameters)callClassBasedExtension() which uses the DI container to instantiate the class src/Validator.php1402-1409Extensions receive parameters in a specific structure:
$attribute - String, the field name being validated$value - Mixed, the field value$parameters - Array, parsed rule parameters (e.g., ['5'] for divisible_by:5)$validator - Validator instance, provides access to all validation data and methodsSources: src/Validator.php1416-1429 src/Validator.php1385-1409 src/Validator.php554-606
Message replacers customize how error message placeholders are replaced for specific rules. They supplement the standard placeholder replacement system.
Custom replacers are invoked during the message replacement phase in the FormatsMessages trait. The trait checks for a custom replacer method in this order:
Validator::$replacers array for custom replacer (closure or class-based)replace{Rule} method in FormatsMessages trait:attribute, :value replacements if no custom replacer existsCustom replacers receive the same four parameters as extensions and return a modified message string.
This replacer would replace :divisor in the message "The :attribute must be divisible by :divisor." with the actual parameter value.
Sources: src/Factory.php190-193 src/Validator.php1205-1222
While the Factory manages extensions at the application level, individual Validator instances can also receive custom extensions directly.
The Validator class exposes public methods that allow runtime customization:
| Method | Purpose | Typical Use Case |
|---|---|---|
setCustomMessages(array) | Override error messages for this validator | One-off message customization src/Validator.php1227-1232 |
setAttributeNames(array) | Set custom attribute display names | User-friendly field names src/Validator.php1237-1242 |
addCustomAttributes(array) | Add to existing custom attributes | Incremental attribute naming src/Validator.php1247-1252 |
setValueNames(array) | Set custom value display names | Enum/status display src/Validator.php1267-1272 |
addCustomValues(array) | Add to existing custom values | Incremental value naming src/Validator.php1277-1282 |
setFallbackMessages(array) | Set fallback messages for custom rules | Applied by Factory src/Validator.php1287-1290 |
Instance-level customizations are particularly useful for:
Sources: src/Validator.php1227-1290 src/Factory.php80-108
The following example demonstrates all extension types working together:
Sources: src/Factory.php152-193 src/Validator.php1139-1222 src/Validator.php554-606
For complex validation logic, extensions can be implemented as class methods and registered by class string reference.
The validator uses Str::parseCallback() to extract the class name and method src/Validator.php1404 then resolves the class via the PSR-11 container src/Validator.php1407-1408 This allows class-based extensions to leverage dependency injection for accessing services like database connections or external APIs.
Sources: src/Validator.php1402-1409 src/Factory.php152-161
The extension system in hypervel/validation provides a flexible mechanism for adding custom validation logic:
The system maintains separation between extension registration (Factory) and extension execution (Validator), enabling both global configuration and per-validator customization while keeping the core validation engine clean and extensible.
Refresh this wiki