eatae/throwable-instruction

Exception instructions

1.0.0 2023-12-20 18:35 UTC

This package is auto-updated.

Last update: 2024-05-30 16:16:18 UTC


README


Throwable instruction

A PHP library for creating Exception Instructions


Source Code Download Package PHP Programming Language GitHub License



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.