Download the PHP package aegisora/guardian without Composer

Aegisora Guardian

Aegisora Guardian is a lightweight and extensible validation orchestrator for the Aegisora ecosystem.

The package provides a fluent and predictable way to execute validation rules against arbitrary values using the standardized architecture defined in aegisora/rule-contract.

Guardian focuses on:

• centralized validation execution
• structured validation results
• custom exception handling
• sequential rule pipelines
• clean and framework-agnostic architecture

The library is intentionally minimalistic while still being powerful enough to build complex domain validation layers.

✨ Features

Fluent Validation Pipeline

Guardian allows validation rules to be chained together in a readable and expressive way.

This makes complex validation scenarios easy to maintain and extend.

Rule-Based Validation

Validation logic is completely separated into independent rule objects implementing:

This promotes:

• single responsibility
• reusable validation logic
• domain-oriented architecture
• testability

Structured Validation Flow

Guardian follows a strict validation flow:

Each rule receives a Context object and returns a standardized Result object.

No raw booleans are used internally.

Custom Exception Handling

Every rule can define its own exception.

This enables precise domain-level error handling:

Lightweight Architecture

The package has:

• no framework dependencies
• minimal memory overhead
• simple object graph
• predictable behavior

Guardian can be used in:

• Laravel
• Symfony
• Slim
• custom PHP applications
• microservices
• domain-driven projects

Safe Rule Execution

Internal rule execution is protected from unexpected contract-level failures.

If a rule throws RuleException, Guardian converts it into:

This keeps the validation layer consistent and isolated.

📦 Installation

Install the package via Composer:

🔗 Related Packages

Guardian is part of the broader Aegisora ecosystem.

Several ready-to-use validation rules are already implemented as separate packages and can be found in the official Aegisora repositories:

https://github.com/orgs/Aegisora/repositories

Rule repositories follow a consistent naming convention:

Examples:

• https://github.com/Aegisora/is-callable-rule
• https://github.com/Aegisora/is-array-rule
• https://github.com/Aegisora/emptiness-rule
• https://github.com/Aegisora/scalar-equality-rule
• etc

These packages provide reusable validation logic fully compatible with Guardian and aegisora/rule-contract.

The ecosystem is designed to allow combining independent validation rules into flexible and composable validation pipelines.

📚 Requirements

Required Package

Guardian relies on:

which provides:

• RuleInterface
• Context
• Result
• RuleException

🚀 Core Concept

Guardian acts as a validation execution engine.

Instead of manually invoking validation logic throughout the application, Guardian centralizes the process and provides a consistent execution model.

Validation flow:

1. A value is passed into Guardian
2. Validation rules are attached
3. Guardian creates a Context
4. Rules are executed sequentially
5. Every rule returns a Result
6. Validation failures trigger exceptions

This architecture makes validation:

• predictable
• composable
• extensible
• easy to debug
• easy to test

🏗️ Basic Usage

Simple Validation

The simplest way to validate a value is using check().

If validation passes, execution continues normally.

If validation fails, Guardian throws:

Validation with Custom Exception

You may provide a custom exception for validation failures.

If validation fails, the provided exception will be thrown instead of the default Guardian exception.

This is especially useful in:

• domain-driven design
• business validation layers
• API validation
• application services

🔗 Fluent Validation API

Guardian supports fluent rule chaining through GuardianExecutor.

Example:

Execution behavior:

• rules execute sequentially
• validation stops on first failure
• exceptions are thrown immediately
• successful rules continue pipeline execution

Multiple Rules with Different Exceptions

Each rule may define its own exception.

This enables extremely precise validation semantics.

🧩 Real-World Example: User Registration Validation

Guardian can be used in an application service to validate incoming data before executing business logic.

In this example, a user registration command is validated by three independent rules:

• email must have a valid format
• password must be strong enough
• user must be at least 18 years old

Guardian does not contain validation logic itself. It receives a value, passes it into rules through Context, executes rules one by one, and stops on the first failed rule.

Registration Command

The command contains the data required to register a user.

Email Rule

This rule checks that the command contains a valid email address.

Password Rule

This rule checks that the password is at least 12 characters long and contains both an uppercase letter and a number.

Age Rule

This rule checks that the user is old enough to register.

Application Service

The service describes the validation pipeline. Each rule may have its own domain exception.

Usage

If all rules pass, the user is created.

If one rule fails, Guardian immediately stops execution and throws the exception attached to that rule.

For example, if ValidEmailRule fails, InvalidEmailException is thrown. StrongPasswordRule and AdultUserRule will not be executed.

If a rule fails internally and throws RuleException, Guardian converts it into GuardianExecutingRuleException, keeping rule execution errors separate from business validation errors.

🏛️ Architecture

Guardian contains several small and focused components.

Guardian

Main entry point for validation operations.

Responsibilities:

• starts validation process
• creates validation pipeline
• provides simple API
• delegates execution to GuardianExecutor

Methods:

GuardianExecutor

Core validation execution engine.

Responsibilities:

• stores validation rules
• creates validation context
• executes rules sequentially
• analyzes validation results
• throws exceptions

Methods:

GuardRule

Immutable transport object containing:

• validation rule
• optional exception

Purpose:

• encapsulates validation configuration
• keeps executor implementation clean

GuardValue

Simple wrapper around arbitrary validated value.

Purpose:

• encapsulates raw input value
• centralizes value transport

⚙️ Validation Lifecycle

Complete internal validation lifecycle:

🚨 Exceptions

Guardian defines dedicated exceptions for predictable error handling.

GuardianValidationException

Thrown when validation fails and no custom exception is provided.

Example:

The exception contains the failed rule code returned by Result.

GuardianExecutingRuleException

Thrown when internal rule execution fails due to contract-level exceptions.

Example scenario:

This protects application code from low-level rule implementation failures.

🧠 Validation Philosophy

Guardian follows several important principles.

Explicit Validation

Validation should be visible and explicit.

Bad:

Good:

Domain-Oriented Exceptions

Validation errors should communicate domain meaning.

Example:

instead of generic runtime errors.

Structured Result Objects

Rules should return standardized objects instead of booleans.

This enables:

• extensibility
• debugging
• metadata support
• consistent validation behavior

Separation of Concerns

Guardian separates:

• validation execution
• validation rules
• result analysis
• exception handling

This keeps code maintainable and scalable.

⚖️ License

This package is open-source and licensed under the MIT License. See the LICENSE for details.

🌱 Contributing

Contributions are welcome and greatly appreciated!. See the CONTRIBUTING for details.

🌟 Support

If you find this project useful, please consider giving it a star on GitHub!

It helps the project grow and motivates further development of the Aegisora ecosystem.