Lemmon Validator

Note

This library is in active development. The API may change in future versions as we refine and improve the developer experience based on real-world usage and feedback.

Lemmon Validator is a comprehensive, fluent validation and data processing library for PHP that prioritizes developer experience, type safety, and real-world practicality. Inspired by modern validation libraries like Valibot and Zod, it brings a chainable, readable API to PHP for validation, transformation, and sanitization with intelligent error handling and form-safe defaults.

Installation

composer require lemmon/validator

Requirements: PHP 8.3 or higher

Quick Start

All runtime classes live under the Lemmon\Validator namespace.

use Lemmon\Validator\Validator;

// Simple validation with form-safe coercion
$email = Validator::isString()
    ->nullifyEmpty() // Empty strings become null (form-safe)
    ->email()
    ->validate('user@example.com');

// Schema validation with custom logic
$userSchema = Validator::isAssociative([
    'name' => Validator::isString()->required(),
    'age' => Validator::isInt()->min(18)->coerce(),
    'email' => Validator::isString()->nullifyEmpty()->email(),
    'password' => Validator::isString()->minLength(8, 'Password too short')
]);

// Tuple-based validation (no exceptions)
[$valid, $user, $errors] = $userSchema->tryValidate($input);
if (!$valid) {
    $flattened = \Lemmon\Validator\ValidationException::flattenErrors($errors);
    // Returns: [['path' => 'name', 'message' => 'Value is required'], ...]
}

// Exception-based validation
try {
    $user = $userSchema->validate($input);
} catch (\Lemmon\Validator\ValidationException $e) {
    $flattened = $e->getFlattenedErrors();
    // Returns: [['path' => 'name', 'message' => 'Value is required'], ...]
}

Features

• Type-safe validation for strings, integers, floats, arrays, and objects, powered by PHP enums for IDE autocomplete, refactoring safety, and zero magic strings
• Fluent, chainable API with a guaranteed execution order — methods run exactly as written (->pipe('trim')->nullifyEmpty()->required())
• Smart null handling — validations skip null unless required(); transform()/pipe()/nullifyEmpty() skip null by default
• Form-safe coercion — empty strings become null (not dangerous 0/false); opt into coerce() for form-friendly type conversions
• Universal transformations (transform(), pipe()) that plug in any PHP callable or external library
• Custom validation with satisfies(), plus logical combinators (satisfiesAll()/satisfiesAny()/satisfiesNone())
• Exact-value and enum matching — const() for single values, enum() for BackedEnum/UnitEnum (available on all validators)
• Last-resort defaults — default() fills null after the pipeline, before required() enforces presence
• Structured errors — getStructuredErrors() returns ValidationError objects with a stable code (see ValidationCode), dotted path, message, and params for programmatic handling and i18n
• Fail-fast per field, aggregated per schema — each validator stops at its first failure while schema validation collects errors across all fields
• API-friendly flattened errors with field paths (_root for root, dot notation for nested) via getFlattenedErrors()
• Accurate schema results — output includes only provided fields and fields with defaults, never unexpected properties
• Strict typing throughout — every file uses declare(strict_types=1);

Philosophy

Simple and minimal, with extensibility over reinvention. Rather than reimplementing every possible transformation or validation rule, Lemmon Validator provides a solid foundation with generic transform() and pipe() methods that integrate seamlessly with PHP's ecosystem. Need complex string transformations? Plug in Laravel's Str class. Need advanced array operations? Connect Laravel Collections. The library focuses on what it does best — type-safe validation with excellent developer experience — while letting you leverage the entire PHP ecosystem.

Documentation

Getting Started

• Installation & Setup
• Basic Usage
• Core Concepts

Validation Guides

• String Validation — Email, URL, patterns, length constraints
• Numeric Validation — Integers, floats, ranges, constraints
• Array Validation — Indexed arrays and item validation
• Object & Schema Validation — Complex nested structures
• Custom Validation — User-defined functions and business logic
• Error Handling — Working with validation errors

API Reference

• Validator Factory

Examples

• Form Validation

For AI Agents

• llms.txt - Complete technical specification with full API signatures, method parameters, and core concepts. Download this file and provide it to your AI agent for accurate code generation and assistance with the library.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Packagist
• GitHub Repository
• Issue Tracker
• Changelog