Aegisora In-Array Rule Guardian

In-Array Rule Guardian provides a simple shortcut for in-array value validation using aegisora/guardian and aegisora/in-array-rule.

It is designed for cases where you want to quickly check whether a value is contained in a given array without manually creating validation pipelines.

This package is built on top of:

• aegisora/guardian
• aegisora/in-array-rule

---

✨ Features

• 🔹 Simple shortcut API for InArrayRule
• 🔹 Validates whether a value is present in an array
• 🔹 Supports both strict and soft (loose) comparison
• 🔹 Uses aegisora/guardian internally
• 🔹 Uses aegisora/in-array-rule internally
• 🔹 Supports custom validation exceptions
• 🔹 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/in-array-rule-guardian

---

🚀 Core Concept

This package wraps the common validation flow:

$guardian->check($value, InArrayRule::createStrict($actualArray), new NotInArrayException());

into a dedicated shortcut class:

$inArrayRuleGuardian->checkStrict($value, $actualArray, new NotInArrayException());

Instead of manually creating InArrayRule and passing it to Guardian, you can use InArrayRuleGuardian directly.

---

🏗️ Basic Usage

use Aegisora\Guardian\Guardian;
use Aegisora\Guardian\Exceptions\GuardianValidationException;
use Aegisora\RuleGuardians\InArrayRule\InArrayRuleGuardian;

$guardian = new Guardian();

$inArrayRuleGuardian = new InArrayRuleGuardian($guardian);

try {
    $inArrayRuleGuardian->checkStrict(2, [1, 2, 3]);
    // value is present in the array
} catch (GuardianValidationException $exception) {
    // value is not present in the array
}

---

⚖️ Strict vs Soft Comparison

The package exposes two methods that differ only in how values are compared.

checkStrict()

Uses strict comparison (===). Both the type and the value must match.

$inArrayRuleGuardian->checkStrict('2', [1, 2, 3]); // fails: '2' !== 2
$inArrayRuleGuardian->checkStrict(2, [1, 2, 3]);   // passes

checkSoft()

Uses loose comparison (==). Only the value must match after type juggling.

$inArrayRuleGuardian->checkSoft('2', [1, 2, 3]); // passes: '2' == 2
$inArrayRuleGuardian->checkSoft(0, ['0']);       // passes: 0 == '0'

Both methods share the same signature and behaviour regarding exceptions — only the comparison mode changes.

---

🧩 Usage with Custom Exception

You may provide your own exception for validation failure.

use Aegisora\Guardian\Guardian;
use Aegisora\RuleGuardians\InArrayRule\InArrayRuleGuardian;
use App\Exceptions\NotInArrayException;

$guardian = new Guardian();

$inArrayRuleGuardian = new InArrayRuleGuardian($guardian);

$inArrayRuleGuardian->checkStrict(4, [1, 2, 3], new NotInArrayException());

If the value is not present in the array, the provided exception will be thrown.

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

---

🧪 Example in Application Service

use Aegisora\RuleGuardians\InArrayRule\InArrayRuleGuardian;
use App\Exceptions\InvalidStatusException;

final class OrderService
{
    private const ALLOWED_STATUSES = ['pending', 'paid', 'shipped', 'cancelled'];

    private InArrayRuleGuardian $inArrayRuleGuardian;

    public function __construct(
        InArrayRuleGuardian $inArrayRuleGuardian
    ) {
        $this->inArrayRuleGuardian = $inArrayRuleGuardian;
    }

    /**
     * @param mixed $status
     */
    public function updateStatus($status): void
    {
        $this->inArrayRuleGuardian->checkStrict($status, self::ALLOWED_STATUSES, new InvalidStatusException());

        // business logic for a valid status
    }
}

---

🚨 Exceptions

This package does not define its own exception types. It delegates execution to Guardian and re-throws the exceptions raised by the underlying pipeline.

GuardianValidationException

Thrown when validation fails and no custom exception is provided.

The rule code for failed in-array validation is in_array_rule.

use Aegisora\Guardian\Exceptions\GuardianValidationException;

try {
    $inArrayRuleGuardian->checkStrict(4, [1, 2, 3]);
} catch (GuardianValidationException $exception) {
    echo $exception->getRuleCode(); // "in_array_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\NotInArrayException;

try {
    $inArrayRuleGuardian->checkStrict(4, [1, 2, 3], new NotInArrayException());
} catch (NotInArrayException $exception) {
    // domain-specific handling
}

GuardianExecutingRuleException

Thrown when the underlying rule execution fails.

use Aegisora\Guardian\Exceptions\GuardianExecutingRuleException;

try {
    $inArrayRuleGuardian->checkStrict($value, $actualArray);
} catch (GuardianExecutingRuleException $exception) {
    // the rule could not be executed
}

---

🧩 API

InArrayRuleGuardian::checkStrict()

/**
 * @param mixed $value
 * @param mixed[] $actualArray
 * @throws GuardianExecutingRuleException
 * @throws GuardianValidationException
 * @throws \Throwable
 */
public function checkStrict(
    $value,
    array $actualArray,
    ?\Throwable $exception = null
): void

Validates that $value is present in $actualArray using strict comparison (===).

InArrayRuleGuardian::checkSoft()

/**
 * @param mixed $value
 * @param mixed[] $actualArray
 * @throws GuardianExecutingRuleException
 * @throws GuardianValidationException
 * @throws \Throwable
 */
public function checkSoft(
    $value,
    array $actualArray,
    ?\Throwable $exception = null
): void

Validates that $value is present in $actualArray using loose comparison (==).

Parameters (both methods):

• $value (mixed) — value to look for in the array
• $actualArray (mixed[]) — array of allowed values (the haystack)
• $exception (?\Throwable, default null) — optional custom exception thrown on validation failure

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

• GuardianValidationException — validation failed and no custom exception was provided
• the provided custom exception — validation failed and a custom exception was passed
• GuardianExecutingRuleException — the underlying rule failed to execute

Example:

$inArrayRuleGuardian->checkStrict(2, [1, 2, 3]);

With custom exception:

$inArrayRuleGuardian->checkSoft('2', [1, 2, 3], new NotInArrayException());

---

🏛️ Architecture

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

Flow:

1. InArrayRuleGuardian::checkStrict() / checkSoft() is called
2. InArrayRule::createStrict() / InArrayRule::createSoft() is created
3. Guardian executes the rule
4. If validation succeeds, execution continues normally
5. If validation fails, the custom exception or GuardianValidationException is thrown
6. If rule execution fails, GuardianExecutingRuleException is thrown

Internal flow:

Value → InArrayRuleGuardian → Guardian → InArrayRule → Result → Exception

---

🔗 Related Packages

• aegisora/guardian — validation execution orchestrator
• aegisora/in-array-rule — rule-based in-array validation
• 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.