Question

As noted throughout this documentation, Flarum uses Laravel's service container (or IoC container) for dependency injection. Service Providers allow low-level configuration and modification of the Flarum backend. The most common use case for service providers is to create, modify, or replace container bindings. That being said, service providers allow you full access to run whatever logic you need during application boot with access to the container.

Advanced Use Only!!!

Unlike with other extenders, the Service Provider layer is NOT use-case driven, and is NOT considered public API. It is subject to change at any time, without notice or deprecation. This should only be used if you know what you're doing, and the other extenders don't satisfy your use case.

Flarum Boot Process

To understand service providers, you must first understand the order in which Flarum boots. Most of this happens in Flarum\Foundation\InstalledSite

1. The container and application are initialized, and essential bindings (config, environment, logger) are registered
2. The register methods of all core service providers are run.
3. The extend methods of all extenders used by all enabled extensions are run.
4. The extend methods of all extenders used in the Flarum site's local extend.php are run.
5. The boot methods of all core service providers are run.

Custom Service Providers

A custom service provider should extend Flarum\Foundation\AbstractServiceProvider, and can have a boot and a register method. For example:

<?php

use Flarum\Foundation\AbstractServiceProvider;
use Illuminate\Contracts\Container\Container;

class CustomServiceProvider extends AbstractServiceProvider
{
    public function register()
    {
        // custom logic here, for example:
        $this->container->resolving(SomeClass::class, function ($container) {
            return new SomeClass($container->make('some.binding'));
        })
    }

    public function boot(Container $container)
    {
        // custom logic here
    }
}

The register method will run during step (3) above, and the boot method will run during step (5) above. In the register method, the container is available via $this->container. In the boot method, the container (or any other arguments), should be injected via typehinted method arguments.

Flarum does not currently support Laravel Octane, but some best practices, like using the $container argument inside bind, singleton, and resolving callbacks instead of $this->container should be used. See the Octane documentation for more information.

To actually register your custom service provider, you can use the ServiceProvider extender in extend.php:

<?php

use Flarum\Extend;

return [
    // Other extenders
    (new Extend\ServiceProvider())
        ->register(CustomServiceProvider::class),
    // Other extenders
];