Framework Documentation - Application Package
2. Container and configuration
joomla/di is a PSR-11 container with autowiring, aliases and tags. We use it to build every
service the application needs, so both the web and the console entry points can share the wiring.
The bootstrap
bootstrap.php:
<?php
declare(strict_types=1);
use App\Service\AuthenticationProvider;
use App\Service\ConfigProvider;
use App\Service\DatabaseProvider;
use App\Service\EventProvider;
use App\Service\TemplateProvider;
use App\Service\RouterProvider;
use App\Service\SessionProvider;
use App\Service\WebApplicationProvider;
use Joomla\DI\Container;
require __DIR__ . '/vendor/autoload.php';
$container = new Container();
$container->registerServiceProvider(new ConfigProvider(__DIR__));
$container->registerServiceProvider(new EventProvider());
$container->registerServiceProvider(new DatabaseProvider());
$container->registerServiceProvider(new SessionProvider());
$container->registerServiceProvider(new AuthenticationProvider());
$container->registerServiceProvider(new TemplateProvider(__DIR__ . '/templates'));
$container->registerServiceProvider(new RouterProvider());
$container->registerServiceProvider(new WebApplicationProvider());
return $container;Order matters only where a provider reads another service during registration. Ours all use
closures, which are evaluated lazily on first get(), so registration order is free.
Configuration provider
src/Service/ConfigProvider.php:
<?php
declare(strict_types=1);
namespace App\Service;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Registry\Registry;
final class ConfigProvider implements ServiceProviderInterface
{
public function __construct(private readonly string $rootPath) {}
public function register(Container $container): void
{
$container->share(
Registry::class,
function (): Registry {
$file = $this->rootPath . '/config/app.json';
// Registry::loadFile() returns an empty registry for an unreadable file
// instead of failing, so check the path first.
if (!is_readable($file)) {
throw new \RuntimeException(
sprintf('Configuration file "%s" is not readable.', $file)
);
}
$config = (new Registry())->loadFile($file, 'JSON');
// Make relative paths absolute so the application works from any cwd.
foreach (['database.database', 'log.path'] as $key) {
$value = (string) $config->get($key, '');
if ($value !== '' && !str_starts_with($value, '/') && !preg_match('#^[a-z]:#i', $value)) {
$config->set($key, $this->rootPath . '/' . $value);
}
}
$config->set('root_path', $this->rootPath);
return $config;
},
true
);
$container->alias('config', Registry::class);
}
}Two details worth copying into your own projects:
- Fail loudly on a missing configuration file.
Registry::loadFile()swallows read errors and
hands you an empty registry, which means every security-relevant setting silently falls back to
its default. The explicitis_readable()check turns that into a startup error. - Resolve relative paths once. Otherwise the application only works when the current working
directory happens to be the project root — which it is not under a web server.
Logger provider
Bundle the logger into the event provider or give it its own; here it lives with the events since
that is where it is mostly consumed. src/Service/EventProvider.php:
<?php
declare(strict_types=1);
namespace App\Service;
use App\EventListener\CsrfSubscriber;
use App\EventListener\ErrorSubscriber;
use App\EventListener\SecurityHeadersSubscriber;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\Dispatcher;
use Joomla\Event\DispatcherInterface;
use Joomla\Registry\Registry;
use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;
use Psr\Log\LoggerInterface;
final class EventProvider implements ServiceProviderInterface
{
public function register(Container $container): void
{
$container->share(
LoggerInterface::class,
static function (Container $container): LoggerInterface {
$config = $container->get(Registry::class);
$logger = new Logger('app');
$logger->pushHandler(
new StreamHandler(
$config->get('log.path'),
Level::fromName($config->get('log.level', 'warning'))
)
);
return $logger;
},
true
);
$container->share(
DispatcherInterface::class,
static function (Container $container): DispatcherInterface {
$dispatcher = new Dispatcher();
foreach ($container->getTagged('event.subscriber') as $subscriber) {
$dispatcher->addSubscriber($subscriber);
}
return $dispatcher;
},
true
);
// Subscribers are written in chapter 6 and 7.
$container->share(CsrfSubscriber::class, static fn (Container $c) => new CsrfSubscriber());
$container->share(SecurityHeadersSubscriber::class, static fn () => new SecurityHeadersSubscriber());
$container->share(
ErrorSubscriber::class,
static fn (Container $c) => new ErrorSubscriber(
$c->get(LoggerInterface::class),
(bool) $c->get(Registry::class)->get('debug', false)
)
);
$container->tag('event.subscriber', [
CsrfSubscriber::class,
SecurityHeadersSubscriber::class,
ErrorSubscriber::class,
]);
}
}Tags are not inherited by child containers.
Container::getTagged()only looks at the
container it is called on. If you ever callcreateChild(), resolve the dispatcher from the
parent or re-tag in the child — otherwise the subscriber list comes back empty with no error.
Application provider
src/Service/WebApplicationProvider.php:
<?php
declare(strict_types=1);
namespace App\Service;
use Joomla\Application\Controller\ContainerControllerResolver;
use Joomla\Application\Controller\ControllerResolverInterface;
use Joomla\Application\WebApplication;
use Joomla\Application\WebApplicationInterface;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\DispatcherInterface;
use Joomla\Input\Input;
use Joomla\Registry\Registry;
use Joomla\Router\RouterInterface;
use Joomla\Session\SessionInterface;
use Psr\Log\LoggerInterface;
final class WebApplicationProvider implements ServiceProviderInterface
{
public function register(Container $container): void
{
$container->share(
ControllerResolverInterface::class,
static fn (Container $c) => new ContainerControllerResolver($c),
true
);
$container->share(Input::class, static fn () => new Input(), true);
$container->share(
WebApplication::class,
static function (Container $container): WebApplication {
$app = new WebApplication(
$container->get(ControllerResolverInterface::class),
$container->get(RouterInterface::class),
$container->get(Input::class),
$container->get(Registry::class)
);
$app->setDispatcher($container->get(DispatcherInterface::class));
$app->setLogger($container->get(LoggerInterface::class));
$app->setSession($container->get(SessionInterface::class));
return $app;
},
true
);
$container->alias(WebApplicationInterface::class, WebApplication::class);
}
}The application is registered as shared so controllers, subscribers and repositories all see
the same instance — they have to, because they set headers and the body on it.
Container gotchas
Two behaviours of joomla/di are worth knowing before you build on it:
- An object with
__invoke()registered as a value is treated as a factory.
ContainerResourcechecksis_callable($value), so$container->share(Foo::class, $invokableInstance)
calls the object instead of returning it. Wrap it:$container->share(Foo::class, static fn () => $invokableInstance). extend()fails on protected resources.Container::extend()ends inset(), which throws
ProtectedKeyExceptionfor anything registered withprotect(). Register services you intend to
decorate without protection.
Verifying the wiring
// scratch.php
$container = require __DIR__ . '/bootstrap.php';
var_dump($container->get(Joomla\Registry\Registry::class)->get('database.driver'));
var_dump($container->get(Psr\Log\LoggerInterface::class)::class);
var_dump(count($container->getTagged('event.subscriber')));$ php scratch.php
string(6) "sqlite"
string(15) "Monolog\Logger"
int(3)Next: Routing and controllers.