cnastasi/functional-validators

A PHP 8.5+ library implementing Value Objects with functional validation using pipes, functors, and union types

dev-main 2025-11-25 11:43 UTC

Requires

• php: ^8.5

Requires (Dev)

• pestphp/pest: ^4.1

MIT

• Christian Nastasi

• validation
• functional-programming
• pipes
• functor
• value-objects
• union-types
• php8.5

README

A PHP 8.5+ library providing functional validation using the pipe operator (|>), functors, and union types. Perfect for building Value Objects with elegant, composable validation.

🎯 Overview

This library provides a functional approach to Value Objects validation in PHP 8.5+. Instead of throwing exceptions on the first validation error, it accumulates all errors and returns them in a type-safe way using union types.

Key Features:

• ✅ Functional Validation: Uses PHP 8.5 pipes for elegant validation chains
• ✅ Error Accumulation: Collects all validation errors, not just the first one
• ✅ Field-Level Errors: For entities, errors are organized by field name
• ✅ Type Safety: Strong typing with union types (ValueObject|ErrorsBag or Entity|MultipleFieldErrorsBag)
• ✅ Reusable Validators: Library of composable validators

📚 Related Articles

This project is part of a blog series on Value Objects in PHP:

1. Value Objects in PHP 8: Building a better code
2. Advanced Value Objects in PHP 8
3. Value Object in PHP 8: Entities
4. Value Object in PHP 8: Build your own type system
5. Value Objects in PHP 8: Let's introduce a functional approach (this project)

📋 Requirements

• PHP 8.5 or higher
• Composer

🚀 Installation

composer require cnastasi/functional-validators

Or add it manually to your composer.json:

{
    "require": {
        "cnastasi/functional-validators": "^0.1"
    }
}

💡 Quick Start

Single Value Object

use CN\FunctionalValidators\Examples\Age;
use CN\FunctionalValidators\Errors\ErrorsBag;

$result = Age::create(25);
if ($result instanceof Age) {
    echo $result->value; // 25
} elseif ($result instanceof ErrorsBag) {
    foreach ($result->getErrors() as $error) {
        echo $error->message . "\n";
    }
}

Entity with Multiple Fields

use CN\FunctionalValidators\Examples\Person;
use CN\FunctionalValidators\Errors\MultipleFieldErrorsBag;

$result = Person::create('', 'invalid-email', -5);
if ($result instanceof MultipleFieldErrorsBag) {
    foreach ($result->getErrorsByField() as $field => $errors) {
        echo "Field '{$field}':\n";
        foreach ($errors as $error) {
            echo "  - {$error->message}\n";
        }
    }
}

Building Your Own Value Objects

use CN\FunctionalValidators\Validators\IntegerValue;
use CN\FunctionalValidators\Errors\ErrorsBag;

readonly final class Price
{
    private function __construct(public int $value) {}

    public static function create(mixed $value): Price|ErrorsBag
    {
        $context = $value
            |> IntegerValue::from(...)
            |> IntegerValue::min(0, "Price cannot be negative")
            |> IntegerValue::max(100000, "Price cannot exceed 1000.00€");

        return $context->isValid()
            ? new self($context->getValue())
            : $context->getErrors();
    }
}

📖 For detailed usage instructions, see USAGE.md

🏗️ Architecture

• CN\FunctionalValidators\Validators\: Core validation classes (ValidationContext, MultipleValidationContext, IntegerValue, StringValue)
• CN\FunctionalValidators\Errors\: Error handling (ErrorsBag, MultipleFieldErrorsBag, Error)
• CN\FunctionalValidators\Examples\: Example Value Objects (Age, Email, Name, Password, Person)

🧪 Testing

composer test

📖 Documentation

• Usage Guide: Detailed guide on building your own Value Objects
• Blog Article: Deep dive into the concepts and design decisions

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📝 License

This project is open-sourced software licensed under the MIT license.

👤 Author

Christian Nastasi

• Blog: dev.to/cnastasi
• Email: [e-mail]

🙏 Acknowledgments

This project explores functional programming concepts in PHP, specifically:

• PHP 8.5 pipe operator (|>)
• Functors for error accumulation
• Union types instead of Either monads
• Reusable validator composition

⚠️ Note

This is an experimental project exploring PHP 8.5 features. While functional and tested, it's primarily intended as a learning resource and proof of concept.