Service Container

Sometimes you require a way to modularize your application and provide a way to make these modules interchangeable to allow different implementations of a given module to be used depending on specific factors, for example, to support new features or avoid known vulnerabilities.

That pattern is part of the SOLID principle and, while we are not going to explain it in this reference manual, it is one of the design considerations in Aurora to provide an extendable codebase, in fact, the Aurora framework is composed of a few services that cover an specific need, for example, routing.

Routing in Aurora is handled through the Router class that implements RouterInterface. That interface defines a method called dispatch that does the actual route handling. As an interface, it has no code, and only defines which the type of data coming in and out of the functions, so that you can create a better router class and while it follows the interface you may be able to swap it out without having to write glue-code. In fact, that is the purpose of interfaces: by coding against the interface you create modular code, and that's great!

So, in Aurora you have services, and the easiest way to access their instances at runtime would be through singletons or global variables; but that is not the most clean way to do it. For one, you pollute the global namespace with objects that may keep an inconsistent state if you modify them by accident, also it difficults testing and the singleton pattern is frowned uppon by some developers. Now, how will you manage your services then? Enter the service container.

A Service container, also called Dependency container is just a class that instantiates services, resolving its dependencies and making sure that they are not overwritten or modified, to keep a consistent state.

In fact, the Service container is also a service and implements the PSR-11 ContainerInterface.

To use it, you only need to get a hold of the Container service:

$container = container();

The container() function just return the current instance of the Container service, for example, to register a new service.

Registering services

Is as simple as:

$container = container();
$container->register(App\Services\MyService::class);

If if was meant to be a shared service (that is, only one instance is to be created and used through all you application) you may use the shared() method:

$container = container();
$container->shared(App\Services\MyService::class);

Also you may use a factory by passing a Closure as a second argument, that is very useful if you require to assemble the service with other objects:

$container = container();
$container->shared(App\Services\MyService::class, function() use ($container) {
    $settings = $container->resolve(Aurora\Settings\SettingsInterface::class);
    $url = $settings->get('myservice.url');
    $secret = $settings->get('myservice.secret');
    $adapter = new App\Services\MyServiceAdapter($url, $secret);
    $service = new App\Services\MyService($adapter);
    return $service;
});

Finally you may also pass an existing instance to the container:

$container = container();
$service = new App\Services\MyService();
$container->shared(App\Services\MyService::class, $service);

Initialization methods and constructor arguments are supported too:

$container = container();
$container->register(App\Services\MyService::class)->argument(42);

Or for example:

$container = container();
$container->register(App\Services\MyService::class)->method('setBaseNumber', [42]);

Registering commands

A Service Provider is also a good place to register the commands related to that service, take for example the ConsoleProvider:

use Aurora\Console\Console;
use Aurora\Console\Commands\CreateCommand;

class ConsoleProvider extends Provider {

    /**
     * Services provided
     * @var array
     */
    protected $provides = [
        Console::class
    ];

    /**
     * Bootstrap service provider
     * @return void
     */
    function bootstrap(): void {
        $app = app();
        if ( $app->isConsole() ) {
            $console = resolve(Console::class);
            $console->command(CreateCommand::class);
        }
    }

    /**
     * Register services
     * @param  ContainerInterface $container The container interface
     */
    public function register(ContainerInterface $container): void {
        $container->shared(Console::class);
    }
}

As you can see, the correct way to register your commands is to add the logic inside the bootstrap() method, checking if the application is being run from the CLI and getting the Console service instance with the resolve() function. Once you got it, just call its command() method and pass the full class name of your command. The reflection API will do the rest and discover the signature automatically.

Resolving services

Later you may access the MyService instance by calling:

$myService = resolve(App\Services\MyService::class);

As you can see the resolve() function allows you to get a service instance and does it by using the get() method of the ContainerInterface; the service container will resolve any service previously registered or any accesible type (for example by passing it's full class name).

Now, getting the container and resolving things out of it in this way is also considered an anti-pattern called service locator and while it is perfectly valid using it if you want, some developers may give you the stinky eye for doing so. A better way is by using dependency injection.

Dependency injection

Dependency injection or DI is a novel way of passing the responsability of allocating dependencies to the class using them and not the service container so that you do not depend on the specific implementation of your container, for a better, decoupled logic.

The easiest way of injecting a dependency is by type hinting your constructors, for example, say you will have a service that requires reading the settings to do some basic setup. You may be tempted to do the following:

namespace App\Services;

use Aurora\Settings\SettingsInterface;

class MyService {
    public function __construct() {
        $settings = resolve(SettingsInterface::class);
        $url = $settings->get('myservice.url');
    }
}

But that's wrong. You're using the container as a service locator. And now you will burn for all the eternity.

Seriously, it isn't the best way of doing it, let's try now with some DI magic:

declare(strict_types = 1);

namespace App\Services;

use Aurora\Settings\SettingsInterface;

class MyService {

    public function __construct(SettingsInterface $settings) {
        $url = $settings->get('myservice.url');
    }
}

Neat! So the next time you resolve the MyService instance out of the container it will also resolve the SettingsInterface instance and pass it to the constructor. Type-hinting enables auto-wiring and simplifies your logic by a lot while also reducing dependency on the service container implementation.

You may use DI on any class through the constructor (given it does not extend a class with a defined constructor).

That's great and all, but there must be a cleaner way of registering the services only if they are required. Well there it is, meet the Service Providers.

Service Providers

Say you have a very, very complex application with hundreds of services. Registering them all at startup will bog down your server on each request, and maybe some of the users are just going to use a dozen or so of services. What if you could load the services, say on demand?

The service providers allow you to separate your app logic in blocks and register each block only when is to be used. But how?

Let's start with a practical example, the router.

The Aurora router is a service, and as such it must be registered at some point to be available for use. But if you are using some commands to migrate your database on the CLI, you don't need a router. So there is a RouterProvider that sits on front of the routing functionality and has the task of registering the router class when the container asks for it. Now let's create a service provider for our service:

declare(strict_types = 1);

namespace App\Services;

use Psr\Container\ContainerInterface;

use Aurora\Container\Provider;
use App\Services\MyService;

class MyServicesProvider extends Provider {

    /**
     * Services provided
     * @var array
     */
    protected $provides = [
        MyService::class
    ];

    /**
     * Register services
     * @param  ContainerInterface $container The container interface
     */
    public function register(ContainerInterface $container): void {
        # Register MyService
        $container->shared(MyService::class, function() use ($container) {
            $settings = $container->resolve(Aurora\Settings\SettingsInterface::class);
            $url = $settings->get('myservice.url');
            $secret = $settings->get('myservice.secret');
            $adapter = new App\Services\MyServiceAdapter($url, $secret);
            $service = new App\Services\MyService($adapter);
            return $service;
        });
    }
}

There's some boilerplate code as you can see, but the most important parts are the $provides array which enumerates all the services provided by your uhm, provider; and the register method, that is called by the container when your services are to be resolved. Notice that we used the complex example where you create an adapter, but you may use any of the service-registration alternatives described before.

Now, you have created a service provider, but how do you tell the application that it exists?

Easy, remember the settings directory from the previous topic? Well, there is a special file named app.php that enumerates all the service providers available to your application:

return [
    'name' => env('APP_NAME'),
    'version' => env('APP_VERSION'),
    'url' => env('APP_URL'),
    'path' => env('APP_PATH'),
    'environment' => env('APP_ENVIRONMENT'),
    'providers' => [
        Aurora\Console\ConsoleProvider::class,
        Aurora\Database\DatabaseProvider::class,
        Aurora\Middleware\MiddlewareProvider::class,
        Aurora\Router\RouterProvider::class,
        Aurora\Events\EventsProvider::class,
        Aurora\Http\HttpProvider::class,
        Aurora\Log\LogProvider::class,
        Aurora\Queue\QueueProvider::class,
        Aurora\Web\WebProvider::class
    ]
];

Just add your provider there and the next time you resolve some class from these provider it will be loaded dinamically by the PSR-4 autoloader:

'providers' => [
    Aurora\Console\ConsoleProvider::class,
    Aurora\Database\DatabaseProvider::class,
    Aurora\Middleware\MiddlewareProvider::class,
    Aurora\Router\RouterProvider::class,
    Aurora\Events\EventsProvider::class,
    Aurora\Http\HttpProvider::class,
    Aurora\Log\LogProvider::class,
    Aurora\Queue\QueueProvider::class,
    Aurora\Web\WebProvider::class,
    App\Services\MyServicesProvider::class
]

Next up, the console.