# Pluggable

The Pluggable component consists in a set of tools providing pluggable logic allowing instructions to be extended, specially by third-parties.

A class defining pluggable logic is known as pluggable.

# Types

The Pluggable component defines two plug types, both implementing PlugTypeInterface.

# EventPlugType

Events defined by EventPlugType with Pluggable Events to Event Plug.

# HookPlugType

Hooks defined by HookPlugType with Pluggable Hooks to Hook Plug.

# Pluggable Events

Pluggable events are used when is intended to broadcast that something took place. A class must implement PluggableEventsInterface to allow pluggable events.

TIP

⏩ Use PluggableEventsTrait to quickly implement PluggableEventsInterface

# How Pluggable Events works

In the code below, calls to event method allows to emit an event once set method logic was executed.

use Chevere\Interfaces\Pluggable\PlugAnchorsInterface;
use Chevere\Components\Pluggable\Plug\Event\Traits\PluggableEventsTrait;
use Chevere\Interfaces\Pluggable\Plug\Hook\PluggableHooksInterface;

final class DoesSomething implements PluggableEventsInterface
{
    use PluggableEventsTrait;

    private string $string = '';

    public static function getEventAnchors(): PlugAnchorsInterface
    {
        return (new PlugAnchors)
            ->withAnchor('beforeSet')
            ->withAnchor('onSet');
    }

    public function set(string $value): void
    {
        $this->event('beforeSet', new Event([]));
        $this->string = 'set=' . $value;
        $this->event('onSet', new Event([]));
    }
}

In the example above, App\DoesSomething implements pluggable events with two anchors which emit events when something happens:

The beforeSet event will be emitted before setting the value or the $string property.
The onSet event will be emitted after the value of $string is set.

# Defining event anchors

The getEventAnchors method is used to define event anchors available to implement in the pluggable class.

Pluggable events use the event method to emit the event which will listened by registered events (if-any).

$this->event('anchor-name', $event);

# Pluggable Hooks

Hooks are used when it is intended to allow modification on variables. A class must implement PluggableHooksInterface to allow pluggable hooks.

TIP

⏩ Use PluggableHooksTrait to quickly implement the PluggableHooksInterface

# How Pluggable Hooks works

In the code below, calls to hook method allows to extend the behavior of the base set method.

use Chevere\Interfaces\Pluggable\PlugAnchorsInterface;
use Chevere\Components\Pluggable\Plug\Hook\Traits\PluggableHooksTrait;
use Chevere\Interfaces\Pluggable\Plug\Hook\PluggableHooksInterface;

final class DoesSomething implements PluggableHooksInterface
{
    use PluggableHooksTrait;

    private string $string = '';

    public static function getHookAnchors(): PlugAnchorsInterface
    {
        return (new PlugAnchors)
            ->withAnchor('hook:before')
            ->withAnchor('hook:after');
    }

    public function set(string $value): void
    {
        // value*alter
        $this->hook('hook:before', $value);
        // set=value*alter
        $this->string = 'set=' . $value;
        // set=value*`alter*again
        $this->hook('hook:after', $value);
    }
}

In the example above, App\DoesSomething implements pluggable hooks with two anchors which alter $value argument, and therefore, the value of the $string property.

# Defining hook anchors

The getHookAnchors method is used to define the hook anchors available to implement in the pluggable class.

Pluggable hooks use the hook method to define a hookable code entry which will run hooks (if-any).

$this->hook('anchor-name', $argument);

The argument $argument is passed by reference and it can be of any type. It is intended to be susceptible to be modified by potentially unknown logic instructions.

Type-checking

✅ Chevere checks that the argument passed by reference doesn't alter its type after running any hook instruction.

# Plugin

Plugin is a class defining extra functionality, it is what a pluggable will plug-in to extend its base instructions and it should be designed to be short sets of instructions that must be executed without persistent memory and decoupled as possible from the application.

# Event Plug

An Event implements EventInterface and is a type of plug that fires when something took place.

Learn by Example

Check the Event example to learn directly playing with code.

# Hook Plug

A hook implements HookInterface and is a type of plug that alters a variable.

Learn by Example

Check the Hook example to learn directly playing with code.