Skip to content

Commit 798147a

Browse files
lemmonlemmon
committed
feat: comprehensive documentation restructure and error message standardization
- **BREAKING**: Remove periods from all error messages to align with PHP ecosystem standards - Updated all built-in validators (String, Int, Float, Array, Object, Bool) - Updated NumericConstraintsTrait constraint messages - Updated FieldValidator combinator messages - Updated all test expectations to match new format - Aligns with Laravel, Symfony, and Zod conventions - **Documentation**: Complete restructure for better developer experience - Replace monolithic README with concise overview and navigation - Create comprehensive documentation structure: - Getting Started guides (Installation, Basic Usage, Core Concepts) - Focused validation guides (String, Numeric, Custom, Error Handling) - API Reference with complete method documentation - Real-world examples (Form validation, E-commerce) - Rename TODO.md to ROADMAP.md for professional appearance - Update GEMINI.md to AGENTS.md as general LLM context - Reorganize IDEAS.md with implementation priorities - Update CHANGELOG.md with documentation improvements - **Quality**: All tests passing (57 tests, 154 assertions) - **Standards**: 100% PHPStan compliance maintained
1 parent 1ae081d commit 798147a

32 files changed

Lines changed: 3791 additions & 515 deletions

‎AGENTS.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Lemmon Validator - Project Overview
2+
3+
A comprehensive, fluent validation library for PHP inspired by Valibot and Zod. This project provides type-safe validation with a symmetrical API for handling different data structures, advanced validation capabilities, and enterprise-grade documentation.
4+
5+
## 🏗️ Architecture
6+
7+
### Core Factory Pattern
8+
- **`Validator`** - Static factory creating type-specific validators (`isString()`, `isInt()`, `isFloat()`, `isArray()`, `isAssociative()`, `isObject()`, `isBool()`)
9+
- **`FieldValidator`** - Abstract base class with unified validation interface and shared functionality
10+
- **`ValidationException`** - Structured exception handling with comprehensive error collection
11+
12+
### Type-Specific Validators
13+
- **`StringValidator`** - Format validation (email, URL, UUID, IP), length constraints, pattern matching
14+
- **`IntValidator`** / **`FloatValidator`** - Numeric constraints via shared `NumericConstraintsTrait`
15+
- **`ArrayValidator`** - Indexed array validation with optional item validation
16+
- **`AssociativeValidator`** / **`ObjectValidator`** - Schema-based validation for complex structures
17+
- **`BoolValidator`** - Boolean validation with intelligent coercion
18+
19+
### Shared Components
20+
- **`NumericConstraintsTrait`** - Common numeric validations (`min()`, `max()`, `multipleOf()`, `positive()`, `negative()`)
21+
22+
## 🚀 Advanced Features
23+
24+
### Validation Capabilities
25+
- **Logical Combinators** - `allOf()`, `anyOf()`, `not()` for complex rule composition
26+
- **Context-Aware Validation** - Custom validators receive `(value, key, input)` parameters
27+
- **Comprehensive Error Collection** - All validation errors collected, not just the first failure
28+
- **Smart Type Coercion** - Configurable automatic type conversion
29+
- **Fluent API** - Chainable method calls for readable validation code
30+
31+
### Developer Experience
32+
- **Dual Validation Methods** - `validate()` (exception-based) and `tryValidate()` (tuple-based)
33+
- **Custom Validation** - `addValidation()` method for business logic integration
34+
- **Schema Validation** - Nested structure validation with hierarchical error reporting
35+
36+
## 📚 Documentation Structure
37+
38+
### Getting Started
39+
- **Installation & Setup** - Requirements, installation, verification
40+
- **Basic Usage** - Fundamental patterns, validation methods, common use cases
41+
- **Core Concepts** - Architecture understanding, validation flow, performance considerations
42+
43+
### Focused Guides
44+
- **String Validation** - Complete format validation suite with practical examples
45+
- **Numeric Validation** - Integer and float validation with shared constraints
46+
- **Custom Validation** - Business logic integration and context-aware validation
47+
- **Error Handling** - Exception vs tuple patterns, structured error reporting
48+
49+
### API Reference
50+
- **Validator Factory** - Complete factory method documentation with usage patterns
51+
- **Type-Specific APIs** - Detailed method references for each validator type
52+
53+
### Practical Examples
54+
- **Form Validation** - Contact forms, user registration, e-commerce products
55+
- **Multi-Step Forms** - Complex validation workflows with session handling
56+
- **Real-World Schemas** - Business logic validation patterns
57+
58+
## 🔧 Development Workflow
59+
60+
### Code Quality
61+
- **Testing** - Pest PHP with organized test suite (8 focused test files, 57 tests, 154 assertions)
62+
- **Static Analysis** - PHPStan at maximum level for type safety
63+
- **Code Style** - PHP-CS-Fixer for consistent formatting
64+
- **Performance** - Optimized validation logic with eliminated code duplication
65+
66+
### Development Tools
67+
- **Debugging** - `symfony/var-dumper` integration
68+
- **Error Handling** - `symfony/error-handler` for development
69+
- **Composer Scripts** - `test`, `lint`, `fix`, `analyse` commands
70+
71+
### Test Organization
72+
```
73+
tests/
74+
├── AssociativeValidatorTest.php # Schema validation
75+
├── ObjectValidatorTest.php # stdClass validation
76+
├── ArrayValidatorTest.php # Indexed arrays
77+
├── StringValidatorTest.php # String formats
78+
├── IntValidatorTest.php # Integer constraints
79+
├── FloatValidatorTest.php # Float constraints
80+
├── FieldValidatorTest.php # Base functionality
81+
└── NumericConstraintsTraitTest.php # Shared numeric logic
82+
```
83+
84+
## 🎯 Project Status
85+
86+
### Current Version: 0.3.0
87+
- ✅ Complete string validation suite
88+
- ✅ Dedicated float validator with numeric constraints
89+
- ✅ Logical combinators for complex validation logic
90+
- ✅ Comprehensive error collection and context-aware validation
91+
- ✅ Organized test suite and enterprise documentation
92+
- ✅ 100% PHPStan compliance and PHP-CS-Fixer standards
93+
94+
### Key Metrics
95+
- **8 validator types** covering all PHP data types
96+
- **25+ built-in validation methods** for common use cases
97+
- **3,000+ lines of documentation** with practical examples
98+
- **57 unit tests** with comprehensive coverage
99+
- **Zero technical debt** with modern PHP 8.1+ codebase
100+
101+
## 🔮 Vision & Roadmap
102+
103+
This library aims to be the definitive validation solution for PHP applications, providing:
104+
- **Developer Productivity** - Intuitive API with excellent documentation
105+
- **Type Safety** - Leveraging PHP's type system for robust validation
106+
- **Performance** - Optimized validation logic for high-throughput applications
107+
- **Extensibility** - Custom validation support for business-specific requirements
108+
- **Enterprise Ready** - Comprehensive error handling and structured feedback
109+
110+
The project maintains a clear separation between completed features (CHANGELOG), strategic planning (ROADMAP), and innovative ideas (IDEAS), ensuring focused development and clear project management.

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
44

55
## [Unreleased]
66

7+
### Added
8+
- **Comprehensive Documentation**: Complete documentation restructure with focused guides, API reference, and practical examples
9+
- Getting Started guides (Installation, Basic Usage, Core Concepts)
10+
- Validation Guides (String, Numeric, Custom, Error Handling)
11+
- API Reference with complete method documentation
12+
- Real-world Examples (Form validation, API validation, E-commerce)
13+
- **Enhanced README**: Concise overview with quick start examples and organized navigation
14+
715
## [0.3.0] - 2025-09-25
816

917
### Added

‎GEMINI.md‎

Lines changed: 0 additions & 56 deletions
This file was deleted.

0 commit comments

Comments
 (0)