exploring a possible refactoring of the interface with reduced comple…

…xity and less runtime overhead (see container-interop#71 (comment) for more details)

src/NotFoundExceptionInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Interop\Container;
+
+/**
+ * No entry was found in the provider.
+ */
+interface NotFoundExceptionInterface extends ServiceProviderExceptionInterface
+{
+}

src/ServiceProviderExceptionInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Interop\Container;
+
+use Throwable;
+
+/**
+ * Base interface representing a generic exception in a service provider.
+ */
+interface ServiceProviderExceptionInterface extends Throwable
+{
+}

src/ServiceProviderInterface.php

@@ -5,41 +5,54 @@
 use Psr\Container\ContainerInterface;
 
 /**
- * A service provider provides entries to a container.
+ * A service provider provides services and extensions to a container.
  */
 interface ServiceProviderInterface
 {
     /**
-     * Returns a list of all container entries registered by this service provider.
-     *
-     * - the key is the entry name
-     * - the value is a callable that will return the entry, aka the **factory**
-     *
-     * A factory is an instance of {@see FactoryDefinitionInterface}, or a `callable` with the following signature:
-     * 
-     *     function(\Psr\Container\ContainerInterface $container)
-     *
-     * @return array<string,((callable(ContainerInterface):mixed)|FactoryDefinitionInterface)>
+     * Lists all of the service IDs supported by this provider.
+     * 
+     * @return string[] list of service IDs
+     */
+    public function getServiceIDs(): array;
+
+    /**
+     * Create the service with the given ID.
+     * 
+     * Supported service IDs can be obtained from `getServiceIDs()` - using an unsupported
+     * service ID will throw a `NotFoundExceptionInterface`.
+     * 
+     * @param string $id ID of the service to create
+     * @param ContainerInterface $container the container to resolve service dependencies from
+     * 
+     * @return mixed the created service
+     * 
+     * @throws NotFoundExceptionInterface if the service ID is not supported
+     * @throws ServiceProviderExceptionInterface if the service could not be created
      */
-    public function getFactories(): array;
+    public function createService(string $id, ContainerInterface $container): mixed;
 
     /**
-     * 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
-     *
-     * 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)
-     *
-     * About factories parameters:
-     *
-     * - 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 array<string,((callable(ContainerInterface,mixed):mixed)|ExtensionDefinitionInterface)[]>
+     * Lists all of the extension IDs supported by this provider.
+     * 
+     * @return string[] list of extension IDs
+     */
+    public function getExtensionIDs(): array;
+
+    /**
+     * Extend the `$previous` service with the given ID.
+     * 
+     * Supported extension IDs can be obtained from `getExtensionIDs()` - using an unsupported
+     * extension ID will throw a `NotFoundExceptionInterface`.
+     * 
+     * @param string $id ID of the service to extend
+     * @param ContainerInterface $container the container to resolve extension dependencies from
+     * @param mixed $previous the previous service (which will be extended)
+     * 
+     * @return mixed the extended service
+     * 
+     * @throws NotFoundExceptionInterface if the extension ID is not supported
+     * @throws ServiceProviderExceptionInterface if the extension could not be applied
      */
-    public function getExtensions(): array;
+    public function extendService(string $id, ContainerInterface $container, mixed $previous): mixed;
 }