Building a PSR-11 Compatible Dependency Injection Container with PHP 8.4 Lazy Objects

Exploring Dependency Injection with Lazy Objects in PHP 8.4

In the realm of modern PHP, the release of version 8.4 introduced a groundbreaking feature: Lazy Objects. These objects enable a new way to defer initialization until absolutely necessary, boosting performance and reducing resource usage. This functionality is deeply integrated into the language through enhancements to the ReflectionClass API, as outlined in the Lazy Initialization for Lazy Objects RFC.

Example from the RFC
To illustrate the potential of Lazy Objects, consider the following example directly the RFC:

class MyClass
{
    public function __construct(private int $foo)
    {
        // Heavy initialization logic here.
    }

    // ...
}

$initializer = static function (MyClass $ghost): void {
    $ghost->__construct(123);
};

$reflector = new ReflectionClass(MyClass::class);
$object = $reflector->newLazyGhost($initializer);

// At this point, $object is a lazy ghost object.

This mechanism allows developers to finely control the initialization process, ensuring that resources are only loaded when accessed.

Inspired by this RFC, I set out to build a PSR-11 compatible Dependency Injection Container, leveraging the Lazy Objects API for optimal performance.

The Foundation of the ContainerLazyObject

The core of our container lies in the ContainerLazyObject class. With it, you can register dependencies and initialize them lazily, meaning they are only instantiated when actually needed. Here is the main method that performs this task:

public function set(string $id, object|string $concrete): void
{
    $reflector = new ReflectionClass($id);
    $initializer = $concrete;

    if (is_string($concrete)) {
        $initializer = function(object $instance) use ($concrete): void {
            $this->instances[$instance::class] = $concrete($this);
        };
    }

    if (is_object($concrete) && !$concrete instanceof Closure) {
        $initializer = function(object $instance) use ($concrete): void {
            $this->instances[$instance::class] = $concrete;
        };
    }

    $this->instances[$id] = $reflector->newLazyProxy($initializer);
}

Registering Services in the Container

Our container supports various ways of registering services, offering flexibility to developers. Here are some examples:

$container = new ContainerLazyObject();
$containerer->set(DatabaseService::class, fn() => new DatabaseService(new LoggerService()));
$container->set(LoggerService::class, fn() => new LoggerService());

// Alternative approach with class names
$container->set(DatabaseService::class, DatabaseService::class);
$containerr->set(LoggerService::class, LoggerService::class);

// Using already instantiated objects
$container->set(DatabaseService::class, new DatabaseService(new LoggerService()));
$container->set(LoggerService::class, new LoggerService());

This flexibility makes the ContainerLazyObject adaptable to various scenarios, whether dynamically building dependencies or reusing pre-configured objects.

Retrieving Services from the Container
Once services are registered in the container, you can retrieve them whenever needed. The container ensures that services are lazily instantiated, so they won’t be created until actually requested. Here is an example of how to retrieve the registered services:

// Retrieving the services from the container
$loggerService = $container->get(LoggerService::class);
$databaseService = $container->get(DatabaseService::class);

The Core of ContainerLazyObject The heart of our container lies in the ContainerLazyObject class. With it, you can register dependencies and initialize them lazily, meaning they are only created when they are actually used. Here is the main method that performs this task:

public function set(string $id, object|string $concrete): void
{
    $reflector = new ReflectionClass($id);
    $initializer = $concrete;

    if (is_string($concrete)) {
        $initializer = function(object $instance) use ($concrete): void {
            $this->instances[$instance::class] = $concrete($this);
        };
    }

    if (is_object($concrete) && !$concrete instanceof Closure) {
        $initializer = function(object $instance) use ($concrete): void {
            $this->instances[$instance::class] = $concrete;
        };
    }

    $this->instances[$id] = $reflector->newLazyProxy($initializer);
}

PSR-11 Compatibility

An additional advantage of the ContainerLazyObject is its compatibility with PSR-11, the PHP standard for dependency injection containers. This ensures interoperability with libraries and frameworks following the specification, making it a lightweight and universal solution.

Performance Comparison with Other Containers

To measure the performance of our container, I used PhpBench in a controlled environment, comparing it to popular alternatives: Pimple, Illuminate, and PHP-DI. The results were encouraging:

ContainerLazyObject          Mo0.100μs (±33.33%)
benchPimple                  Mo0.297μs (±18.84%)
benchIlluminate              Mo0.503μs (±9.07%)
benchPhpDI                   Mo0.161μs (±41.57%)

Our container demonstrated excellent performance, being significantly faster than more robust alternatives like Illuminate Container and PHP-DI in simple dependency resolution scenarios.

The Complete Class

class ContainerLazyObject implements ContainerInterface
{

    /**
     * @var array
     */
    private array $instances;

    /**
     * @var array
     */
    protected static array $reflectionCache = [];


    /**
     * @param  string  $class
     *
     * @return ReflectionClass
     * @throws ReflectionException
     */
    protected function getReflectionClass(string $class): ReflectionClass
    {
        if(!isset(self::$reflectionCache[$class])) {
            self::$reflectionCache[$class] = new ReflectionClass($class);
        }

        return self::$reflectionCache[$class];
    }

    /**
     * @param  string         $class
     * @param  object|string  $concrete
     *
     * @return void
     * @throws ReflectionException
     */
    public function set(string $class, object|string $concrete): void
    {
        $initializer = $concrete;
        if(is_string($concrete)) {
            $initializer = function(object $instance) use ($concrete): void {
                $this->instances[$instance::class] = $concrete($this);
            };
        }

        if(is_object($concrete) && !$concrete instanceof Closure) {
            $initializer = function(object $instance) use ($concrete): void {
                $this->instances[$instance::class] = $concrete;
            };
        }

        $this->instances[$class] = $this->getReflectionClass($class)->newLazyProxy($initializer);
    }

    /**
     * @param  string  $id
     *
     * @return object
     */
    public function get(string $id): object
    {
        if(!isset($this->instances[$id])) {
            throw new \InvalidArgumentException("Reference '{$id}' not found in container.");
        }
        return $this->instances[$id];
    }

    /**
     * @param  string  $id
     *
     * @return bool
     */
    public function has(string $id): bool
    {
        return isset($this->instances[$id]);
    }

    /**
     * @return void
     */
    public function clear(): void
    {
        $this->instances = [];
    }

    /**
     * @param  string  $id
     *
     * @return void
     */
    public function remove(string $id): void
    {
        if($this->has($id)) {
            unset($this->instances[$id]);
        }
    }
}

Conclusion

PHP 8.4 and its Lazy Objects have opened new possibilities to simplify and optimize dependency injection. Our ContainerLazyObject, in addition to being lightweight, efficient, and flexible, is PSR-11 compliant, ensuring interoperability with other libraries and frameworks.

Try this approach and see how it can simplify dependency management in your next project!