README

Emptiness Rule Guardian provides a simple shortcut for emptiness validation using aegisora/guardian and aegisora/emptiness-rule.

It is designed for cases where you want to quickly check whether a value is empty or is not empty, without manually building an EmptyRule / NotEmptyRule and a validation pipeline by hand.

This package is built on top of:

✨ Features

🔹 Simple shortcut API for EmptyRule and NotEmptyRule
🔹 Validates that a value is empty via checkEmpty()
🔹 Validates that a value is not empty via checkNotEmpty()
🔹 Works with scalars, arrays and countable objects
🔹 Uses aegisora/guardian internally
🔹 Uses aegisora/emptiness-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/emptiness-rule-guardian

🚀 Core Concept

This package wraps the common emptiness validation flow:

$guardian->check(
    $value,
    EmptyRule::create(),
    new ValueIsNotEmptyException()
);

$guardian->check(
    $value,
    NotEmptyRule::create(),
    new ValueIsEmptyException()
);

into a dedicated shortcut class:

$emptinessRuleGuardian->checkEmpty($value, new ValueIsNotEmptyException());
$emptinessRuleGuardian->checkNotEmpty($value, new ValueIsEmptyException());

Instead of manually creating an EmptyRule / NotEmptyRule and passing it to Guardian, you can use EmptinessRuleGuardian directly.

🏗️ Basic Usage

use Aegisora\Guardian\Guardian;
use Aegisora\Guardian\Exceptions\GuardianValidationException;
use Aegisora\RuleGuardians\EmptinessRuleGuardian\EmptinessRuleGuardian;

$guardian = new Guardian();

$emptinessRuleGuardian = new EmptinessRuleGuardian($guardian);

try {
    $emptinessRuleGuardian->checkEmpty($value);
    // $value is empty
} catch (GuardianValidationException $exception) {
    // $value is not empty
}

try {
    $emptinessRuleGuardian->checkNotEmpty($value);
    // $value is not empty
} catch (GuardianValidationException $exception) {
    // $value is empty
}

checkEmpty() passes when $value is empty, and fails otherwise.

checkNotEmpty() passes when $value is not empty, and fails otherwise.

✅ How the emptiness check works

A value is considered empty when it is null, an empty string, an empty array or an empty countable object. Every other value — including 0, 0.0, false and non-countable objects — is considered not empty:

$emptinessRuleGuardian->checkEmpty(null);                // passes (null)
$emptinessRuleGuardian->checkEmpty('');                  // passes (empty string)
$emptinessRuleGuardian->checkEmpty([]);                  // passes (empty array)
$emptinessRuleGuardian->checkEmpty(new ArrayObject([])); // passes (empty countable object)

$emptinessRuleGuardian->checkEmpty('foo');               // fails (non-empty string)
$emptinessRuleGuardian->checkEmpty([1]);                 // fails (non-empty array)
$emptinessRuleGuardian->checkEmpty(0);                   // fails (int)
$emptinessRuleGuardian->checkEmpty(0.0);                 // fails (float)
$emptinessRuleGuardian->checkEmpty(false);               // fails (bool)
$emptinessRuleGuardian->checkEmpty(new stdClass());      // fails (non-countable object)
$emptinessRuleGuardian->checkEmpty(new ArrayObject([1]));// fails (non-empty countable object)
$emptinessRuleGuardian->checkEmpty(static fn () => null);// fails (callable)

checkNotEmpty() is the exact inverse — it passes for every value listed above as fails and fails for every value listed as passes.

⚠️ A resource cannot be evaluated for emptiness. Passing a 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\EmptinessRuleGuardian\EmptinessRuleGuardian;
use App\Exceptions\ValueIsEmptyException;

$guardian = new Guardian();

$emptinessRuleGuardian = new EmptinessRuleGuardian($guardian);

$emptinessRuleGuardian->checkNotEmpty(
    $value,
    new ValueIsEmptyException()
);

If the value is empty, 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\EmptinessRuleGuardian\EmptinessRuleGuardian;
use App\Exceptions\EmptyPayloadException;

final class PayloadProcessor
{
    private EmptinessRuleGuardian $emptinessRuleGuardian;

    public function __construct(
        EmptinessRuleGuardian $emptinessRuleGuardian
    ) {
        $this->emptinessRuleGuardian = $emptinessRuleGuardian;
    }

    /**
     * @param mixed $payload
     */
    public function process($payload): void
    {
        $this->emptinessRuleGuardian->checkNotEmpty(
            $payload,
            new EmptyPayloadException()
        );

        // business logic for processing a non-empty payload
    }
}

🚨 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 a failed checkEmpty() is empty_rule, and for a failed checkNotEmpty() it is not_empty_rule.

use Aegisora\Guardian\Exceptions\GuardianValidationException;

try {
    $emptinessRuleGuardian->checkEmpty($value);
} catch (GuardianValidationException $exception) {
    echo $exception->getRuleCode(); // "empty_rule"
}

try {
    $emptinessRuleGuardian->checkNotEmpty($value);
} catch (GuardianValidationException $exception) {
    echo $exception->getRuleCode(); // "not_empty_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\ValueIsEmptyException;

try {
    $emptinessRuleGuardian->checkNotEmpty($value, new ValueIsEmptyException());
} catch (ValueIsEmptyException $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.

Emptiness cannot be determined for a resource, so passing a resource surfaces this exception instead of a validation result:

use Aegisora\Guardian\Exceptions\GuardianExecutingRuleException;

try {
    $emptinessRuleGuardian->checkEmpty(tmpfile());
} catch (GuardianExecutingRuleException $exception) {
    // the rule could not be executed
}

🧩 API

`EmptinessRuleGuardian::checkEmpty()`

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

Validates that $value is empty.

`EmptinessRuleGuardian::checkNotEmpty()`

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

Validates that $value is not empty.

Arguments (both methods):

$value — the value to validate
$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 emptiness 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

🏛️ Architecture

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

Flow:

EmptinessRuleGuardian::checkEmpty() / checkNotEmpty() is called with a value and an optional exception
An EmptyRule / NotEmptyRule is created (create())
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 → EmptinessRuleGuardian → Guardian → EmptyRule / NotEmptyRule → Result → Exception

🔗 Related Packages

aegisora/guardian — validation execution orchestrator
aegisora/emptiness-rule — empty and not empty rules
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 / emptiness-rule-guardian

Maintainers

Package info

Statistics

Security