README

Qube is a lightweight and simple dependency injection container.

Installation

You can install the package via composer:

composer require clementdecou/qube

Usage

Creating a container is a matter of creating a Container instance:

use Qube\Container;

$container = new Container();

Or use the helper function:

use Amorfx\Qube\qube;

$container = qube();

It will return a unique instance of the container even if you call it multiple times.

Defining Services

$container->set('my_service', new MyService());

Defining Services with a factory

If a service has multiple dependencies you can define a factory for your service.

use Amorfx\Qube\DependencyInjection\ContainerInterface;

$container->set('my_service', function (ContainerInterface $container) {
    return new MyService($container->get('service1'), $container->get('service2'));
});

Notice that the anonymous function has access to the current container instance, allowing references to other services or parameters. As objects are only created when you get them, the order of the definitions does not matter.

Defining Services not shareable

By default, each time you get a service, the same instance is returned. If you want a different instance to be returned for all calls, use the share parameter.

$container->set('my_service', new MyService(), false);

Now, each call to 'my_service' returns a new instance of the service.

Defining Services with a tag

You can tag a service with a specific tag. This is useful when you want to retrieve multiple services with the same tag.

$container->set('my_service', new MyService(), tags: ['tag1', 'tag2']);

Retrieve a service

Retrieve a previously registered service using its identifier.

$service = $container->get('my_service');

Retrieve multiple services with tags

It will return a generator with all services tagged. You can iterate over it or use the iterator_to_array function to get an array.

$services = $container->getByTag('tag1');

Defining Parameters

Defining a parameter allows to ease the configuration of your container from the outside and to store global values:

$container->setParameter('my_param', 'my_value');

Retrieve a parameter

Retrieve a previously registered parameter using its identifier.

$param = $container->getParameter('my_param'); // return my_value

Extending a Container

If you use the same libraries over and over, you might want to reuse some services from one project to the next one. Package your services into a provider by implementing Qube\DependencyInjection\ServiceProviderInterface:

use Amorfx\Qube\DependencyInjection\ServiceProviderInterface;
use Amorfx\Qube\DependencyInjection\Container;
class ServiceProvider implements ServiceProviderInterface
{
    public function register(Container $container): void
    {
        // register services and parameters or other providers
    }
}

Then register your provider into the container:

$container->registerProviders([new ServiceProvider()]);
// OR
$container->registerProvider(new ServiceProvider());

Using the builder / or configuration file

You can use the builder to create your container. It will allow you to use a configuration file to define your services and parameters.

use Amorfx\Qube\DependencyInjection\ContainerBuilder;
use Amorfx\Qube\quBuilder;

$builder = new ContainerBuilder(configFilePath: __DIR__ . '/config.php');
$container = $builder->get();

// OR use helper function
$container = quBuilder()
->fromConfig(__DIR__ . '/config.php')
->get();

// Or directly from an array
$container = (new ContainerBuilder(config: [...]))->get();

The configuration file must return an array with the following structure:

return [
    'parameters' => [
        //list of parameter identifier with their value
        'param1' => 'value1',
        // ...
    ],
    
    'services' => [ // list of you services
    
        'service1' => [ // the service identifier
            'object' => // an instance of your service or use factory
            'factory' => function (ContainerInterface $container) {
                // the closure to return your service instance
            },
            'tags' => [], // a list of tags
            'share' => false, // if the service is shareable, default is true
        ],
        // ...
    ],
    
    'providers' => [
        // the list of your providers class name
    ],
];

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

clementdecou / qube

Maintainers

Details