Plugins Plugins

A next generation dependency injection system

Plugins can perform a variety of tasks and be nested together to form a composite plugin. Various types of plugins are available and custom plugins can also be created.

App
'dashboard' => new App(new FileInclude(__DIR__ . '/dashboard.php')),

The app plugin is used to provide a scoped instance of an Mvc5\App class and uses the current service provider as its parent.

Args
'request' => [
    Request\Config::class,
    'config' => new Args([
        'host' => new Call('request.getHost'),
        'method' => new Call('request.getMethod'),
        'path' => new Call('request.getPathInfo'),
        'scheme' => new Call('request.getScheme')
    ])
],

The args plugin is used to return an array of values that are resolved just in time, e.g. when the class is being instantiated.

Call
new Call('Home\Controller', ['response' => new Plugin('Response')])

The call plugin is used to invoke an object or method, and supports plugins and named arguments.

Callback
new Callback(function() {
    $messages = $this->plugin('messages');
})

A callback plugin binds the scope of the application to a closure which can then access the application’s public service methods.

Calls
'route\dispatch' => new Calls(new Plugin(Mvc5\Route\Dispatch::class), ['service' => new Link])

The calls plugin is similar to a hydrator and is used to resolve a plugin with a set of function calls and supports named arguments.

Child
'manager' => new Plugin(null),
'service\manager' => new Child(Service\Manager::class, 'manager'),

A child plugin is used to extend a parent plugin. The first parameter is the name of the class to create and the second is the name of the parent plugin. Custom child configurations can also be created to allow another plugin to be used without having to specify the name of its parent. Examples are the controller, factory and form plugins.

Config
'Home\Controller' => [Home\Controller::class, 'config' => new Config]

The config plugin is used to provide the main configuration array or object.

Controller
'controller' => new Hydrator(null, ['request' => new Plugin('request')]),
'Home\Controller' => new Controller(Home\Controller::class),

A controller plugin is used to provide the constructor arguments and call methods for a controller without having to specify the name of its parent controller plugin. This is a convenience plugin for when controllers have a similar method of instantiation.

Copy
new Copy(new Plug('response'))

The copy plugin can be used to resolve and clone an object.

End
new End(new Call('@session_start'), new Plugin(Session\Config::class));

The end plugin will resolve a list of plugins and return the result of the last plugin.

Expect
new Expect(new Call('web'), new Call('exception\response'), true, false);

The expect plugin is used to catch an exception when resolving a plugin. The second argument is the plugin to use when an exception is thrown. The third argument indicates whether the exception should be passed to the second plugin as a named argument. The fourth argument indicates whether to merge the exception with the arguments passed to the first plugin.

Factory
'factory' => new Service(null),
'Home\Controller' => new Factory(Home\Controller::class),

A factory plugin is used to create a class object without having to specify the name of its parent factory plugin.

FileInclude
new FileInclude('config/templates.php'),

A file include plugin is used to include and evaluate a specified file. The name of the file can also be resolved via another plugin.

Filter
'response' => new Filter(
    new Plugin(Response::class), [function($response) { return $response;  }], [], 'response'
)

A filter plugin is used to pass a value from one function to the next and returns the result of the last function called. If a function returns null, the iteration is stopped and null is returned. If a function returns false, the iteration is stopped and the previous value, or current object, is returned. The third parameter contains any additional arguments and the fourth parameter specifies the name of the argument for the value that is being filtered.

Form
'form' => new Service(null),
'my\form' => new Form(My\Form::class),

A form plugin is used create a class object without having to specify the name of its parent form plugin.

GlobalVar
new GlobalVar('_COOKIE')

A global var plugin is a value plugin that returns the value assigned to the PHP $GLOBALS array for the specified parameter name.

Hydrator
'messages' => new Hydrator(Mvc5\Session\Messages::class, ['info' => 'success'])

A hydrator plugin is used to create an object with a resolvable plugin name and a set of calls to invoke. Using null for the parameter name is a convenient way for it to be used as a parent plugin. When the array key of its calls configuration is a string, it is used as the name of the method to call on the newly created object and passes its array value as a single resolvable argument. However, if the string is prefixed with the $ symbol, the string is used as the name of the object property to set. If a method needs to be called more than once, then an array of methods can be used.

'config' => new Hydrator(
    Mvc5\Config::class, [['set', 'controller', 'Home\Controller'], ['set', 'name', 'home']]
)

Additionally, any resolvable plugin can also be called.

'route' => new Hydrator(Mvc5\Route\Config::class, [new Call(fn($a) => var_dump($a), [500])]),

When an array configuration is used, the current object is passed to the called methods as a named argument called item. This can be changed by adding a value to the beginning of the array with the name of the parameter to use.

'service' => new Hydrator(
    ArrayObject::class, [['$current', new TestObject, 'index' => 'foo', 'bar' => 'baz']]
)

class TestObject
{
    function __invoke($index, $current, $bar)
    {
        return $current[$index] = $bar; //i.e $current['foo'] = 'baz'
    }
}
Invokable
$response = $app->call(new Invokable(new Plugin('response')));

An invokable plugin is used to return an anonymous function. When invoked, it will resolve and return its configured value.

Invoke
new Invoke('response.setStatusCode', [500]),
new Invoke(new Args([new Plugin('response'), 'setStatusCode']), [500]),
new Invoke(function() { var_dump(func_get_args()); }),

An invoke plugin is used to return an anonymous function. When invoked, it will resolve and call its configured value with the optional array of parameters passed to the anonymous function, merged with the plugin’s args. The return value is also resolved.

$app->call(new Invoke(new Plugin('Home\Controller')), ['request' => new Plugin('Request')])

'request\service' => [Mvc5\Request\Service::class, new Link]

A link plugin is used to return the current application or service provider.

Maybe
new Maybe($value = null, $default = null)

The maybe plugin returns a value that is not null. The resolved value will be returned if it is not null, in which case the default value will be returned if it is also not null, otherwise an instance of Nothing is returned. The value can be shared and then retrieved using the nullable plugin; which returns null when the value is Nothing.

(new Maybe)(); //Nothing
(new Maybe)('foo'); //foo
(new Maybe)(new Nothing); //Nothing
(new Maybe(null, new Value('bar')))(); //new Value('bar')
(new App)(new Maybe); //Nothing
(new App)(new Maybe(new Value('foo'))); //foo
(new App)(new Maybe(null, new Value('bar'))); //bar
Nullable
new Nullable($value = null, $default = null)

The nullable plugin returns a resolved value. When the value is Nothing, the default value is returned.

(new Nullable)(); //null
(new Nullable)('foo'); //foo
(new Nullable)(new Nothing); //null
(new Nullable(new Nothing, new Value('bar')))(new Nothing); //new Value('bar')
(new App)(new Nullable); //null
(new App)(new Nullable(new Value('foo')); //foo
(new App)(new Nullable(new Nothing, new Value('bar'))); //bar
NullValue
new NullValue

A null value plugin is used to return a null value. It can be used to prevent a service provider from being invoked and from creating an instance of its service same.

Param
new Param('templates.home')

A param is used to retrieve a configuration value and uses a dot notation for arrays and objects with ArrayAccess.

Plug
new Plug('controller\exception')

A plug is used to return the value of another plugin configuration.

Plugin
'config' => new Plugin(Mvc5\Config::class, [['a' => '1']], [['set', 'b', '2'], ['set', 'c', '3']])

A plugin is used to instantiate a class object. It requires the name of a resolvable plugin and optionally, its constructor arguments and a set of calls to invoke. See the hydrator plugin for details on how to specify the calls to invoke.

Plugins
new Plugins(__DIR__.'/services.php')

A plugins config is used to instantiate an application class. The first parameter is an array of service plugins, the second parameter defaults to using the current application as the provider for any missing services. The third parameter sets the application as the scope for any anonymous functions within service array plugin configuration.

Provide
new Provide($config, array $args = [])

The provide plugin is used to retrieve a value from its parent container.

Register
'user' => new Register('user', 'session', new Plugin(Mvc5\Config::class))

The register plugin will create an object if it is not already registered with a specified (configuration) object. The first parameter is the registered name, the second parameter is the name of the service configuration that should contain the registered object. The third parameter is the plugin configuration for the object to create and register if it does not already exist.

Response
'web' => new Response('web')

A response plugin is used to dispatch a response. It configures the response dispatch plugin with the name of the event to use and an optional request and response object. Each event function can return a request or response object for the the next function to use.

Scope
new Scope(array $plugins, string $name)

The scope plugin is used to set the scope of an application to the class that is being created. The first parameter is an array service plugins for the application, and the second parameter is the name of the class to create, e.g. ServerRequest. Any plugins using a closure will then have the same scope as the class being created and can access its protected properties.

Scoped
new Scoped($this)

The scoped plugin is used to provide a closure with the scope of the application. The first parameter of the plugin is a function that is called when the plugin is being resolved. The function returns a closure and its scope is set to the scope of the application.

ScopedCall
new ScopedCall($this)

The scoped call plugin extends the call plugin and uses the scoped plugin to set the scope of the closure for it to be called with.

Service
'router' => new Service(Mvc5\Route\Router:class, [new Param('routes')])

A service plugin is similar to a plugin and is used to add a call to a service method to set the current service object.

Session
'user' => new Session('user', new Plugin(Mvc5\Config::class))

The session plugin is a register plugin that retrieves a session variable. The first parameter is the name of the session variable, the optional second parameter is the plugin configuration for the object to create if it does not already exist in the session. If a value already exists in the session, it will be returned and a new object will not be created.

Shared
new Shared('response')

A shared plugin is used to create a shared value. When used as a configuration value, it should specify another configuration in order to prevent a recursion error. Alternatively, a configuration can be passed as a second argument to its constructor.

'response' => new Shared('response', new Plugin(Http\Response::class))
Value
new Value('A demo web page')

A value plugin is used to return a string value from the services container instead of the main configuration. Otherwise the container will assume that the string is the name of a class to instantiate.

ViewModel
new Model('error/404', ['message' => 'A 404 error occurred'])

A view model plugin is used to create a view model. Its first parameter is the template name and the second parameter contains its values.