README

Instanceof Rule Guardian provides a simple shortcut for object type validation using aegisora/guardian and aegisora/instanceof-rule.

It is designed for cases where you want to quickly check whether a value is an instance of a given class without manually creating validation pipelines.

This package is built on top of:

✨ Features

🔹 Simple shortcut API for InstanceofRule
🔹 Validates whether a value is an instance of a given class
🔹 Uses aegisora/guardian internally
🔹 Uses aegisora/instanceof-rule internally
🔹 Supports custom validation exceptions
🔹 Provides package-specific exception types
🔹 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/instanceof-rule-guardian

🚀 Core Concept

This package wraps the common validation flow:

$guardian->check($value, InstanceofRule::create(User::class), new InvalidUserObjectException());

into a dedicated shortcut class:

$instanceofRuleGuardian->check($value, User::class, new InvalidUserObjectException());

Instead of manually creating InstanceofRule and passing it to Guardian, you can use InstanceofRuleGuardian directly.

🏗️ Basic Usage

use Aegisora\Guardian\Guardian;
use Aegisora\RuleGuardians\InstanceofRule\InstanceofRuleGuardian;
use Aegisora\RuleGuardians\InstanceofRule\Exceptions\NotInstanceofException;

class User {}

$guardian = new Guardian();

$instanceofRuleGuardian = new InstanceofRuleGuardian($guardian);

try {
    $instanceofRuleGuardian->check(new User(), User::class);
    // value is instance of User
} catch (NotInstanceofException $exception) {
    // value is not instance of User
}

🧩 Usage with Custom Exception

You may provide your own exception for validation failure.

use Aegisora\Guardian\Guardian;
use Aegisora\RuleGuardians\InstanceofRule\InstanceofRuleGuardian;
use App\Exceptions\InvalidUserObjectException;

class User {}

$guardian = new Guardian();

$instanceofRuleGuardian = new InstanceofRuleGuardian($guardian);

$instanceofRuleGuardian->check(new \stdClass(), User::class, new InvalidUserObjectException());

If the value is not an instance of User, the provided exception will be thrown.

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

🧪 Example in Application Service

use Aegisora\RuleGuardians\InstanceofRule\InstanceofRuleGuardian;
use App\Exceptions\InvalidUserObjectException;

class User {}

final class UserService
{
    private InstanceofRuleGuardian $instanceofRuleGuardian;

    public function __construct(
        InstanceofRuleGuardian $instanceofRuleGuardian
    ) {
        $this->instanceofRuleGuardian = $instanceofRuleGuardian;
    }

    /**
     * @param mixed $value
     */
    public function process($value): void
    {
        $this->instanceofRuleGuardian->check($value, User::class, new InvalidUserObjectException());

        // business logic for valid User object
    }
}

🚨 Exceptions

This package provides dedicated exceptions for predictable error handling.

All exceptions extend the abstract base class Aegisora\RuleGuardians\InstanceofRule\Exceptions\InstanceofRuleGuardianException, so you can catch every error raised by this package with a single catch:

use Aegisora\RuleGuardians\InstanceofRule\Exceptions\InstanceofRuleGuardianException;

try {
    $instanceofRuleGuardian->check($value, User::class);
} catch (InstanceofRuleGuardianException $exception) {
    // handles NotInstanceofException, ExecutingRuleException and ExecutingCheckException
}

`NotInstanceofException`

Thrown when validation fails and no custom exception is provided.

use Aegisora\RuleGuardians\InstanceofRule\Exceptions\NotInstanceofException;

try {
    $instanceofRuleGuardian->check(new \stdClass(), User::class);
} catch (NotInstanceofException $exception) {
    echo $exception->getRuleCode();
}

`ExecutingRuleException`

Thrown when the underlying rule execution fails.

Internally, Guardian converts rule execution failures into GuardianExecutingRuleException. This package wraps it into:

Aegisora\RuleGuardians\InstanceofRule\Exceptions\ExecutingRuleException

`ExecutingCheckException`

Thrown when an unexpected error occurs during the shortcut check process.

Aegisora\RuleGuardians\InstanceofRule\Exceptions\ExecutingCheckException

🧩 API

`InstanceofRuleGuardian::check()`

/**
 * @param mixed $value
 */
public function check(
    $value,
    string $targetClassName,
    ?\Throwable $exception = null
): void

Parameters:

$value (mixed) — value to validate
$targetClassName (string) — fully qualified class name to check against
$exception (?\Throwable, default null) — optional custom exception thrown on validation failure

Returns void. The method communicates results through exceptions only — it returns nothing on success and throws on failure:

NotInstanceofException — validation failed and no custom exception was provided
ExecutingRuleException — the underlying rule failed to execute
ExecutingCheckException — an unexpected error occurred during the check

Example:

$instanceofRuleGuardian->check($value, User::class);

With custom exception:

$instanceofRuleGuardian->check($value, User::class, new InvalidUserObjectException());

🏛️ Architecture

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

Flow:

InstanceofRuleGuardian::check() is called
InstanceofRule::create($targetClassName) is created
Guardian executes the rule
If validation succeeds, execution continues normally
If validation fails, custom exception or NotInstanceofException is thrown
If rule execution fails, ExecutingRuleException is thrown

Internal flow:

Value → InstanceofRuleGuardian → Guardian → InstanceofRule → Result → Exception

🔗 Related Packages

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

Maintainers

Package info

Statistics

Security