README

divineniiquaye/php-invoker is a php library that allows invoking callables with named parameters in a generic and extensible way for PHP 7.1+, based on reference implementation PHP-DI Invoker created by Matthieu Napoli. This library provides clear extension points to let frameworks/projects implement any kind of dependency injection support they want, but not limited to dependency injection. Again, any PSR-11 compliant container can be provided.

📦 Installation & Basic Usage

This project requires PHP 7.1 or higher. The recommended way to install, is via Composer. Simply run:

$ composer require divineniiquaye/php-invoker

Let's say you working on a project and want to invoke some named parameters in callables with whatever the order of parameters, but should be matched by their names or instance. Then we'll need an over-engineered call_user_func().

In short, this library is meant to be a base building block for calling a function with named parameters and/or dependency injection.

Using DivineNii\Invoker\Invoker class method call:

$invoker = new DivineNii\Invoker\Invoker;

$invoker->call(function () {
    echo 'Hello world!';
});

// Simple parameter array
$invoker->call(function ($name) {
    echo 'Hello ' . $name;
}, ['John']);

// Named parameters
$invoker->call(function ($name) {
    echo 'Hello ' . $name;
}, [
    'name' => 'John'
]);

// Typehint parameters
$invoker->call(function (string $name) {
    echo 'Hello ' . $name;
}, [
    'name' => 'John'
]);

// Use the default value
$invoker->call(function ($name = 'world') {
    echo 'Hello ' . $name;
});

// Invoke any PHP callable
$invoker->call(['MyClass', 'myStaticMethod']);

// Using Class::method syntax
$invoker->call('MyClass::myStaticMethod');

// Using ":" pattern syntax
$invoker->call('MyClass:myMethod');

// Using "@" pattern syntax
$invoker->call('MyClass@myMethod');

Using DivineNii\Invoker\ArgumentResolver class in DivineNii\Invoker\Invoker class:

Extending the behavior of the DivineNii\Invoker\Invoker is easy and is done by adding a callable to ArgumentResolver class:

use ReflectionParameter;
use DivineNii\Invoker\Interfaces\ArgumentValueResolverInterface;

class MyParameterValueResolver implements ArgumentValueResolverInterface
{
    /**
     * {@inheritdoc}
     */
    public function resolve(ReflectionParameter $parameter, array $providedParameters)
    {
        //....
    }
}

$providedParameters contains the parameters provided by the user when calling $invoker->call($callable, $parameters)

An DivineNii\Invoker\Invoker can chain multiple parameter resolvers to mix behaviors, e.g. you can mix "named parameters" support with "dependency injection" support.

Here is an implementation example for dumb dependency injection that creates a new instance of the classes type-hinted:

use {ReflectionClass, ReflectionException};
use DivineNii\Invoker\Interfaces\ArgumentValueResolverInterface;

class MyParameterValueResolver implements ArgumentValueResolverInterface
{
    /**
     * {@inheritdoc}
     */
    public function resolve(ReflectionParameter $parameter, array $providedParameters)
    {
        $parameterClass = $parameter->getClass();

        if ($parameterClass instanceof ReflectionClass) {
            try {
                return $class->newInstance();
            } catch (ReflectionExcetion $e) {
                // ...
            }
        }
    }
}

To use it:

$invoker = new DivineNii\Invoker\Invoker([new MyParameterValueResolver()]);

$invoker->call(function (ArticleManager $articleManager) {
    $articleManager->publishArticle('Hello world', 'This is the article content.');
});

A new instance of ArticleManager will be created by our parameter resolver. The fun starts to happen when we want to add support for many things:

named parameters
dependency injection for type-hinted parameters
...

It allows to support even the weirdest use cases like:

$parameters = [];

// First parameter will receive "Welcome"
$parameters[] = 'Welcome';

// Parameter named "content" will receive "Hello world!"
$parameters['content'] = 'Hello world!';

// $published is not defined so it will use its default value
$invoker->call(function ($title, $content, $published = true) {
    // ...
}, $parameters);

Rather than have you re-implement support for dependency injection with different containers every time, this package ships with 2 optional resolvers:

This resolver will inject container entries by searching for the class name using the type-hint:
```
$invoker->call(function (Psr\Logger\LoggerInterface $logger) {
    // ...
});
```
In this example it will ->get('Psr\Logger\LoggerInterface') from the container and inject it, but if instance of interface exist in $providedParameters, it also get injected.
This resolver will inject container entries by searching for the name of the parameter:
```
$invoker->call(function ($twig) {
    // ...
});
```
In this example it will ->get('twig') from the container and inject it or from $providedParameters.

The DivineNii\Invoker\Invoker can be wired to your DI container to resolve the callables, but can resolve all callables including invokable class or object.

For example with an invokable class:

class MyHandler
{
    public function __invoke()
    {
        // ...
    }
}

// By default this work
$invoker->call('MyHandler');

// If we set up the container to use
$invoker = new Invoker\Invoker([], $container);
// Now 'MyHandler' parameters is resolved using the container if any!
$invoker->call('MyHandler');

The same works for a class method:

class WelcomeController
{
    public function home()
    {
        // ...
    }
}

// By default this doesn't work: home() is not a static method
$invoker->call(['WelcomeController', 'home']);

// If we set up the container to use
$invoker = new Invoker\Invoker([], $container);
// Now 'WelcomeController' is resolved using the container!
$invoker->call(['WelcomeController', 'home']);
// Alternatively we can use the Class::method syntax
$invoker->call('WelcomeController::home');

📓 Documentation

For in-depth documentation before using this library. Full documentation on advanced usage, configuration, and customization can be found at docs.biurad.com.

⏫ Upgrading

Information on how to upgrade to newer versions of this library can be found in the UPGRADE.

🏷️ Changelog

SemVer is followed closely. Minor and patch releases should not introduce breaking changes to the codebase; See CHANGELOG for more information on what has changed recently.

Any classes or methods marked @internal are not intended for use outside of this library and are subject to breaking changes at any time, so please avoid using them.

🛠️ Maintenance & Support

When a new major version is released (1.0, 2.0, etc), the previous one (0.19.x) will receive bug fixes for at least 3 months and security updates for 6 months after that new release comes out.

(This policy may change in the future and exceptions may be made on a case-by-case basis.)

Professional support, including notification of new releases and security updates, is available at Biurad Commits.

👷‍♀️ Contributing

To report a security vulnerability, please use the Biurad Security. We will coordinate the fix and eventually commit the solution in this project.

Contributions to this library are welcome, especially ones that:

Improve usability or flexibility without compromising our ability to adhere to PSR-12 coding stardand.
Optimize performance
Fix issues with adhering to PSR-11 support and backward compatability.

Please see CONTRIBUTING for additional details.

🧪 Testing

$ composer test

This will tests divineniiquaye/php-invoker will run against PHP 7.2 version or higher.

👥 Credits & Acknowledgements

🙌 Sponsors

Are you interested in sponsoring development of this project? Reach out and support us on Patreon or see https://biurad.com/sponsor for a list of ways to contribute.

📄 License

divineniiquaye/php-invoker is licensed under the BSD-3 license. See the LICENSE file for more details.

🏛️ Governance

This project is primarily maintained by Divine Niiquaye Ibok. Members of the Biurad Lap Leadership Team may occasionally assist with some of these duties.

🗺️ Who Uses It?

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us an email or message mentioning this library. We publish all received request's at https://patreons.biurad.com.

Check out the other cool things people are doing with divineniiquaye/php-invoker: https://packagist.org/packages/divineniiquaye/php-invoker/dependents

divineniiquaye / php-invoker

Maintainers

Details