README

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:

✨ 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:

InArrayRuleGuardian::checkStrict() / checkSoft() is called
InArrayRule::createStrict() / InArrayRule::createSoft() is created
Guardian executes the rule
If validation succeeds, execution continues normally
If validation fails, the custom exception or GuardianValidationException is thrown
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.

aegisora / in-array-rule-guardian

Maintainers

Package info

Statistics

Security