PHPackages                             aegisora/guardian - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. aegisora/guardian

ActiveLibrary[Validation & Sanitization](/categories/validation)

aegisora/guardian
=================

Lightweight validation rule execution orchestrator for the Aegisora ecosystem

v1.0.0(1mo ago)01803MITPHPPHP >=7.4

Since Jun 11Pushed 1mo agoCompare

[ Source](https://github.com/Aegisora/guardian)[ Packagist](https://packagist.org/packages/aegisora/guardian)[ Docs](https://github.com/Aegisora/guardian)[ RSS](/packages/aegisora-guardian/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (3)

Aegisora Guardian
=================

[](#aegisora-guardian)

[![Code Coverage Badge](./badge.svg)](./badge.svg)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![PHPStan Badge](https://camo.githubusercontent.com/83dd3d35cebed0eab9ee97ff1a5849c1344cda6a8ee9cac2cda20f5aa55b67bd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230392d627269676874677265656e2e7376673f7374796c653d666c6174)](https://camo.githubusercontent.com/83dd3d35cebed0eab9ee97ff1a5849c1344cda6a8ee9cac2cda20f5aa55b67bd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230392d627269676874677265656e2e7376673f7374796c653d666c6174)

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
==========

[](#-features)

### Fluent Validation Pipeline

[](#fluent-validation-pipeline)

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

```
$guardian
    ->that($value)
    ->must(FirstRule::create())
    ->must(SecondRule::create())
    ->validate();
```

This makes complex validation scenarios easy to maintain and extend.

---

### Rule-Based Validation

[](#rule-based-validation)

Validation logic is completely separated into independent rule objects implementing:

```
Aegisora\RuleContract\RuleInterface
```

This promotes:

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

---

### Structured Validation Flow

[](#structured-validation-flow)

Guardian follows a strict validation flow:

```
Value → Context → Rule → Result → Exception

```

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

No raw booleans are used internally.

---

### Custom Exception Handling

[](#custom-exception-handling)

Every rule can define its own exception.

This enables precise domain-level error handling:

```
->must(
    EmailRule::create(),
    new InvalidEmailException()
)
```

---

### Lightweight Architecture

[](#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

[](#safe-rule-execution)

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

If a rule throws `RuleException`, Guardian converts it into:

```
GuardianExecutingRuleException
```

This keeps the validation layer consistent and isolated.

---

📦 Installation
==============

[](#-installation)

Install the package via Composer:

```
composer require aegisora/guardian
```

---

🔗 Related Packages
==================

[](#-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:

Rule repositories follow a consistent naming convention:

```
*-rule

```

Examples:

-
-
-
-
- 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
==============

[](#-requirements)

### Required Package

[](#required-package)

Guardian relies on:

```
aegisora/rule-contract
```

which provides:

- `RuleInterface`
- `Context`
- `Result`
- `RuleException`

---

🚀 Core Concept
==============

[](#-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
==============

[](#️-basic-usage)

### Simple Validation

[](#simple-validation)

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

```
use Aegisora\Guardian\Guardian;

$guardian = new Guardian();

$guardian->check(
    $value,
    FooRule::create()
);
```

If validation passes, execution continues normally.

If validation fails, Guardian throws:

```
GuardianValidationException
```

---

### Validation with Custom Exception

[](#validation-with-custom-exception)

You may provide a custom exception for validation failures.

```
use Aegisora\Guardian\Guardian;
use App\Exceptions\InvalidValueException;

$guardian = new Guardian();

$guardian->check(
    $value,
    FooRule::create(),
    new InvalidValueException()
);
```

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
=======================

[](#-fluent-validation-api)

Guardian supports fluent rule chaining through `GuardianExecutor`.

Example:

```
use Aegisora\Guardian\Guardian;

$guardian = new Guardian();

$guardian
    ->that($value)
    ->must(FirstRule::create())
    ->must(SecondRule::create())
    ->validate();
```

Execution behavior:

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

---

### Multiple Rules with Different Exceptions

[](#multiple-rules-with-different-exceptions)

Each rule may define its own exception.

```
$guardian
    ->that($value)
    ->must(
        EmailRule::create(),
        new InvalidEmailException()
    )
    ->must(
        PasswordRule::create(),
        new WeakPasswordException()
    )
    ->validate();
```

This enables extremely precise validation semantics.

---

🧩 Real-World Example: User Registration Validation
==================================================

[](#-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

[](#registration-command)

The command contains the data required to register a user.

```