Last indexed: 14 February 2026 (fb2a0f)

Validation

The validation system provides a comprehensive data validation framework built on the Facade pattern. It validates incoming data against a set of rules and generates user-friendly error messages when validation fails. The system supports both synchronous validation through the Validator facade and integration with the HTTP request lifecycle.

This page covers the overall validation architecture and common usage patterns. For detailed information about the Validator facade's API, custom rules, and error message handling, see Validator Facade. For request-specific validation, see Request and Response.

Architecture Overview

The validation system follows a factory pattern where the Validator facade resolves to a factory instance that creates validator instances for each validation request.

Sources: src/Facades/Validator.php1-197

Facade Resolution

The Validator facade resolves to the Factory contract, which is responsible for creating individual validator instances.

Sources: src/Facades/Validator.php193-196

Validation Workflow

The validation process follows a predictable lifecycle from creation through validation to result retrieval.

Sources: src/Facades/Validator.php10-11 src/Facades/Validator.php25-37

Core Methods

The Validator facade provides methods organized into several functional categories.

Factory Methods

Method	Description	Return Type
`make(array $data, array $rules, array $messages = [], array $attributes = [])`	Create a new validator instance	`\Hypervel\Validation\Validator`
`validate(array $data, array $rules, array $messages = [], array $attributes = [])`	Validate data and return validated values	`array`

Validation Execution

Method	Description	Return Type
`passes()`	Determine if validation passes	`bool`
`fails()`	Determine if validation fails	`bool`
`validated()`	Get validated data	`array`
`safe(array\|null $keys = null)`	Get safe validated input accessor	`ValidatedInput\|array`

Error Handling

Method	Description	Return Type
`messages()`	Get error messages	`\Hypervel\Support\MessageBag`
`errors()`	Alias for messages()	`\Hypervel\Support\MessageBag`
`failed()`	Get failed validation rules	`array`
`addFailure(string $attribute, string $rule, array $parameters = [])`	Manually add failure	`void`

Data Accessors

Method	Description	Return Type
`valid()`	Get attributes that passed validation	`array`
`invalid()`	Get attributes that failed validation	`array`
`getData()`	Get all data under validation	`array`
`getValue(string $attribute)`	Get specific attribute value	`mixed`

Sources: src/Facades/Validator.php10-44

Validation Rule Categories

The Validator supports numerous built-in validation rules organized by category.

Basic Rules

Sources: src/Facades/Validator.php74-183

Comparative Rules

The validator provides methods for comparing values:

Rule Method	Purpose
`validateBetween()`	Value between min and max
`validateMin()`	Minimum value/length
`validateMax()`	Maximum value/length
`validateSize()`	Exact size
`validateGt()`	Greater than another field
`validateGte()`	Greater than or equal
`validateLt()`	Less than another field
`validateLte()`	Less than or equal
`validateSame()`	Same as another field
`validateDifferent()`	Different from another field

Sources: src/Facades/Validator.php91-173

Database Rules

Rule Method	Purpose
`validateExists()`	Value exists in database
`validateUnique()`	Value is unique in database

These rules use the PresenceVerifier interface to query the database.

Sources: src/Facades/Validator.php20-21 src/Facades/Validator.php105-106

File Validation

Rule Method	Purpose
`validateFile()`	Valid file upload
`validateImage()`	Valid image file
`validateMimes()`	File has allowed MIME type
`validateMimetypes()`	File matches MIME type pattern
`validateExtensions()`	File has allowed extension
`validateDimensions()`	Image has required dimensions

Sources: src/Facades/Validator.php102-132

Date and Time Rules

Rule Method	Purpose
`validateDate()`	Valid date
`validateDateFormat()`	Date matches format
`validateDateEquals()`	Date equals specified date
`validateBefore()`	Date is before another
`validateBeforeOrEqual()`	Date is before or equal
`validateAfter()`	Date is after another
`validateAfterOrEqual()`	Date is after or equal
`validateTimezone()`	Valid timezone identifier

Sources: src/Facades/Validator.php81-97 src/Facades/Validator.php180

Custom Rules and Extensions

The validator can be extended with custom validation rules using several methods.

Extension Method Overview

Method	Use Case
`extend(string $rule, \Closure\|string $extension, string\|null $message = null)`	Add standard validation rule
`extendImplicit(string $rule, \Closure\|string $extension, string\|null $message = null)`	Add rule that validates even when attribute is absent
`extendDependent(string $rule, \Closure\|string $extension, string\|null $message = null)`	Add rule that depends on other field values
`replacer(string $rule, \Closure\|string $replacer)`	Define message parameter replacer

Sources: src/Facades/Validator.php12-15 src/Facades/Validator.php50-57

Configuration and Customization

The validator supports extensive customization through various configuration methods.

Message Customization

Method	Purpose
`setCustomMessages(array $messages)`	Set custom validation messages
`setFallbackMessages(array $messages)`	Set fallback messages
`setAttributeNames(array $attributes)`	Set custom attribute display names
`addCustomAttributes(array $attributes)`	Add to existing attribute names
`setValueNames(array $values)`	Set custom value display names
`addCustomValues(array $customValues)`	Add to existing value names

Behavior Configuration

Method	Purpose
`stopOnFirstFailure(bool $stopOnFirstFailure = true)`	Stop validation after first failure
`includeUnvalidatedArrayKeys()`	Include unvalidated array keys in result
`excludeUnvalidatedArrayKeys()`	Exclude unvalidated array keys from result
`sometimes(array\|string $attribute, array\|string $rules, callable $callback)`	Conditionally add rules
`after(callable\|array\|string $callback)`	Add after validation hook

Sources: src/Facades/Validator.php16-17 src/Facades/Validator.php25 src/Facades/Validator.php48-64

Integration with Other Components

The validation system integrates with several other framework components.

Translation Integration

The validator uses the translator to generate localized error messages based on validation rules and parameters.

Sources: src/Facades/Validator.php19 src/Facades/Validator.php68-73

Database Integration

Database-dependent validation rules (exists, unique) use the PresenceVerifier interface to query the database.

Sources: src/Facades/Validator.php20-21 src/Facades/Validator.php105-109

Container Integration

The validator can access the service container to resolve dependencies for custom validation rules.

Sources: src/Facades/Validator.php22-23

HTTP Request Integration

The Request facade integrates validation directly into HTTP request handling. See Request and Response for request validation patterns.

Data Manipulation Methods

The validator provides methods to manipulate the data under validation.

Method	Purpose	Return Type
`setData(array $data)`	Replace all data	`Validator`
`setValue(string $attribute, mixed $value)`	Set single attribute value	`void`
`parseData(array $data)`	Parse and normalize data	`array`

Rule Manipulation

Method	Purpose	Return Type
`getRules()`	Get all validation rules	`array`
`getRulesWithoutPlaceholders()`	Get rules without parameter placeholders	`array`
`setRules(array $rules)`	Replace all rules	`Validator`
`addRules(array $rules)`	Add to existing rules	`void`
`hasRule(string $attribute, array\|string $rules)`	Check if attribute has rule	`bool`

Sources: src/Facades/Validator.php24 src/Facades/Validator.php38-48

Advanced Features

Conditional Validation

The validator supports conditional rule application through the sometimes() method, which adds rules only when a callback returns true.

Sources: src/Facades/Validator.php48

After Validation Hooks

The after() method allows executing callbacks after validation completes, useful for cross-field validation or complex business logic.

Sources: src/Facades/Validator.php25

Validation with Error Bags

The validateWithBag() method validates data and stores errors in a named error bag, useful for multiple forms on one page.

Sources: src/Facades/Validator.php28

Safe Validated Input

The safe() method returns a ValidatedInput instance that provides type-safe access to validated data with dot notation support.

Sources: src/Facades/Validator.php29

Exception Handling

The validator can be configured to throw custom exceptions when validation fails.

Method	Purpose
`getException()`	Get exception class name
`setException(string\|\Throwable $exception)`	Set custom exception class

Sources: src/Facades/Validator.php65-66

Summary

The validation system provides:

Facade-based API: Clean static interface via Validator facade
Factory pattern: Creates validator instances for each validation request
Extensive rule library: 80+ built-in validation rules covering common scenarios
Extensibility: Custom rules via extend(), extendImplicit(), and extendDependent()
Integration: Seamless integration with translation, database, and container systems
Flexible error handling: MessageBag for structured error access
Safe data access: ValidatedInput for type-safe validated data retrieval

For detailed API documentation and examples, see Validator Facade.