Overview

The hypervel/validation package is a comprehensive data validation library for PHP 8.2+ applications within the Hypervel/Hyperf ecosystem. This page introduces the package's purpose, design philosophy, architecture, and key components.

Purpose and Design Philosophy

The hypervel/validation package validates user input, API requests, configuration data, and any data requiring verification against business rules. The package is designed around three core principles:

1. Separation of Concerns: The Validator class orchestrates validation, delegating actual rule execution to the ValidatesAttributes trait (50+ methods), message generation to FormatsMessages trait, and attribute replacement to ReplacesAttributes trait.

2. Extensibility Through Composition: Multiple rule definition formats are supported (string-based, object-based, closures, invokables), all unified through a common execution pipeline. Custom rules implement contracts like Rule, ValidationRule, DataAwareRule, or ValidatorAwareRule.

3. Framework Integration with Independence: While designed for Hyperf's Swoole runtime via ConfigProvider, the package maintains independence through PSR contracts and optional dependencies. Database validation requires hyperf/database, but the core engine functions without it.

The package follows Laravel's validation API patterns while being optimized for the Hyperf framework and Swoole's coroutine environment.

Sources: composer.json1-11 composer.json28-36 composer.json40-51

Position in Hypervel Ecosystem

The validation package is part of the Hypervel component family, sitting between framework concerns and application logic:

Layer	Components	Role
Framework	Hyperf Framework	Request handling, routing, middleware
Validation Layer	hypervel/validation	Data validation, rule execution, error messages
Support Libraries	hypervel/support, hypervel/translation	Utilities, localization
Infrastructure	Swoole, hyperf/database	Runtime, persistence

The package depends on two sibling packages: hypervel/support (array/collection utilities via Arr class) and hypervel/translation (message localization via Translator contract). Optional integration with hyperf/database enables the DatabasePresenceVerifier for exists and unique rules.

Sources: composer.json28-36 composer.json48-51

Core Components

The validation system is built around these core components with their relative importance in the codebase:

Component	Primary Classes/Traits	File Paths	Importance
Validation Engine	ValidatesAttributes trait	src/Concerns/ValidatesAttributes.php	High (50+ validation methods)
Orchestration	Validator class	src/Validator.php	High
Factory System	Factory, ValidatorFactory	src/Factory.php, src/ValidatorFactory.php	Medium
Rule Objects	Rule interface, concrete classes	src/Rules/*.php	Medium
Message System	FormatsMessages, ReplacesAttributes traits	src/Concerns/*.php	Medium
Database Integration	DatabasePresenceVerifier, PresenceVerifierInterface	src/DatabasePresenceVerifier.php	Medium (optional)
Rule Contracts	Rule, DataAwareRule, ValidatorAwareRule, ImplicitRule	src/Contracts/*.php	Low (interfaces)
Translation	Translator interface	(from hypervel/translation)	External dependency

Sources: composer.json23-26 composer.json28-36

Key Features

• 50+ Built-in Rules: Validation for strings, numbers, dates, files, emails, URLs, arrays, and more
• Custom Rule Support: Closures, invokable classes, and contract-based custom rules via Rule, InvokableRule, ValidationRule interfaces
• Conditional Logic: ConditionalRules and NestedRules for runtime-determined validation
• Array/Nested Validation: Wildcard rules with asterisk notation for deep structure validation
• Database Rules: unique and exists rules via DatabasePresenceVerifier
• Message Localization: Hierarchical message retrieval with placeholder replacement via Translator
• Dependency Injection: PSR-11 container integration via ConfigProvider
• Extensibility: Custom extensions, replacers, and resolvers via Factory

Sources: src/Validator.php145-188 composer.json40-43

System Architecture

The validation system follows a three-layer architecture: Public API, Core Engine, and Rule System.

Three-Layer Architecture with Code Entities

The Validator class (src/Validator.php) orchestrates validation, delegating to three key traits:

• ValidatesAttributes (src/Concerns/ValidatesAttributes.php) - 50+ validate* methods for built-in rules
• FormatsMessages (src/Concerns/FormatsMessages.php) - Generates error messages with 4-tier lookup
• ReplacesAttributes (src/Concerns/ReplacesAttributes.php) - Placeholder replacement in messages

Rules are created via the Rule facade (src/Rule.php) and implement the Rule contract (src/Contracts/Rule.php). Database validation is abstracted through PresenceVerifierInterface with optional DatabasePresenceVerifier implementation.

Sources: composer.json23-26 composer.json28-36 composer.json48-51

Component Interaction Map

This diagram shows how the core components interact during a typical validation request:

Validation Execution Flow with Method Names

The flow begins with Factory::make() creating a Validator instance. Rules are parsed via ValidationRuleParser::parse() and wildcards expanded. During execution, Validator::validateAttribute() routes to either RuleObject::passes() for custom rules or ValidatesAttributes::validate{Rule}() for built-in rules. Database rules call DatabasePresenceVerifier::getCount(). Failed validations trigger the message pipeline: FormatsMessages::getMessage() → makeReplacements() → ReplacesAttributes::doReplacements() → MessageBag::add().

Sources: composer.json23-26

Rule Type Taxonomy

The validation system supports six distinct categories of rules, each with different execution strategies:

Rule Type Classification

Rule Type	Examples	Execution Method
String-Based	'required', 'email:rfc', 'max:100'	ValidatesAttributes::validate{Rule}()
Basic Objects	Rule::email(), Rule::date()	Rule::passes() method
Complex Objects	Rule::password(), Rule::file()	Rule::passes() with configuration
Conditional	Rule::prohibitedIf(), Rule::requiredIf()	Rule::passes() with condition evaluation
Logical	Rule::anyOf(), Rule::contains()	Rule::passes() with sub-rule aggregation
Custom	Closures, invokable classes	Wrapped in ClosureValidationRule or InvokableValidationRule

Sources: composer.json23-26

Dependencies

The validation package requires the following dependencies:

Dependency	Version	Purpose
php	^8.2	Minimum PHP version requirement
ext-filter	*	Native filter extension for basic validation
ext-mbstring	*	Multibyte string support
brick/math	^0.11|^0.12	Arbitrary precision decimal validation
egulias/email-validator	^3.2.5|^4.0	RFC-compliant email validation
hypervel/support	^0.3	Array/collection utilities via Arr, Collection
hypervel/translation	^0.3	Message localization via Translator contract

Optional Dependencies:

Dependency	Purpose
hyperf/database ^3.1.0	Required for DatabasePresenceVerifier (unique/exists rules)
ramsey/uuid ^4.7	Required for Validator::validateUuid() method

Sources: composer.json28-36 composer.json48-51

Framework Integration

The package integrates with Hyperf via ConfigProvider (src/ConfigProvider.php):

ConfigProvider Dependency Registration

The ConfigProvider (src/ConfigProvider.php) registers three primary factories with the PSR-11 container:

1. ValidatorFactory (src/ValidatorFactory.php) - Invokable factory that resolves Translator and Factory from container
2. Factory (src/Factory.php) - Manages validator instance creation, custom extensions via extend(), and message replacers
3. PresenceVerifierFactory (src/PresenceVerifierFactory.php) - Creates DatabasePresenceVerifier when hyperf/database is available

The Translator contract is provided by hypervel/translation. Database connection is optional from hyperf/database.

Sources: composer.json40-43 composer.json48-51

Getting Started

To begin using the validation system:

1. Basic Usage: See Core Validation Engine for fundamental validation concepts
2. Rule Reference: Consult Built-in Validation Rules for available validation methods
3. Custom Logic: Review Custom Validation Rules for extending the system
4. Framework Setup: Check Factory and Configuration for Hyperf integration
5. Database Rules: See Database Integration for exists and unique validation
6. Error Messages: Reference Message System for customizing validation output

Sources: composer.json1-52 README.md1-2