Aegisora String Length Rule

String Length Rule provides a simple, rule-based string length validation implementation for the Aegisora ecosystem.

It is built on top of 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, usernames, passwords, API request parameters, database column constraints, and any other string that must satisfy a length boundary.

---

📑 Table of Contents

• Features
• Installation
• Core Concept
• Basic Usage
• Valid vs Invalid
• Validation Result
• Guardian Usage
• Real-World Examples
• Factory Methods
• Architecture
• License
• Contributing
• Support

---

✨ Features

• 🔹 Lightweight and dependency-free except aegisora/rule-contract
• 🔹 Validates a string length against a lower bound, an upper bound, or a range
• 🔹 Supports strict (>, <) and inclusive (>=, <=) comparisons
• 🔹 Counts characters (not bytes) via native mb_strlen(), so multibyte strings are measured correctly
• 🔹 Rejects non-string input as an invalid context
• 🔹 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

composer require aegisora/string-length-rule

---

🚀 Core Concept

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

• accepts a string value via Context
• checks whether the string length satisfies the configured boundary
• returns a standardized Result

Under the hood it wraps the common boilerplate:

$length = mb_strlen($value);

if ($length < $min || $length > $max) {
    // length 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

use Aegisora\RuleContract\Models\Context;
use Aegisora\Rules\StringLengthRule;

$result = StringLengthRule::createGreaterThanOrEqualTo(8)->validate(Context::create('super-secret'));

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

---

✅ Valid vs Invalid

The rule passes when the string length satisfies the configured boundary and fails otherwise. The length is measured in characters via mb_strlen().

Lower bound

StringLengthRule::createGreaterThan(3)->validate(Context::create('abcd'));         // valid   — 4 > 3
StringLengthRule::createGreaterThan(3)->validate(Context::create('abc'));          // invalid — 3 is not > 3

StringLengthRule::createGreaterThanOrEqualTo(3)->validate(Context::create('abc')); // valid   — 3 >= 3
StringLengthRule::createGreaterThanOrEqualTo(3)->validate(Context::create('ab'));  // invalid — 2 < 3

Upper bound

StringLengthRule::createLessThan(3)->validate(Context::create('ab'));              // valid   — 2 < 3
StringLengthRule::createLessThan(3)->validate(Context::create('abc'));             // invalid — 3 is not < 3

StringLengthRule::createLessThanOrEqualTo(3)->validate(Context::create('abc'));    // valid   — 3 <= 3
StringLengthRule::createLessThanOrEqualTo(3)->validate(Context::create('abcd'));   // invalid — 4 > 3

Range

StringLengthRule::createBetween(2, 4)->validate(Context::create('abc'));           // valid   — 2 <= 3 <= 4
StringLengthRule::createBetween(2, 4)->validate(Context::create('a'));             // invalid — 1 < 2

StringLengthRule::createBetweenExclusive(2, 4)->validate(Context::create('abc'));  // valid   — 2 < 3 < 4
StringLengthRule::createBetweenExclusive(2, 4)->validate(Context::create('ab'));   // invalid — 2 is not > 2

StringLengthRule::createBetweenMinExclusive(2, 4)->validate(Context::create('abcd')); // valid    — 2 < 4 <= 4
StringLengthRule::createBetweenMinExclusive(2, 4)->validate(Context::create('ab'));   // invalid  — 2 is not > 2

StringLengthRule::createBetweenMaxExclusive(2, 4)->validate(Context::create('ab'));   // valid    — 2 <= 2 < 4
StringLengthRule::createBetweenMaxExclusive(2, 4)->validate(Context::create('abcd')); // invalid  — 4 is not < 4

---

🧪 Validation Result

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

$result->isValid(); // true

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

$result->isValid(); // false
$result->getFailedRuleCode(); // string_length_rule

If the context value is not a string, the rule throws:

Aegisora\RuleContract\Exceptions\InvalidRuleContextException

---

🔗 Guardian Usage

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

use Aegisora\Guardian\Guardian;
use Aegisora\Rules\StringLengthRule;
use App\Exceptions\InvalidUsernameException;

$guardian = new Guardian();

$guardian
    ->that($username)
    ->must(StringLengthRule::createBetween(3, 32), new InvalidUsernameException())
    ->validate();

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

---

🧭 Real-World Examples

String Length Rule is useful for enforcing length constraints before values are persisted or processed.

Examples

User Registration:

require a username between 3 and 32 characters

Security:

require a password of at least 8 characters

Database:

ensure a value fits a VARCHAR column limit

API:

reject request parameters that exceed a maximum length

---

🧩 Factory Methods

StringLengthRule::createGreaterThan($length);

• passes when the string length is strictly greater than $length

StringLengthRule::createGreaterThanOrEqualTo($length);

• passes when the string length is greater than or equal to $length

StringLengthRule::createLessThan($length);

• passes when the string length is strictly less than $length

StringLengthRule::createLessThanOrEqualTo($length);

• passes when the string length is less than or equal to $length

StringLengthRule::createBetween($min, $max);

• passes when the string length is between $min and $max, both boundaries inclusive ($min <= length <= $max)

StringLengthRule::createBetweenExclusive($min, $max);

• passes when the string length is between $min and $max, both boundaries exclusive ($min < length < $max)

StringLengthRule::createBetweenMinExclusive($min, $max);

• passes when the string length is between $min (exclusive) and $max (inclusive) ($min < length <= $max)

StringLengthRule::createBetweenMaxExclusive($min, $max);

• passes when the string length is between $min (inclusive) and $max (exclusive) ($min <= length < $max)

StringLengthRule::createGreaterThanOrEqualTo($length)->validate($context);

• $context — Context wrapping the string value to validate

---

🏛️ Architecture

This package relies on aegisora/rule-contract.

Flow:

1. validate() is called
2. Context is passed in
3. The string value is extracted from context (non-strings raise InvalidRuleContextException)
4. The length is measured with mb_strlen()
5. The length is compared against the configured boundary
6. Result is returned — valid on success, invalid with the string_length_rule code on failure

All logic is safely handled by Rule contract.

---

⚖️ 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.