Data-Aware and Validator-Aware Rules

Purpose and Scope

This document explains the DataAwareRule and ValidatorAwareRule interfaces, which enable custom validation rules to access the complete validation context. These interfaces provide lifecycle hooks that the Validator uses to inject runtime context into rule objects before execution.

For information about rule interfaces in general, see Rule Interfaces and Contracts. For creating custom validation rules, see Custom Validation Rules.

Overview

The validation system provides two context-injection interfaces that enable rules to make decisions based on the complete validation state rather than just the single attribute value being validated:

Interface	Purpose	Provides Access To
DataAwareRule	Access all data under validation	Complete $data array being validated
ValidatorAwareRule	Access the validator instance	Validator configuration, custom messages, all validation data

These interfaces are optional. Rules that only need the attribute value being validated can implement the basic Rule interface without implementing these context-aware interfaces.

Sources: src/Contracts/DataAwareRule.php src/Contracts/ValidatorAwareRule.php

Context Injection Flow

The Validator automatically detects when a rule implements these interfaces and calls the appropriate setter methods before executing the rule's passes() method.

Injection Sequence

Sources: src/Validator.php src/InvokableValidationRule.php65-88

Code-Level Injection Points

Sources: src/Validator.php

The DataAwareRule Interface

The DataAwareRule interface provides rules with access to all data being validated, enabling cross-field validation logic.

Interface Contract

Implementation Pattern

Rules that implement DataAwareRule should:

1. Declare a protected property to store the data
2. Implement the setData() method to store the array
3. Access stored data in the passes() method

Example: Email Rule Implementation

The Email rule uses DataAwareRule to access all validation data, which it then passes to a nested validator for email-specific validation.

src/Rules/Email.php11 - Interface declaration:

src/Rules/Email.php40-42 - Property to store data:

src/Rules/Email.php251-256 - Implementation of setter:

src/Rules/Email.php174-175 - Usage of stored data:

Sources: src/Rules/Email.php1-257

The ValidatorAwareRule Interface

The ValidatorAwareRule interface provides rules with access to the Validator instance, enabling access to custom messages, custom attributes, and other validator configuration.

Interface Contract

Implementation Pattern

Rules that implement ValidatorAwareRule should:

1. Declare a protected property to store the validator
2. Implement the setValidator() method to store the instance
3. Access validator properties or methods in the passes() method

Example: Email Rule Implementation

The Email rule uses ValidatorAwareRule to access custom messages and attributes configured on the parent validator.

src/Rules/Email.php35-37 - Property to store validator:

src/Rules/Email.php241-246 - Implementation of setter:

src/Rules/Email.php177-178 - Usage of stored validator:

Sources: src/Rules/Email.php1-257

Adapter Pattern for Custom Rules

The validation system provides adapter classes that automatically handle context injection for closure-based and invokable rules.

ClosureValidationRule Adapter

The ClosureValidationRule implements ValidatorAwareRule and passes the validator instance to the closure callback.

src/ClosureValidationRule.php13 - Interface implementation:

src/ClosureValidationRule.php49-53 - Passing validator to closure:

Sources: src/ClosureValidationRule.php1-76

InvokableValidationRule Adapter

The InvokableValidationRule implements ValidatorAwareRule and conditionally injects context into the wrapped invokable if it implements the context-aware interfaces.

src/InvokableValidationRule.php16 - Interface implementation:

src/InvokableValidationRule.php69-75 - Conditional context injection:

Sources: src/InvokableValidationRule.php1-125

Use Cases

Cross-Field Validation

DataAwareRule enables validation logic that depends on other fields in the data array.

Use Case	Example Logic	Why Data Access is Needed
Conditional validation	Require field B only if field A has specific value	Must check value of field A
Field comparison	Ensure password_confirmation matches password	Must access both fields
Related field constraints	Discount percentage requires discount code field	Must verify presence of related field
Aggregate validation	Sum of quantity fields must not exceed limit	Must access multiple quantity fields

Accessing Validator Configuration

ValidatorAwareRule enables rules to integrate with the validator's configuration and state.

Use Case	Validator Property Accessed	Purpose
Custom messages	$validator->customMessages	Apply same custom messages as parent validation
Custom attributes	$validator->customAttributes	Use same attribute display names
Translation	$validator->getTranslator()	Access translation service
All data	$validator->getData()	Alternative to implementing DataAwareRule
Validation state	$validator->getRules()	Inspect what other rules are being applied

Nested Validation

Rules can create nested validators using the parent validator's configuration, as demonstrated by the Email rule.

src/Rules/Email.php174-179 - Creating nested validator with parent configuration:

This pattern ensures consistent behavior: if the parent validator has custom messages for "email" validation, those messages will be used in the nested validation as well.

Sources: src/Rules/Email.php166-188

Context Availability Matrix

Different rule types have different levels of context access:

Sources: src/Validator.php src/ClosureValidationRule.php45-56 src/InvokableValidationRule.php65-88

Implementation Guidelines

When to Implement DataAwareRule

Implement DataAwareRule when your rule needs to:

• Compare the current attribute value with other field values
• Validate based on the presence or absence of other fields
• Perform aggregate calculations across multiple fields
• Apply conditional logic based on other field values

When to Implement ValidatorAwareRule

Implement ValidatorAwareRule when your rule needs to:

• Create nested validators with consistent configuration
• Access custom message or attribute configurations
• Use the validator's translation service
• Inspect other rules being applied to the data

When to Implement Both

Implement both interfaces when your rule needs complete validation context, such as:

• Complex rules that create nested validators (like Email)
• Rules that perform sophisticated cross-field validation
• Rules that need to maintain consistency with parent validator configuration

Implementation Checklist

For rules implementing these interfaces:

1. ✅ Declare protected properties to store injected context
2. ✅ Implement setter methods that return $this for fluent interface
3. ✅ Initialize properties with sensible defaults (empty array, null)
4. ✅ Access stored context only in passes() method, not in constructor
5. ✅ Handle case where context might not be injected (defensive programming)

Sources: src/Rules/Email.php1-257

Complete Example: Email Rule Architecture

The Email rule demonstrates a complete implementation using both context-aware interfaces:

The Email rule uses:

• DataAwareRule to pass the complete data array to its nested validator
• ValidatorAwareRule to inherit custom messages and attributes from the parent validator
• Both together to ensure consistent validation behavior at all nesting levels

Sources: src/Rules/Email.php1-257