Refined ServiceManager factory, delegator and configuration types, to allow for easier introspection of mis-configuration at type level

psalm.xml.dist

@@ -5,17 +5,34 @@
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
     errorBaseline="psalm-baseline.xml"
+    findUnusedPsalmSuppress="true"
 >
     <projectFiles>
         <directory name="bin"/>
         <directory name="src"/>
         <directory name="test"/>
         <ignoreFiles>
             <directory name="vendor"/>
-            <directory name="test/TestAsset/laminas-code"/>
+            <directory name="test/TestAsset"/>
+            <directory name="test/**/TestAsset"/>
         </ignoreFiles>
     </projectFiles>
 
+    <issueHandlers>
+        <DeprecatedClass>
+            <errorLevel type="suppress">
+                <referencedClass name="Laminas\ServiceManager\DelegatorFactoryInterface"/>
+                <referencedClass name="Laminas\ServiceManager\InitializerInterface"/>
+                <referencedClass name="Laminas\ServiceManager\FactoryInterface"/>
+            </errorLevel>
+        </DeprecatedClass>
+        <InvalidThrow>
+            <errorLevel type="suppress">
+                <referencedClass name="Interop\Container\Exception\ContainerException"/>
+            </errorLevel>
+        </InvalidThrow>
+    </issueHandlers>
+
     <plugins>
         <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
     </plugins>

src/AbstractPluginManager.php

@@ -5,6 +5,7 @@
 namespace Laminas\ServiceManager;
 
 use Interop\Container\ContainerInterface;
+use Laminas\ServiceManager\Exception\ContainerModificationsNotAllowedException;
 use Laminas\ServiceManager\Exception\InvalidServiceException;
 use Psr\Container\ContainerInterface as PsrContainerInterface;
 
@@ -31,6 +32,9 @@
  *
  * The implementation extends `ServiceManager`, thus providing the same set
  * of capabilities as found in that implementation.
+ *
+ * @psalm-import-type ServiceManagerConfiguration from ServiceManager
+ * @psalm-suppress PropertyNotSetInConstructor
  */
 abstract class AbstractPluginManager extends ServiceManager implements PluginManagerInterface
 {
@@ -45,6 +49,7 @@ abstract class AbstractPluginManager extends ServiceManager implements PluginMan
      * An object type that the created instance must be instanced of
      *
      * @var null|string
+     * @psalm-var null|class-string
      */
     protected $instanceOf;
 
@@ -55,6 +60,7 @@ abstract class AbstractPluginManager extends ServiceManager implements PluginMan
      *
      * @param null|ConfigInterface|ContainerInterface|PsrContainerInterface $configInstanceOrParentLocator
      * @param array $config
+     * @psalm-param ServiceManagerConfiguration $config
      */
     public function __construct($configInstanceOrParentLocator = null, array $config = [])
     {
@@ -110,16 +116,18 @@ public function __construct($configInstanceOrParentLocator = null, array $config
     /**
      * Override configure() to validate service instances.
      *
-     * If an instance passed in the `services` configuration is invalid for the
-     * plugin manager, this method will raise an InvalidServiceException.
-     *
-     * {@inheritDoc}
-     *
-     * @throws InvalidServiceException
+     * @param  array $config
+     * @psalm-param ServiceManagerConfiguration $config
+     * @return self
+     * @throws InvalidServiceException If an instance passed in the `services` configuration is invalid for the
+     *                                 plugin manager.
+     * @throws ContainerModificationsNotAllowedException If the allow override flag has been toggled off, and a
+     *                                                   service instanceexists for a given service.
      */
     public function configure(array $config)
     {
         if (isset($config['services'])) {
+            /** @psalm-suppress MixedAssignment */
             foreach ($config['services'] as $service) {
                 $this->validate($service);
             }
@@ -142,10 +150,8 @@ public function setService($name, $service)
     }
 
     /**
-     * {@inheritDoc}
-     *
      * @param string $name Service name of plugin to retrieve.
-     * @param null|array $options Options to use when creating the instance.
+     * @param null|array<mixed> $options Options to use when creating the instance.
      * @return mixed
      * @throws Exception\ServiceNotFoundException If the manager does not have
      *     a service definition for the instance, and the service is not
@@ -167,7 +173,8 @@ public function get($name, ?array $options = null)
             $this->setFactory($name, Factory\InvokableFactory::class);
         }
 
-        $instance = empty($options) ? parent::get($name) : $this->build($name, $options);
+        /** @psalm-suppress MixedAssignment */
+        $instance = ! $options ? parent::get($name) : $this->build($name, $options);
         $this->validate($instance);
         return $instance;
     }

src/Config.php

@@ -4,13 +4,9 @@
 
 namespace Laminas\ServiceManager;
 
-use Laminas\Stdlib\ArrayUtils\MergeRemoveKey;
-use Laminas\Stdlib\ArrayUtils\MergeReplaceKeyInterface;
+use Laminas\Stdlib\ArrayUtils;
 
-use function array_key_exists;
 use function array_keys;
-use function is_array;
-use function is_int;
 
 /**
  * Object for defining configuration and configuring an existing service manager instance.
@@ -26,10 +22,12 @@
  *
  * These features are advanced, and not typically used. If you wish to use them,
  * you will need to require the laminas-stdlib package in your application.
+ *
+ * @psalm-import-type ServiceManagerConfigurationType from ConfigInterface
  */
 class Config implements ConfigInterface
 {
-    /** @var array */
+    /** @var array<string,bool> */
     private $allowedKeys = [
         'abstract_factories' => true,
         'aliases'            => true,
@@ -42,7 +40,10 @@ class Config implements ConfigInterface
         'shared'             => true,
     ];
 
-    /** @var array */
+    /**
+     * @var array<string,array>
+     * @psalm-var ServiceManagerConfigurationType
+     */
     protected $config = [
         'abstract_factories' => [],
         'aliases'            => [],
@@ -56,7 +57,7 @@ class Config implements ConfigInterface
     ];
 
     /**
-     * @param array $config
+     * @psalm-param ServiceManagerConfigurationType $config
      */
     public function __construct(array $config = [])
     {
@@ -66,6 +67,8 @@ public function __construct(array $config = [])
                 unset($config[$key]);
             }
         }
+
+        /** @psalm-suppress ArgumentTypeCoercion */
         $this->config = $this->merge($this->config, $config);
     }
 
@@ -86,32 +89,14 @@ public function toArray()
     }
 
     /**
-     * Copy paste from https://github.com/laminas/laminas-stdlib/commit/26fcc32a358aa08de35625736095cb2fdaced090
-     * to keep compatibility with previous version
-     *
-     * @link https://github.com/zendframework/zend-servicemanager/pull/68
+     * @psalm-param ServiceManagerConfigurationType $a
+     * @psalm-param ServiceManagerConfigurationType $b
+     * @psalm-return ServiceManagerConfigurationType
+     * @psalm-suppress MixedReturnTypeCoercion
      */
-    private function merge(array $a, array $b): array
+    private function merge(array $a, array $b)
     {
-        foreach ($b as $key => $value) {
-            if ($value instanceof MergeReplaceKeyInterface) {
-                $a[$key] = $value->getData();
-            } elseif (isset($a[$key]) || array_key_exists($key, $a)) {
-                if ($value instanceof MergeRemoveKey) {
-                    unset($a[$key]);
-                } elseif (is_int($key)) {
-                    $a[] = $value;
-                } elseif (is_array($value) && is_array($a[$key])) {
-                    $a[$key] = $this->merge($a[$key], $value);
-                } else {
-                    $a[$key] = $value;
-                }
-            } else {
-                if (! $value instanceof MergeRemoveKey) {
-                    $a[$key] = $value;
-                }
-            }
-        }
-        return $a;
+        /** @psalm-suppress MixedReturnTypeCoercion */
+        return ArrayUtils::merge($a, $b);
     }
 }

src/ConfigInterface.php

@@ -4,6 +4,53 @@
 
 namespace Laminas\ServiceManager;
 
+use ArrayAccess;
+use Interop\Container\ContainerInterface;
+
+/**
+ * @see ContainerInterface
+ * @see ArrayAccess
+ *
+ * @psalm-type AbstractFactoriesConfigurationType = array<
+ *      array-key,
+ *      (class-string<Factory\AbstractFactoryInterface>|Factory\AbstractFactoryInterface)
+ * >
+ * @psalm-type DelegatorsConfigurationType = array<
+ *      string,
+ *      array<
+ *          array-key,
+ *          (class-string<Factory\DelegatorFactoryInterface>|Factory\DelegatorFactoryInterface)
+ *          |callable(ContainerInterface,string,callable():object,array<mixed>|null):object
+ *      >
+ * >
+ * @psalm-type FactoriesConfigurationType = array<
+ *      string,
+ *      (class-string<Factory\FactoryInterface>|Factory\FactoryInterface)
+ *      |callable(ContainerInterface,string,array<mixed>|null)
+ * >
+ * @psalm-type InitializersConfigurationType = array<
+ *      array-key,
+ *      (class-string<Initializer\InitializerInterface>|Initializer\InitializerInterface)
+ *      |callable(ContainerInterface,object):void
+ * >
+ * @psalm-type LazyServicesConfigurationType = array{
+ *      class_map?:array<string,class-string>,
+ *      proxies_namespace?:non-empty-string,
+ *      proxies_target_dir?:non-empty-string,
+ *      write_proxy_files?:bool
+ * }
+ * @psalm-type ServiceManagerConfigurationType = array{
+ *     abstract_factories?: AbstractFactoriesConfigurationType,
+ *     aliases?: array<string,string>,
+ *     delegators?: DelegatorsConfigurationType,
+ *     factories?: FactoriesConfigurationType,
+ *     initializers?: InitializersConfigurationType,
+ *     invokables?: array<string,string>,
+ *     lazy_services?: LazyServicesConfigurationType,
+ *     services?: array<string,object|array>,
+ *     shared?:array<string,bool>
+ * }
+ */
 interface ConfigInterface
 {
     /**
@@ -37,6 +84,7 @@ public function configureServiceManager(ServiceManager $serviceManager);
      * a service manager or plugin manager, or pass to its `withConfig()` method.
      *
      * @return array
+     * @psalm-return ServiceManagerConfigurationType
      */
     public function toArray();
 }

src/Exception/ContainerModificationsNotAllowedException.php

@@ -8,9 +8,6 @@
 
 use function sprintf;
 
-/**
- * @inheritDoc
- */
 class ContainerModificationsNotAllowedException extends DomainException implements ExceptionInterface
 {
     /**

src/Factory/DelegatorFactoryInterface.php

@@ -23,6 +23,7 @@ interface DelegatorFactoryInterface
      * A factory that creates delegates of a given service
      *
      * @param  string             $name
+     * @psalm-param callable():mixed $callback
      * @param  null|array         $options
      * @return object
      * @throws ServiceNotFoundException If unable to resolve the service.

src/PluginManagerInterface.php

@@ -17,7 +17,7 @@ interface PluginManagerInterface extends ServiceLocatorInterface
     /**
      * Validate an instance
      *
-     * @param  object $instance
+     * @param  mixed $instance
      * @return void
      * @throws InvalidServiceException If created instance does not respect the
      *     constraint on type imposed by the plugin manager.

src/ServiceLocatorInterface.php

@@ -19,7 +19,7 @@ interface ServiceLocatorInterface extends
      * Build a service by its name, using optional options (such services are NEVER cached).
      *
      * @param  string $name
-     * @param  null|array  $options
+     * @param  null|array<mixed>  $options
      * @return mixed
      * @throws Exception\ServiceNotFoundException If no factory/abstract
      *     factory could be found to create the instance.