Add optional factory/extension interfaces and dependency inspection (#54

)

* add dependency enumeration feature.
* add optional interfaces for factories/extensions.
* add callable types: these were tested with Psalm and PHPStan, and worked as expected with both - this provides static analysis with at least two popular tools (probably PHPStorm as well) and to the rest of the world they are just documentation.

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 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
+{
+    /**
+     * 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/ServiceDependencyInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Interop\Container;
+
+/**
+ * A `ServiceProviderInterface` implementation may optionally implements this interface,
+ * which provides a means of reflecting the dependencies of the provided services.
+ */
+interface ServiceDependencyInterface
+{
+    /**
+     * @return array<string,string[]> map where entry ID => list of dependency IDs
+     */
+    public function getDependencies(): array;
+}

src/ServiceProviderInterface.php

@@ -2,6 +2,8 @@
 
 namespace Interop\Container;
 
+use Psr\Container\ContainerInterface;
+
 /**
  * A service provider provides entries to a container.
  */
@@ -13,20 +15,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 array<string,((callable(ContainerInterface):mixed)|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 +39,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 array<string,((callable(ContainerInterface,mixed):mixed)|ExtensionDefinitionInterface)[]>
      */
-    public function getExtensions();
+    public function getExtensions(): array;
 }