Refactor configuration to immutable types

psalm.xml.dist

@@ -6,6 +6,7 @@
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
     errorBaseline="psalm-baseline.xml"
     findUnusedPsalmSuppress="true"
+    findUnusedBaselineEntry="true"
     findUnusedCode="true"
 >
     <projectFiles>

src/Config.php

@@ -74,11 +74,13 @@
  * For classes known from the definitions, a type preference might be the
  * better approach
  *
+ * @deprecated Since 3.16.0. This class will be removed in 4.0. Please use the immutable and typesafe
+ *             {@link Config\InjectionConfig} variant.
+ *
  * @see \Laminas\Di\Resolver\ValueInjection A container to force injection of a value
  * @see \Laminas\Di\Resolver\TypeInjection  A container to force looking up a specific type instance for injection
  *
  * @final
- *
  * @psalm-type TypeConfigArray = array{
  *  typeOf?: class-string|null,
  *  preferences?: array<string, string>|null,

src/Config/AliasConfig.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config;
+
+/**
+ * Provides type configuration for a type alias (virtual type)
+ */
+final readonly class AliasConfig
+{
+    public function __construct(
+        public string $name,
+        public TypeConfig $type,
+    ) {
+    }
+}

src/Config/Exception/InvalidConfigException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config\Exception;
+
+use Laminas\Di\Exception\UnexpectedValueException;
+
+class InvalidConfigException extends UnexpectedValueException
+{
+}

src/Config/Exception/InvalidParametersException.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config\Exception;
+
+use function sprintf;
+
+class InvalidParametersException extends InvalidConfigException
+{
+    public static function numericParamKey(int $key): self
+    {
+        return new self(
+            sprintf(
+                'Parameter name must be an identifier, got a numeric index %d',
+                $key,
+            ),
+        );
+    }
+}

src/Config/Exception/InvalidTypePreferenceException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config\Exception;
+
+use Laminas\Di\Config\Exception\InvalidConfigException;
+
+class InvalidTypePreferenceException extends InvalidConfigException
+{
+}

src/Config/Exception/UndefinedClassException.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config\Exception;
+
+use Throwable;
+
+use function sprintf;
+
+/**
+ * This is thrown when a configured type does not exist
+ */
+class UndefinedClassException extends InvalidConfigException
+{
+    public function __construct(
+        public readonly string $className,
+        string|null $message = null,
+        int $code = 0,
+        Throwable|null $previous = null
+    ) {
+        parent::__construct($message ?? sprintf('Class "%s" does not exists', $className), $code, $previous);
+    }
+}

src/Config/InjectionConfig.php

@@ -0,0 +1,164 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config;
+
+use ArrayAccess;
+use Laminas\Di\Config\Exception\InvalidConfigException;
+use Laminas\Di\ConfigInterface;
+use Laminas\Di\Exception\LogicException;
+
+use function array_keys;
+use function get_debug_type;
+use function is_array;
+use function sprintf;
+
+/**
+ * Provides a typesafe and immutable DI configuration from a config array.
+ *
+ *  This configures the instantiation process of the dependency injector.
+ *
+ *  **Example:**
+ *
+ *  <code>
+ *  return [
+ *      // This section provides global type preferences.
+ *      // Those are visited if a specific instance has no preference definitions.
+ *      'preferences' => [
+ *          // The key is the requested class or interface name, the values are
+ *          // the types the dependency injector should prefer.
+ *          Some\Interface::class => Some\Preference::class
+ *      ],
+ *      // This configures the instantiation of specific types.
+ *      // Types may also be purely virtual by defining the aliasOf key.
+ *      'types' => [
+ *          My\Class::class => [
+ *               'preferences' => [
+ *                   // this supercedes the global type preferences
+ *                   // when My\Class is instantiated
+ *                   Some\Interface::class => 'My.SpecificAlias'
+ *               ],
+ *
+ *               // instantiation parameters. These will only be used for
+ *               // the instantiator (i.e. the constructor)
+ *               'parameters' => [
+ *                   'foo' => My\FooImpl::class, // Use the given type to provide the injection (depends on definition)
+ *                   'bar' => '*' // Use the type preferences
+ *               ],
+ *          ],
+ *
+ *          'My.Alias' => [
+ *              // typeOf defines virtual classes which can be used as type
+ *              // preferences or for newInstance calls. They allow providing
+ *              // custom configs for a class
+ *              'typeOf' => Some\Class::class,
+ *              'preferences' => [
+ *                   Foo::class => Bar::class
+ *              ]
+ *          ]
+ *      ]
+ *  ];
+ *  </code>
+ *
+ *  ## Notes on Injections
+ *
+ *  Named arguments and Automatic type lookups will only work for Methods that
+ *  are known to the dependency injector through its definitions. Injections for
+ *  unknown methods do not perform type lookups on its own.
+ *
+ *  A value injection without any lookups can be forced by providing a
+ *  Resolver\ValueInjection instance.
+ *
+ *  To force a service/class instance provide a Resolver\TypeInjection instance.
+ *  For classes known from the definitions, a type preference might be the
+ *  better approach
+ *
+ * @see \Laminas\Di\Resolver\ValueInjection A container to force injection of a value
+ * @see \Laminas\Di\Resolver\TypeInjection  A container to force looking up a specific type instance for injection
+ */
+final readonly class InjectionConfig implements ConfigInterface
+{
+    /**
+     * @param array<string, TypeConfig|AliasConfig> $types
+     */
+    public function __construct(
+        private TypePreferences $preferences = new TypePreferences(),
+        private array $types = []
+    ) {
+    }
+
+    /**
+     * Constructs the injection config from a laminas config value
+     */
+    public static function fromConfigValue(mixed $config): self
+    {
+        if (! is_array($config) && ! $config instanceof ArrayAccess) {
+            throw new InvalidConfigException(
+                sprintf(
+                    'Di configuration must be an array or implement ArrayAccess, got %s',
+                    get_debug_type($config),
+                ),
+            );
+        }
+
+        return new self(
+            TypePreferences::fromConfigValue($config['preferences'] ?? []),
+            TypeConfig::mapFromConfigValue($config['types'] ?? []),
+        );
+    }
+
+    private function getTypeConfig(string $name): TypeConfig|null
+    {
+        $type = $this->types[$name] ?? null;
+        return $type instanceof AliasConfig ? $type->type : $type;
+    }
+
+    public function isAlias(string $name): bool
+    {
+        $type = $this->types[$name] ?? null;
+        return $type instanceof AliasConfig;
+    }
+
+    public function getConfiguredTypeNames(): array
+    {
+        return array_keys($this->types);
+    }
+
+    public function getClassForAlias(string $name): string|null
+    {
+        return $this->getTypeConfig($name)?->getClassName();
+    }
+
+    public function getParameters(string $type): array
+    {
+        /**
+         * Psalm-Bug: https://github.com/vimeo/psalm/issues/7099
+         *
+         * @psalm-suppress RedundantCondition
+         * @psalm-suppress TypeDoesNotContainNull
+         */
+        return $this->getTypeConfig($type)?->parameters->toArray() ?? [];
+    }
+
+    public function setParameters(string $type, array $params)
+    {
+        throw new LogicException(
+            'Injection config is considered immutable. You can set [dependencies][auto][mutableConfig] to '
+            . 'true to restore the previous, but deprecated, behavior'
+        );
+    }
+
+    public function getTypePreference(string $type, string|null $contextClass = null): string|null
+    {
+        if ($contextClass !== null) {
+            $preference = $this->getTypeConfig($contextClass)?->preferences->getPreferenceFor($type);
+
+            if ($preference !== null) {
+                return $preference;
+            }
+        }
+
+        return $this->preferences->getPreferenceFor($type);
+    }
+}

src/Config/Parameter.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config;
+
+use Laminas\Di\Resolver\InjectionInterface;
+use Laminas\Di\Resolver\ValueInjection;
+
+use function is_string;
+
+/**
+ * Parameter injection configuration
+ */
+final readonly class Parameter
+{
+    public function __construct(
+        public string $name,
+        public string|InjectionInterface $injection,
+    ) {
+    }
+
+    public static function fromValue(string $name, mixed $value): self
+    {
+        return new self(
+            $name,
+            is_string($value) || $value instanceof InjectionInterface
+                ? $value
+                : new ValueInjection($value),
+        );
+    }
+}

src/Config/ParameterMap.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Di\Config;
+
+use Laminas\Di\Config\Exception\InvalidParametersException;
+use Laminas\Di\Resolver\InjectionInterface;
+use Laminas\Di\Util;
+
+use function array_map;
+use function array_values;
+use function get_debug_type;
+use function is_iterable;
+use function is_string;
+use function sprintf;
+
+final readonly class ParameterMap
+{
+    /** @var array<string, Parameter> */
+    private array $parameters;
+
+    public function __construct(Parameter ...$parameters)
+    {
+        $map = [];
+
+        foreach ($parameters as $parameter) {
+            $map[$parameter->name] = $parameter;
+        }
+
+        $this->parameters = $map;
+    }
+
+    /**
+     * @param mixed $parameters the parameters array from the laminas config
+     * @throws InvalidParametersException When a numeric key is encountered.
+     */
+    public static function fromConfigValue(mixed $parameters): self
+    {
+        if (! is_iterable($parameters)) {
+            throw new InvalidParametersException(
+                sprintf(
+                    'Injection parameters must be an array, got %s',
+                    get_debug_type($parameters)
+                ),
+            );
+        }
+
+        return new self(
+            ...array_values(
+                Util::mapIterable(
+                    $parameters,
+                    static function (mixed $value, string|int $key): Parameter {
+                        if ($value instanceof Parameter) {
+                            return $value;
+                        }
+
+                        if (! is_string($key)) {
+                            throw InvalidParametersException::numericParamKey($key);
+                        }
+
+                        return Parameter::fromValue($key, $value);
+                    },
+                ),
+            ),
+        );
+    }
+
+    /**
+     * @return array<string, string|InjectionInterface>
+     */
+    public function toArray(): array
+    {
+        return array_map(
+            static fn (Parameter $parameter) => $parameter->injection,
+            $this->parameters
+        );
+    }
+
+    public function get(string $key): Parameter | null
+    {
+        return $this->parameters[$key] ?? null;
+    }
+}