README

Throwable instruction

A PHP library for creating Exception Instructions

Description

Throwable Instruction makes it possible to define additional actions when an Exception is thrown in a specific place.

Translation

RU

Simple example

Call а instruction for the specified Exception type

try {
    $instruction = new ThrowableInstruction();
    $operation = new EchoOperation('Some output.');
    /*
     * Throwing an exception with an instruction
     */
    throw new LogicException('Some message.', 0, $instruction->add($operation));
} catch (LogicException $e) {
    echo $e->getMessage();
    /*
     * Call instructions for a specified exception
     */
    Operator::followInstruction($e);
} 

Calling an instruction for any type of Exception

try {
    $instruction = new ThrowableInstruction();
    $operation = new EchoOperation('Some output.');
    /*
     * Throwing an exception with an instruction
     */
    throw new LogicException('Some message.', 0, $instruction->add($operation));
} catch (LogicException $e) {
    echo $e->getMessage();
} finally {
    /*
     * Call instructions for all exceptions
     */
    if (isset($e) && is_subclass_of($e, Exception::class)) {
        Operator::followInstruction($e);
    }
}

Usage

1. Create an operation class

class ImportantMessageOperation implements OperationInterface
{
    protected string $message;
    protected int $code;

    public function __construct(string $message, int $code)
    {
        $this->message = $message;
        $this->code = $code;
    }

    public function execute(): void
    {
        echo "Important: {$this->message}. Code: {$this->code}";
    }
}

1. Call the Operator::followInstruction() method

public function whereExceptionsAreCaught(): void
{
    $object = new \stdClass();
    try {
        /*
         * Some code...
         */
        $this->item->doSomethingElse($object, $this->validator, $this->instruction);
    } catch (Exception $e) {
        $this->logger->log($e->getMessage(), $e->getCode());
    } finally {
        /*
         * Call instructions for all exceptions
         */
        if (isset($e) && is_subclass_of($e, Exception::class)) {
            Operator::followInstruction($e);
        }
    }
}

1. Provide instructions for Exception

• No instructions

public function doSomething(object $entity): void
{
    if (!$this->validator->validate($entity)) {
        /*
         *  InvalidArgumentException without instructions
         */
        throw new InvalidArgumentException('Entity is not valid object');
    }
}

• With Notice instructions

public function doSomethingElse(object $item): void
{
    if (!$this->validator->validate($item)) {
        /*
         * InvalidArgumentException with Notice instructions
         */
        throw new InvalidArgumentException(
            'Item is not valid object',
            0,
            $this->instruction->operation(NoticeMessageOperation::class, ['Invalid values passed'])
        );
    }
}

• With Important and CriticalEmail instructions

public function doSomethingImportant(object $importantItem): void
{
    if (!$this->validator->validate($importantItem)) {
        /*
         * InvalidArgumentException with Important instructions
         */
        throw new InvalidArgumentException(
            'Important Item is not valid object',
            0,
            $this->instruction
                ->operation(ImportantMessageOperation::class, ['Important values are not valid', 500])
                ->operation(SendCriticalEmailOperation::class, ['Any message text'])
        );
    }
}

Conclusion

Try/catch in different places in the code or the lack of a logical hierarchy of Exceptions can make them difficult to work with. Throwable Instruction will not fix architectural problems, but it may improve understanding of the actions caused by Exceptions and add the ability to reuse these actions.