Getting Started

This page guides you through installing the hypervel/validation package, creating your first validator, and performing basic validation tasks. It covers the essential workflows for validating data using the Factory pattern and executing validation rules.

For in-depth information about the validation engine's architecture and traits, see Core Validation Engine. For details on creating custom validation rules, see Custom Validation Rules. For database-specific validation (unique/exists rules), see Database Integration.

---

Installation

The hypervel/validation package is installed via Composer. It requires PHP 8.2 or higher and has mandatory dependencies on hypervel/support, hypervel/translation, egulias/email-validator, and brick/math.

Required PHP Extensions

The package requires the following PHP extensions:

• ext-filter - Used for basic validation filters
• ext-mbstring - Used for multibyte string operations

Optional Dependencies

For database validation rules (unique, exists):

For UUID validation:

Sources: composer.json1-52

---

Quick Start Example

The simplest way to validate data is using the Factory::make() method to create a validator, then calling validation methods on it.

Sources: src/Factory.php80-108 src/Validator.php288-305 src/Validator.php392-441

---

Factory-Based Validator Creation

The Factory class is the primary entry point for creating Validator instances. It manages dependencies, extensions, and presence verifiers.

Factory Instantiation Flow

Diagram: Factory instantiation via dependency injection container

The ValidatorFactory is an invokable class that creates a Factory instance with all necessary dependencies. If database components are available, it automatically configures database presence verification for unique and exists rules.

Sources: src/ValidatorFactory.php13-29 src/Factory.php71-75

Creating Validators with Factory::make()

The Factory::make() method accepts four parameters:

Parameter	Type	Description
$data	array	Data to validate
$rules	array	Validation rules per attribute
$messages	array	Custom error messages (optional)
$attributes	array	Custom attribute display names (optional)

Sources: src/Factory.php80-108

Factory::validate() Shortcut

For one-line validation with exception throwing:

This method creates a validator and immediately calls validate(), throwing a ValidationException if validation fails.

Sources: src/Factory.php115-118

---

Validation Execution Methods

Once you have a Validator instance, several methods are available for executing validation and retrieving results.

Validation Method Decision Tree

Diagram: Choosing the appropriate validation method

Sources: src/Validator.php392-441 src/Validator.php446-449 src/Validator.php481-486 src/Validator.php519-549

Method Reference Table

Method	Returns	Throws Exception	Use Case
passes()	bool	No	Check validation status without throwing
fails()	bool	No	Inverse of passes()
validate()	array	Yes (on failure)	Get validated data or fail with exception
validated()	array	Yes (if not run yet)	Get validated data after passes()
errors() / messages()	MessageBag	No	Get error messages
failed()	array	No	Get failed rules per attribute

Sources: src/Validator.php392-953

---

Working with Validation Results

Accessing Validated Data

After successful validation, retrieve only the validated attributes:

The validated() method returns an array containing only the data that has validation rules defined. Attributes without rules are excluded.

Sources: src/Validator.php519-549

Safe Validated Input

For type-safe access to validated data:

The safe() method returns a ValidatedInput object that provides safe access to validated data.

Sources: src/Validator.php507-512

Accessing Error Messages

When validation fails, retrieve error messages:

Sources: src/Validator.php929-952

Accessing Valid and Invalid Data

Retrieve data that passed or failed validation:

Sources: src/Validator.php869-924

---

Rule Syntax Overview

Validation rules are specified as strings or arrays. Multiple rules are separated by pipe (|) characters or provided as array elements.

String Syntax

Array Syntax

Rule Objects

Wildcard Syntax for Arrays

This validates all elements in the users array, regardless of the array keys.

Sources: src/Validator.php558-605 src/ValidationRuleParser.php

---

Common Validation Rules Quick Reference

The package includes 50+ built-in validation rules. Here are the most commonly used ones:

Rule	Description	Example
required	Field must be present and not empty	'name' => 'required'
email	Field must be valid email address	'email' => 'email'
string	Field must be a string	'name' => 'string'
integer	Field must be an integer	'age' => 'integer'
numeric	Field must be numeric	'price' => 'numeric'
min:value	Minimum value/length	'name' => 'min:3'
max:value	Maximum value/length	'name' => 'max:255'
between:min,max	Value/length between min and max	'age' => 'between:18,120'
in:foo,bar	Value must be in list	'status' => 'in:active,inactive'
confirmed	Field must have matching _confirmation field	'password' => 'confirmed'
unique:table,column	Value must be unique in database	'email' => 'unique:users,email'
exists:table,column	Value must exist in database	'category_id' => 'exists:categories,id'

For a complete list of built-in rules, see Built-in Validation Rules.

Sources: src/Concerns/ValidatesAttributes.php

---

Validation Execution Flow

Understanding the validation execution flow helps debug issues and optimize performance.

Diagram: Validation execution sequence from Factory creation to result

Key execution steps:

1. Factory creates Validator: The Factory::make() method instantiates a Validator with the translator and data
2. Data parsing: parseData() converts special characters in keys to placeholders to handle dots and asterisks
3. Rule parsing: ValidationRuleParser::explode() expands wildcard rules and conditional rules
4. Validation loop: For each attribute and each rule, validateAttribute() delegates to trait methods
5. Error collection: Failed validations add messages to the MessageBag
6. Result: Return boolean or throw ValidationException based on MessageBag state

Sources: src/Factory.php80-108 src/Validator.php288-305 src/Validator.php392-441 src/Validator.php554-606

---

Customizing Error Messages

Custom error messages can be provided when creating the validator:

Custom Attribute Names

Display friendly attribute names in error messages:

For detailed information on message customization and placeholders, see Custom Messages and Placeholders.

Sources: src/Validator.php288-305 src/Factory.php80-108

---

Conditional Validation

Execute validation only when certain conditions are met using the sometimes() method:

The callback receives the data being validated and should return true to apply the rules.

Sources: src/Validator.php1090-1107

---

After Validation Callbacks

Register callbacks to execute after validation completes:

After callbacks are useful for cross-field validation or complex business logic that doesn't fit into standard rules.

Sources: src/Validator.php373-387 src/Validator.php436-438

---

Stop On First Failure

For performance optimization or user experience, stop validation after the first rule failure:

This is useful for large datasets or when you only need to know if validation passes without collecting all errors.

Sources: src/Validator.php1129-1134

---

Next Steps

Now that you understand the basics of creating and using validators, explore these topics:

• Core Validation Engine - Deep dive into the Validator class architecture and validation traits
• Built-in Validation Rules - Complete reference of all 50+ built-in rules with examples
• Custom Validation Rules - Create your own validation rules using closures and rule classes
• Database Integration - Use unique and exists rules with database presence verification
• Message System - Advanced message customization, localization, and formatting

Sources: composer.json1-52 src/Validator.php1-1430 src/Factory.php1-260 src/ValidatorFactory.php1-30