Download the PHP package aegisora/boolean-rule-guardian without Composer

Aegisora Boolean Rule Guardian

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:

• aegisora/guardian
• aegisora/boolean-rule

✨ 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

🚀 Core Concept

This package wraps the common validation flow:

into a dedicated shortcut class:

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

🏗️ Basic Usage

✅ Truthy vs Falsy

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

checkTruthy()

Passes when the value is strictly true.

checkFalsy()

Passes when the value is strictly false.

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.

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

🚨 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.

Custom exception

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

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.

🧩 API

BooleanRuleGuardian::checkTruthy()

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

BooleanRuleGuardian::checkFalsy()

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:

With custom exception:

🏛️ Architecture

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

Flow:

1. BooleanRuleGuardian::checkTruthy() / checkFalsy() is called
2. BooleanRule::createTruthy() / BooleanRule::createFalsy() 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:

🔗 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.