README

Boolean Rule Guardian provides a simple shortcut for boolean value validation using aegisora/guardian and aegisora/boolean-rule.

It is designed for cases where you want to quickly check whether a value is strictly true or strictly false without manually creating validation pipelines.

This package is built on top of:

✨ Features

🔹 Simple shortcut API for BooleanRule
🔹 Validates whether a value is strictly true or strictly false
🔹 Uses strict comparison (===) — no type juggling
🔹 Uses aegisora/guardian internally
🔹 Uses aegisora/boolean-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/boolean-rule-guardian

🚀 Core Concept

This package wraps the common validation flow:

$guardian->check($value, BooleanRule::createTruthy(), new NotTruthyException());

into a dedicated shortcut class:

$booleanRuleGuardian->checkTruthy($value, new NotTruthyException());

Instead of manually creating BooleanRule and passing it to Guardian, you can use BooleanRuleGuardian directly.

🏗️ Basic Usage

use Aegisora\Guardian\Guardian;
use Aegisora\Guardian\Exceptions\GuardianValidationException;
use Aegisora\RuleGuardians\BooleanRule\BooleanRuleGuardian;

$guardian = new Guardian();

$booleanRuleGuardian = new BooleanRuleGuardian($guardian);

try {
    $booleanRuleGuardian->checkTruthy(true);
    // value is strictly true
} catch (GuardianValidationException $exception) {
    // value is not true
}

✅ Truthy vs Falsy

The package exposes two methods that differ only in the expected boolean value.

`checkTruthy()`

Passes when the value is strictly true.

$booleanRuleGuardian->checkTruthy(true);  // passes
$booleanRuleGuardian->checkTruthy(false); // fails

`checkFalsy()`

Passes when the value is strictly false.

$booleanRuleGuardian->checkFalsy(false); // passes
$booleanRuleGuardian->checkFalsy(true);  // fails

Both methods use strict comparison (===). No type juggling is performed — only real booleans are accepted as valid input (see Exceptions).

🧩 Usage with Custom Exception

You may provide your own exception for validation failure.

use Aegisora\Guardian\Guardian;
use Aegisora\RuleGuardians\BooleanRule\BooleanRuleGuardian;
use App\Exceptions\NotTruthyException;

$guardian = new Guardian();

$booleanRuleGuardian = new BooleanRuleGuardian($guardian);

$booleanRuleGuardian->checkTruthy(false, new NotTruthyException());

If the value is not true, the provided exception will be thrown.

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

🧪 Example in Application Service

use Aegisora\RuleGuardians\BooleanRule\BooleanRuleGuardian;
use App\Exceptions\ConsentRequiredException;

final class RegistrationService
{
    private BooleanRuleGuardian $booleanRuleGuardian;

    public function __construct(
        BooleanRuleGuardian $booleanRuleGuardian
    ) {
        $this->booleanRuleGuardian = $booleanRuleGuardian;
    }

    public function register(bool $termsAccepted): void
    {
        $this->booleanRuleGuardian->checkTruthy($termsAccepted, new ConsentRequiredException());

        // business logic for an accepted agreement
    }
}

🚨 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 boolean validation is boolean_rule.

use Aegisora\Guardian\Exceptions\GuardianValidationException;

try {
    $booleanRuleGuardian->checkTruthy(false);
} catch (GuardianValidationException $exception) {
    echo $exception->getRuleCode(); // "boolean_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\NotTruthyException;

try {
    $booleanRuleGuardian->checkTruthy(false, new NotTruthyException());
} catch (NotTruthyException $exception) {
    // domain-specific handling
}

`GuardianExecutingRuleException`

Thrown when the underlying rule execution fails.

This happens, for example, when the value is not a real boolean (e.g. 1, 'true', '', [], null). The rule only accepts true or false; any other type is treated as an execution error, not a validation failure.

use Aegisora\Guardian\Exceptions\GuardianExecutingRuleException;

try {
    $booleanRuleGuardian->checkTruthy(1); // not a real boolean
} catch (GuardianExecutingRuleException $exception) {
    // the rule could not be executed
}

🧩 API

`BooleanRuleGuardian::checkTruthy()`

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

Validates that $value is strictly true (=== true).

`BooleanRuleGuardian::checkFalsy()`

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

Validates that $value is strictly false (=== false).

Parameters (both methods):

$value (mixed) — value to validate; must be a real boolean
$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 (e.g. the value is not a real boolean)

Example:

$booleanRuleGuardian->checkTruthy(true);

With custom exception:

$booleanRuleGuardian->checkFalsy(true, new NotFalsyException());

🏛️ Architecture

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

Flow:

BooleanRuleGuardian::checkTruthy() / checkFalsy() is called
BooleanRule::createTruthy() / BooleanRule::createFalsy() 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 → BooleanRuleGuardian → Guardian → BooleanRule → Result → Exception

🔗 Related Packages

aegisora/guardian — validation execution orchestrator
aegisora/boolean-rule — rule-based boolean 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 / boolean-rule-guardian

Maintainers

Package info

Statistics

Security