README

String Length Rule Guardian provides a simple shortcut for string length validation using aegisora/guardian and aegisora/string-length-rule.

It is designed for cases where you want to quickly check whether a string's length satisfies a boundary — greater than, less than, or between two values — without manually building a StringLengthRule and a validation pipeline by hand.

This package is built on top of:

✨ Features

🔹 Simple shortcut API for StringLengthRule
🔹 Validates a minimum length via checkGreaterThan() / checkGreaterThanOrEqualTo()
🔹 Validates a maximum length via checkLessThan() / checkLessThanOrEqualTo()
🔹 Validates a range via checkBetween() and its exclusive variants
🔹 Measures length in characters using mb_strlen() (multibyte-safe)
🔹 Uses aegisora/guardian internally
🔹 Uses aegisora/string-length-rule internally
🔹 Supports a custom validation exception
🔹 Keeps rule execution errors separated from validation errors
🔹 Fully compatible with the Aegisora ecosystem
🔹 Ready to use out of the box

📦 Installation

composer require aegisora/string-length-rule-guardian

🚀 Core Concept

This package wraps the common string length validation flow:

$guardian->check(
    $value,
    StringLengthRule::createGreaterThan($length),
    new StringIsTooShortException()
);

$guardian->check(
    $value,
    StringLengthRule::createBetween($min, $max),
    new StringLengthOutOfRangeException()
);

into a dedicated shortcut class:

$stringLengthRuleGuardian->checkGreaterThan($value, $length, new StringIsTooShortException());
$stringLengthRuleGuardian->checkBetween($value, $min, $max, new StringLengthOutOfRangeException());

Instead of manually creating a StringLengthRule and passing it to Guardian, you can use StringLengthRuleGuardian directly.

🏗️ Basic Usage

use Aegisora\Guardian\Guardian;
use Aegisora\Guardian\Exceptions\GuardianValidationException;
use Aegisora\RuleGuardians\StringLengthRule\StringLengthRuleGuardian;

$guardian = new Guardian();

$stringLengthRuleGuardian = new StringLengthRuleGuardian($guardian);

try {
    $stringLengthRuleGuardian->checkGreaterThan($value, 3);
    // $value is longer than 3 characters
} catch (GuardianValidationException $exception) {
    // $value is not longer than 3 characters
}

try {
    $stringLengthRuleGuardian->checkBetween($value, 2, 4);
    // $value length is between 2 and 4 characters
} catch (GuardianValidationException $exception) {
    // $value length is out of the [2, 4] range
}

Every method passes when the string length satisfies the boundary, and fails otherwise.

✅ How the length check works

The length is the number of characters in the string, measured with mb_strlen(), so multibyte strings are counted correctly ('абвг' has a length of 4, not 8).

Boundaries are inclusive or exclusive depending on the method:

// minimum length
$stringLengthRuleGuardian->checkGreaterThan('abcd', 3);          // passes (4 > 3)
$stringLengthRuleGuardian->checkGreaterThan('abc', 3);           // fails  (3 > 3 is false)
$stringLengthRuleGuardian->checkGreaterThanOrEqualTo('abc', 3);  // passes (3 >= 3)
$stringLengthRuleGuardian->checkGreaterThanOrEqualTo('ab', 3);   // fails  (2 >= 3 is false)

// maximum length
$stringLengthRuleGuardian->checkLessThan('ab', 3);               // passes (2 < 3)
$stringLengthRuleGuardian->checkLessThan('abc', 3);              // fails  (3 < 3 is false)
$stringLengthRuleGuardian->checkLessThanOrEqualTo('abc', 3);     // passes (3 <= 3)
$stringLengthRuleGuardian->checkLessThanOrEqualTo('abcd', 3);    // fails  (4 <= 3 is false)

// range (min = 2, max = 4)
$stringLengthRuleGuardian->checkBetween('ab', 2, 4);             // passes (both bounds inclusive)
$stringLengthRuleGuardian->checkBetween('abcd', 2, 4);           // passes
$stringLengthRuleGuardian->checkBetween('a', 2, 4);              // fails  (below min)
$stringLengthRuleGuardian->checkBetween('abcde', 2, 4);          // fails  (above max)

$stringLengthRuleGuardian->checkBetweenExclusive('abc', 2, 4);   // passes (both bounds exclusive)
$stringLengthRuleGuardian->checkBetweenExclusive('ab', 2, 4);    // fails  (equal to min)
$stringLengthRuleGuardian->checkBetweenExclusive('abcd', 2, 4);  // fails  (equal to max)

$stringLengthRuleGuardian->checkBetweenMinExclusive('abcd', 2, 4); // passes (min exclusive, max inclusive)
$stringLengthRuleGuardian->checkBetweenMinExclusive('ab', 2, 4);   // fails  (equal to min)

$stringLengthRuleGuardian->checkBetweenMaxExclusive('ab', 2, 4);   // passes (min inclusive, max exclusive)
$stringLengthRuleGuardian->checkBetweenMaxExclusive('abcd', 2, 4); // fails  (equal to max)

⚠️ Only strings can be evaluated for length. Passing a non-string value (int, float, bool, null, array, object, callable, resource) raises a GuardianExecutingRuleException (see below) instead of a validation result.

🧩 Usage with Custom Exception

You may provide your own exception for validation failure. It must be the last argument.

use Aegisora\Guardian\Guardian;
use Aegisora\RuleGuardians\StringLengthRule\StringLengthRuleGuardian;
use App\Exceptions\StringIsTooShortException;

$guardian = new Guardian();

$stringLengthRuleGuardian = new StringLengthRuleGuardian($guardian);

$stringLengthRuleGuardian->checkGreaterThanOrEqualTo(
    $value,
    8,
    new StringIsTooShortException()
);

If the length check fails, the provided exception will be thrown instead of GuardianValidationException.

This is useful when validation errors should have domain-specific meaning.

🧪 Example in Application Service

use Aegisora\RuleGuardians\StringLengthRule\StringLengthRuleGuardian;
use App\Exceptions\InvalidPasswordLengthException;

final class PasswordValidator
{
    private StringLengthRuleGuardian $stringLengthRuleGuardian;

    public function __construct(
        StringLengthRuleGuardian $stringLengthRuleGuardian
    ) {
        $this->stringLengthRuleGuardian = $stringLengthRuleGuardian;
    }

    public function validate(string $password): void
    {
        $this->stringLengthRuleGuardian->checkBetween(
            $password,
            8,
            64,
            new InvalidPasswordLengthException()
        );

        // business logic for a password of valid length
    }
}

🚨 Exceptions

The package raises validation-related exceptions, all delegated to Guardian (the outcome of running the rule):

`GuardianValidationException`

Thrown when validation fails and no custom exception is provided.

The rule code for every failed check is string_length_rule.

use Aegisora\Guardian\Exceptions\GuardianValidationException;

try {
    $stringLengthRuleGuardian->checkGreaterThan($value, 3);
} catch (GuardianValidationException $exception) {
    echo $exception->getRuleCode(); // "string_length_rule"
}

Custom exception

When a custom exception is passed as the last argument, it is thrown instead of GuardianValidationException on validation failure.

use App\Exceptions\StringIsTooShortException;

try {
    $stringLengthRuleGuardian->checkGreaterThan($value, 3, new StringIsTooShortException());
} catch (StringIsTooShortException $exception) {
    // domain-specific handling
}

`GuardianExecutingRuleException`

Thrown when the underlying rule fails to execute (raises a RuleException during validation), as opposed to simply reporting an invalid result.

Length can only be determined for a string, so passing a non-string value surfaces this exception instead of a validation result:

use Aegisora\Guardian\Exceptions\GuardianExecutingRuleException;

try {
    $stringLengthRuleGuardian->checkGreaterThan(123, 3);
} catch (GuardianExecutingRuleException $exception) {
    // the rule could not be executed
}

🧩 API

All methods share the same shape: they take the $value to validate, one or two length boundaries, and an optional custom \Throwable thrown on validation failure. They return void and communicate results through exceptions only.

Minimum length

/**
 * @param mixed $value
 * @throws GuardianExecutingRuleException
 * @throws GuardianValidationException
 * @throws \Throwable
 */
public function checkGreaterThan($value, int $length, ?\Throwable $exception = null): void

public function checkGreaterThanOrEqualTo($value, int $length, ?\Throwable $exception = null): void

checkGreaterThan() passes when the length is strictly greater than $length. checkGreaterThanOrEqualTo() passes when the length is greater than or equal to $length.

Maximum length

public function checkLessThan($value, int $length, ?\Throwable $exception = null): void

public function checkLessThanOrEqualTo($value, int $length, ?\Throwable $exception = null): void

checkLessThan() passes when the length is strictly less than $length. checkLessThanOrEqualTo() passes when the length is less than or equal to $length.

Range

public function checkBetween($value, int $min, int $max, ?\Throwable $exception = null): void

public function checkBetweenExclusive($value, int $min, int $max, ?\Throwable $exception = null): void

public function checkBetweenMinExclusive($value, int $min, int $max, ?\Throwable $exception = null): void

public function checkBetweenMaxExclusive($value, int $min, int $max, ?\Throwable $exception = null): void

Method	Min bound	Max bound
`checkBetween()`	inclusive	inclusive
`checkBetweenExclusive()`	exclusive	exclusive
`checkBetweenMinExclusive()`	exclusive	inclusive
`checkBetweenMaxExclusive()`	inclusive	exclusive

Arguments:

$value — the value to validate
$length / $min / $max — the length boundaries in characters
$exception — an optional custom \Throwable to be thrown on validation failure

The methods return void. They communicate results through exceptions only — they return nothing on success and throw on failure:

GuardianValidationException — the length check failed and no custom exception was provided
the provided custom exception — the check failed and a custom exception was passed
GuardianExecutingRuleException — the rule could not be executed (e.g. a non-string value)

🏛️ Architecture

This package is a small shortcut layer over the Aegisora validation pipeline.

Flow:

A check*() method is called with a value, one or two length boundaries and an optional exception
A StringLengthRule is created via the matching factory (createGreaterThan(), createBetween(), …)
Guardian executes the rule against the value
If the check passes, execution continues normally
If the check fails, the custom exception or GuardianValidationException is thrown
If the rule could not be executed, GuardianExecutingRuleException is thrown

Internal flow:

value → StringLengthRuleGuardian → Guardian → StringLengthRule → Result → Exception

🔗 Related Packages

aegisora/guardian — validation execution orchestrator
aegisora/string-length-rule — string length rule
aegisora/rule-contract — base rule contract and validation result architecture

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

aegisora / string-length-rule-guardian

Maintainers

Package info

Statistics

Security