PHPackages                             aegisora/numeric-range-rule - 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/numeric-range-rule

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

aegisora/numeric-range-rule
===========================

Numeric Range Rule provides a simple, rule-based numeric range validation implementation for the Aegisora ecosystem

v1.0.0(today)01↑2900%MITPHPPHP >=7.4

Since Aug 29Pushed todayCompare

[ Source](https://github.com/Aegisora/numeric-range-rule)[ Packagist](https://packagist.org/packages/aegisora/numeric-range-rule)[ Docs](https://github.com/Aegisora/numeric-range-rule)[ RSS](/packages/aegisora-numeric-range-rule/feed)WikiDiscussions main Synced today

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

Aegisora Numeric Range Rule
===========================

[](#aegisora-numeric-range-rule)

[![Latest Version](https://camo.githubusercontent.com/b739db25472bb9fd5d31c89857402e9aee2c6bf07ca4c467927e504e202445eb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61656769736f72612f6e756d657269632d72616e67652d72756c653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aegisora/numeric-range-rule)[![Total Downloads](https://camo.githubusercontent.com/4b686ba5c7aa69c5b9c18a06e63fd5c8116705ba4f3d461df00f5873fe808a06/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61656769736f72612f6e756d657269632d72616e67652d72756c653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aegisora/numeric-range-rule)[![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)

Numeric Range Rule provides a simple, rule-based numeric range validation implementation for the Aegisora ecosystem.

It is built on top of [`aegisora/rule-contract`](https://github.com/Aegisora/rule-contract) and follows its strict validation architecture, ensuring consistent and predictable behavior across applications.

This rule is useful for validating user input, form fields, prices, quantities, ages, percentages, API request parameters, configuration values, and any other numeric value that must satisfy a range boundary.

---

📑 Table of Contents
-------------------

[](#-table-of-contents)

- [Features](#-features)
- [Installation](#-installation)
- [Core Concept](#-core-concept)
- [Basic Usage](#-basic-usage)
- [Valid vs Invalid](#-valid-vs-invalid)
- [Validation Result](#-validation-result)
- [Guardian Usage](#-guardian-usage)
- [Real-World Examples](#-real-world-examples)
- [Factory Methods](#-factory-methods)
- [Architecture](#-architecture)
- [License](#-license)
- [Contributing](#-contributing)
- [Support](#-support)

---

✨ Features
----------

[](#-features)

- 🔹 Lightweight and dependency-free except `aegisora/rule-contract`
- 🔹 Validates a numeric value against a lower bound, an upper bound, or a range
- 🔹 Supports strict (`>`, `=`, ` max`) at construction time
- 🔹 Fully compatible with Aegisora validation pipeline
- 🔹 Strict `Context` → `Result` validation flow
- 🔹 No raw booleans — only structured results
- 🔹 Safe execution via base `Rule` abstraction
- 🔹 Expressive factory API for every boundary variation
- 🔹 Ready to use out of the box

---

📦 Installation
--------------

[](#-installation)

```
composer require aegisora/numeric-range-rule
```

---

🚀 Core Concept
--------------

[](#-core-concept)

This package implements a single validation rule with several factory variations:

- accepts a numeric value via `Context`
- checks whether the value satisfies the configured boundary
- returns a standardized `Result`

Under the hood it wraps the common boilerplate:

```
if ($value < $min || $value > $max) {
    // value is out of the allowed boundary
}
```

into a reusable rule that reports its outcome through a `Result` object instead of a raw boolean.

---

🏗️ Basic Usage
--------------

[](#️-basic-usage)

```
use Aegisora\RuleContract\Models\Context;
use Aegisora\Rules\NumericRangeRule;

$result = NumericRangeRule::createBetween(1, 100)->validate(Context::create(42));

if ($result->isValid()) {
    // value satisfies the boundary
} else {
    // value is out of the allowed boundary
}
```

---

✅ Valid vs Invalid
------------------

[](#-valid-vs-invalid)

The rule passes when the numeric value satisfies the configured boundary and fails otherwise. Integers, floats, and numeric strings are all accepted as input.

### Lower bound

[](#lower-bound)

```
NumericRangeRule::createGreaterThan(3)->validate(Context::create(4));         // valid   — 4 > 3
NumericRangeRule::createGreaterThan(3)->validate(Context::create(3));         // invalid — 3 is not > 3

NumericRangeRule::createGreaterThanOrEqualTo(3)->validate(Context::create(3)); // valid   — 3 >= 3
NumericRangeRule::createGreaterThanOrEqualTo(3)->validate(Context::create(2)); // invalid — 2 < 3
```

### Upper bound

[](#upper-bound)

```
NumericRangeRule::createLessThan(3)->validate(Context::create(2));            // valid   — 2 < 3
NumericRangeRule::createLessThan(3)->validate(Context::create(3));            // invalid — 3 is not < 3

NumericRangeRule::createLessThanOrEqualTo(3)->validate(Context::create(3));   // valid   — 3 validate(Context::create(4));   // invalid — 4 > 3
```

### Range

[](#range)

```
NumericRangeRule::createBetween(2, 4)->validate(Context::create(3));          // valid   — 2 validate(Context::create(3)); // valid   — 2 < 3 < 4
NumericRangeRule::createBetweenExclusive(2, 4)->validate(Context::create(2)); // invalid — 2 is not > 2

NumericRangeRule::createBetweenMinExclusive(2, 4)->validate(Context::create(4)); // valid    — 2 < 4 validate(Context::create(2)); // invalid  — 2 is not > 2

NumericRangeRule::createBetweenMaxExclusive(2, 4)->validate(Context::create(2)); // valid    — 2 validate(Context::create(4)); // invalid  — 4 is not < 4
```

---

🧪 Validation Result
-------------------

[](#-validation-result)

If the value satisfies the boundary, the rule returns a valid result.

`$result->isValid(); // true`

If the value is out of the boundary, the rule returns an invalid result.

```
$result->isValid(); // false
$result->getFailedRuleCode(); // numeric_range_rule
```

If the context value is not numeric, the rule throws:

`Aegisora\RuleContract\Exceptions\InvalidRuleContextException`

The same exception is thrown at construction time when the range configuration is impossible, e.g. `NumericRangeRule::createBetween(4, 2)` (`$min > $max`) or an empty exclusive range such as `NumericRangeRule::createBetweenExclusive(3, 3)`.

---

🔗 Guardian Usage
----------------

[](#-guardian-usage)

This rule can be used together with `aegisora/guardian` to build fluent validation pipelines.

```
use Aegisora\Guardian\Guardian;
use Aegisora\Rules\NumericRangeRule;
use App\Exceptions\InvalidAgeException;

$guardian = new Guardian();

$guardian
    ->that($age)
    ->must(NumericRangeRule::createBetween(18, 120), new InvalidAgeException())
    ->validate();
```

If the value is out of the allowed boundary, `Guardian` throws the provided domain exception.

---

🧭 Real-World Examples
---------------------

[](#-real-world-examples)

Numeric Range Rule is useful for enforcing range constraints before values are persisted or processed.

Examples

```
User Registration:

require an age between 18 and 120

```

```
E-commerce:

require a quantity of at least 1

```

```
Configuration:

ensure a percentage stays between 0 and 100

```

```
API:

reject request parameters that fall outside an allowed range

```

---

🧩 Factory Methods
-----------------

[](#-factory-methods)

`NumericRangeRule::createGreaterThan($min);`

- passes when the value is strictly greater than `$min`

`NumericRangeRule::createGreaterThanOrEqualTo($min);`

- passes when the value is greater than or equal to `$min`

`NumericRangeRule::createLessThan($max);`

- passes when the value is strictly less than `$max`

`NumericRangeRule::createLessThanOrEqualTo($max);`

- passes when the value is less than or equal to `$max`

`NumericRangeRule::createBetween($min, $max);`

- passes when the value is between `$min` and `$max`, both boundaries inclusive (`$min