Supervision Component

• Introduction
• Features
• Concepts
• Examples
  • Registering Problem Solvers
  • Registering Multiple Solvers
  • Solving Problems
  • Solvers Resolution
  • Writing Custom Solvers
• Important Classes & Interfaces
  • Solver
  • SolverComposite
  • SolverInterface
  • SolverFactory
  • SolverFactoryInterface
  • Supervisor
  • SupervisorInterface

Introduction

Supervision is component that provides supervision mechanism for runtime containers and common problem solvers.

Features

Supervision features:

Concepts

This section contains terminology, useful concepts and definitions, that might be helpful to learn to fully understand this component purpose.

Supervison

Supervision is dependency relationship between supervisor and supervised code, in which supervisor must respond to its supervised code execution failures. When a failure is detected, the supervisor should stop execution of supervised code and react accordingly. Supervision systems are usually used in distributed systems, in which parent process supervises its children.

Supervisor

Supervisor is an object that supervises part of code or application architecture.

Solver

Solver is an abstraction of a measure that have to be taken to solve problem which occurred.

Examples

This section contains examples and patterns that can be used with described component.

Registering Problem Solvers

Registering problem solvers can be done via passing its instance or class name to supervisor constructor:

$supervisor = new Supervisor($factory, [], [
    CustomException::class => CustomSolver::class
]);

Or by passing adding it dynamically using setSolver method.

$supervisor->setSolver(CustomException::class, CustomSolver::class);

Registering Multiple Solvers

Multiple solvers for one problem can be also defined using array syntax:

$supervisor = new Supervisor($factory, [], [
    CustomException::class => [ FirstSolver::class, SecondSolver::class ]
]);

Solving Problems

Solving problems can be used by calling solve method.

try
{
    // some code
}
catch (Throwable $throwable)
{
    $supervisor->solve($throwable);
}

Solvers Resolution

{warning} Supervisor solve methods behaves the same way as declaring multiple catch blocks. This means that the first valid solver will be the only one executed, so pay attention to the order of your solvers.

$supervisor = new Supervisor($factory, [], [
    Error::class            => ASolver::class,
    Exception::class        => BSolver::class,
    CustomException::class  => CSolver::class
]);

// since CustomException is instance of Exception, the first and the only solver to be execute will be BSolver
$supervisor->solve(new CustomException());

{tip} It is a good idea to register Throwable::class solver as the last one which will behave in similar way that default does in switches.

Writing Custom Solvers

All of custom solvers need to extend Kraken\Supervision\Solver class and implement Kraken\Supervision\SolverInterface interface.

use Kraken\Supervision\Solver;
use Kraken\Supervision\SolverInterface;

class CmdDoNothing extends Solver implements SolverInterface
{
    protected function solver($ex, $params = [])
    {
        // this code will be executed and promisified by Supervisor
    }
}

Important Classes & Interfaces

This section contains list of most important classes and interfaces shipped with this component. It does not include all classes and interface.

Solver

class Solver implements SolverInterface

Solver represents the handler that is executed as a response for thrown error or exception which intention is to solve a problem which occurred.

SolverComposite

class SolverComposite implements SolverInterface

SolverComposite is a class that allows creating chain of solvers which are executed one after another. It is important to keep in mind, that if one of solvers in chain fails then the rest of them won't be executed, as the overall resolution of problem will be marked as failure.

SolverInterface

interface SolverInterface

SolverFactory

class SolverFactory extends Factory implements SolverFactoryInterface

SolverFactory is the factory that knows how to create all of solvers used in application.

SolverFactoryInterface

interface SolverFactoryInterface extends FactoryInterface

Supervisor

class Supervisor implements SupervisorInterface

Supervisor is an instance of an object that that supervises execution of your code and in case of failure, executes proper solvers.

SupervisorInterface

interface SupervisorInterface