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:

• aegisora/guardian
• aegisora/instanceof-rule

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

1. InstanceofRuleGuardian::check() is called
2. InstanceofRule::create($targetClassName) is created
3. Guardian executes the rule
4. If validation succeeds, execution continues normally
5. If validation fails, custom exception or NotInstanceofException is thrown
6. 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.