Add optional factory/extension interfaces and dependency inspection

composer.json

@@ -10,6 +10,7 @@
         }
     },
     "require": {
+        "php": ">= 8.0.0",
         "psr/container": "^1.0 || ^2.0"
     }
 }

src/ExtensionDefinitionInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Interop\Container;
+
+use Psr\Container\ContainerInterface;
+
+/**
+ * An extension optionally implements this interface to reflect it's dependencies.
+ */
+interface ExtensionDefinitionInterface extends ServiceDefinitionInterface
+{
+    /**
+     * Extends a given service, using the given container to resolve dependencies.
+     * 
+     * @param ContainerInterface $container The container that should be used to resolve dependencies
+     * @param mixed              $previous  The previous service
+     *
+     * @return mixed The extended service.
+     */
+    public function __invoke(ContainerInterface $container, mixed $previous): mixed;
+}

src/FactoryDefinitionInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Interop\Container;
+
+use Psr\Container\ContainerInterface;
+
+/**
+ * A factory optionally implements this interface to reflect it's dependencies.
+ */
+interface FactoryDefinitionInterface extends ServiceDefinitionInterface
+{
+    /**
+     * Creates the entry, using the given container to resolve dependencies.
+     * 
+     * @param ContainerInterface $container The container that should be used to resolve dependencies
+     *
+     * @return mixed The created entry
+     */
+    public function __invoke(ContainerInterface $container): mixed;
+}

src/ServiceDefinitionInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Interop\Container;
+
+/**
+ * Represents a service definition.
+ */
+interface ServiceDefinitionInterface
+{
+    /**
+     * Retrieves the keys of known dependencies of this service.
+     *
+     * @return string[] A list of service keys.
+     */
+    public function getDependencies(): array;
+}

src/ServiceProviderInterface.php

@@ -13,20 +13,22 @@ interface ServiceProviderInterface
      * - the key is the entry name
      * - the value is a callable that will return the entry, aka the **factory**
      *
-     * Factories have the following signature:
-     *        function(\Psr\Container\ContainerInterface $container)
+     * A factory is an instance of {@see FactoryDefinitionInterface}, or a `callable` with the following signature:
+     * 
+     *     function(\Psr\Container\ContainerInterface $container)
      *
-     * @return callable[]
+     * @return (callable|FactoryDefinitionInterface)[]
      */
-    public function getFactories();
+    public function getFactories(): array;
 
     /**
      * Returns a list of all container entries extended by this service provider.
      *
      * - the key is the entry name
      * - the value is a callable that will return the modified entry
      *
-     * Callables have the following signature:
+     * An extension is an instance of {@see ExtensionDefinitionInterface}, or a `callable` with the following signature:
+     * 
      *        function(Psr\Container\ContainerInterface $container, $previous)
      *     or function(Psr\Container\ContainerInterface $container, $previous = null)
      *
@@ -35,7 +37,7 @@ public function getFactories();
      * - the container (instance of `Psr\Container\ContainerInterface`)
      * - the entry to be extended. If the entry to be extended does not exist and the parameter is nullable, `null` will be passed.
      *
-     * @return callable[]
+     * @return (callable|ExtensionDefinitionInterface)[]
      */
-    public function getExtensions();
+    public function getExtensions(): array;
 }