Add spec memoization via PSR-16, sound fast-path, and bundled InMemoryCache

Deep object-graph construction through the resolver makes repeated
ReflectionParameter introspection (getName/getType/isVariadic etc.)
a bottleneck. Cache the per-callable spec -- name, non-builtin type,
variadic flag, default-available flag -- in a PSR-16 cache supplied as
an optional second constructor argument. The key is derived from the
callable's stable identity (FQCN::method or fn:name); closures and
invocable objects bypass the cache. Default values are deliberately
excluded from the spec and fetched lazily only when the slow-path
default branch executes, so PHP 8.1+ `new Foo()` defaults do not run
prematurely.

A sound fast-path returns the arguments unchanged when the resolution
would be a no-op: no named args, no variadic, positional count equals
parameter count, and each positional already satisfies its parameter's
type (or the container lacks that type). This avoids the loop and
container lookups in the common DI case where the caller supplies all
args in order. A naive count-only fast path is unsound because
container injection shifts positionals.

The commit adds `psr/simple-cache: ^3.0` as a runtime dependency and
bundles `Respect\Parameter\InMemoryCache`, a zero-dependency array-
backed PSR-16 implementation whose entries live for the cache
instance's lifetime. Users get spec memoization out of the box by
passing `new InMemoryCache()` as the second constructor argument, with
no external cache package needed.

New test fixtures (TwoRequiredConsumer, ConsumerWithExpensiveDefault,
ExpensiveDefaultService) and an ArrayCache fixture subclass exercise
both fast-path branches, cache-sharing across reflection instances,
lazy-default behavior, and the full PSR-16 contract.

Author: henriquemoody

README.md

@@ -52,6 +52,36 @@ container; the remaining parameters are filled by type and defaults:
 $args = $resolver->resolve($constructor, ['username' => 'admin']);
 ```
 
+### Memoize parameter introspection
+
+Reflection is expensive. The resolver accepts an optional PSR-16 cache as its second argument;
+when supplied, the per-parameter spec (name, type, variadic flag, default-available flag) is
+memoized under a stable key derived from the callable identity (`FQCN::method` for methods,
+`fn:name` for named functions), so repeated `resolve()` calls on different
+`ReflectionMethod` / `ReflectionFunction` instances of the same callable share one spec and
+skip `ReflectionParameter` method calls entirely. Closures and invocable objects have no stable
+identity across reflections and bypass the cache.
+
+```php
+use Respect\Parameter\Resolver;
+
+$resolver = new Resolver($container, $psr16Cache);
+```
+
+The package ships with a ready-to-use in-memory PSR-16 implementation so you get the memoization
+benefit with no external dependency:
+
+```php
+use Respect\Parameter\InMemoryCache;
+use Respect\Parameter\Resolver;
+
+$resolver = new Resolver($container, new InMemoryCache());
+```
+
+`InMemoryCache` is a process-local array-backed cache: entries live for the lifetime of the
+cache instance and are not shared across processes. For longer-lived or shared caching, pass any
+real PSR-16 implementation (Symfony Cache, PSR-16 adapter over APCu, etc.).
+
 ### Bind to the interface
 
 Type-hint `ParameterResolver` (the `resolve()` contract) rather than the concrete `Resolver` to stay
@@ -98,6 +128,9 @@ Resolver::acceptsType($reflection, LoggerInterface::class); // true/false
 
 `Resolver` implements `ParameterResolver`.
 
+`InMemoryCache` implements `Psr\SimpleCache\CacheInterface` and is the bundled zero-dependency
+PSR-16 cache for memoizing the resolver's parameter spec.
+
 ## License
 
 ISC. See [LICENSE](LICENSE).

composer.json

@@ -12,7 +12,8 @@
     ],
     "require": {
         "php": "^8.5",
-        "psr/container": "^2.0"
+        "psr/container": "^2.0",
+        "psr/simple-cache": "^3.0"
     },
     "require-dev": {
         "phpstan/phpstan": "^2.1",

composer.lock

@@ -0,0 +1,115 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Parameter;
+
+use DateInterval;
+use Psr\SimpleCache\CacheInterface;
+use Psr\SimpleCache\InvalidArgumentException;
+
+use function array_key_exists;
+use function is_string;
+
+/**
+ * In-memory PSR-16 cache backed by a PHP array.
+ *
+ * Ships with the package so users get a working spec cache out of the box: pass it as the
+ * second argument to {@see Resolver} and per-callable parameter introspection is memoized
+ * for the lifetime of the cache instance, with no external cache dependency required.
+ *
+ * The cache lives for the lifetime of this object: it is not shared across processes and is
+ * lost when the object is garbage-collected. For longer-lived or shared caching, use a real
+ * PSR-16 implementation (Symfony Cache, PSR-16 adapter over APCu, etc.).
+ *
+ * TTLs are accepted for PSR-16 conformance but ignored: this is a process-local cache, so
+ * entries never expire on their own. Call {@see clear()} or {@see delete()} to remove entries.
+ *
+ * Not marked final so test doubles and integrations can subclass it to add instrumentation
+ * (e.g. hit/miss counters) without re-implementing the whole contract.
+ */
+class InMemoryCache implements CacheInterface
+{
+    /** @var array<string, mixed> */
+    protected array $store = [];
+
+    public function get(string $key, mixed $default = null): mixed
+    {
+        return array_key_exists($key, $this->store) ? $this->store[$key] : $default;
+    }
+
+    public function set(string $key, mixed $value, DateInterval|int|null $ttl = null): bool
+    {
+        $this->store[$key] = $value;
+
+        return true;
+    }
+
+    public function delete(string $key): bool
+    {
+        unset($this->store[$key]);
+
+        return true;
+    }
+
+    public function clear(): bool
+    {
+        $this->store = [];
+
+        return true;
+    }
+
+    /**
+     * @param iterable<string> $keys
+     *
+     * @return iterable<string, mixed>
+     */
+    public function getMultiple(iterable $keys, mixed $default = null): iterable
+    {
+        $out = [];
+        foreach ($keys as $key) {
+            $out[$key] = $this->get($key, $default);
+        }
+
+        return $out;
+    }
+
+    /**
+     * @param iterable<string, mixed> $values
+     *
+     * @throws InvalidArgumentException When a key is not a non-empty string.
+     */
+    public function setMultiple(iterable $values, DateInterval|int|null $ttl = null): bool
+    {
+        foreach ($values as $key => $value) {
+            /** @phpstan-ignore function.alreadyNarrowedType (defensive: callers may pass int-keyed arrays that PHP upcasts to int on iteration) */
+            if (!is_string($key) || $key === '') {
+                throw new InvalidCacheKey('Cache keys must be non-empty strings.');
+            }
+
+            $this->store[$key] = $value;
+        }
+
+        return true;
+    }
+
+    /** @param iterable<string> $keys */
+    public function deleteMultiple(iterable $keys): bool
+    {
+        foreach ($keys as $key) {
+            unset($this->store[$key]);
+        }
+
+        return true;
+    }
+
+    public function has(string $key): bool
+    {
+        return array_key_exists($key, $this->store);
+    }
+}

src/InMemoryCache.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Parameter;
+
+use Psr\SimpleCache\InvalidArgumentException;
+use RuntimeException;
+
+/**
+ * Thrown by {@see InMemoryCache::setMultiple()} when a caller passes a key that
+ * violates the PSR-16 key contract (non-string or empty string).
+ *
+ * Implements the PSR-16 `InvalidArgumentException` marker interface so callers
+ * that catch `Psr\SimpleCache\InvalidArgumentException` see it as a standard
+ * PSR-16 exception, while still carrying a concrete class name for typed
+ * catches in application code.
+ */
+final class InvalidCacheKey extends RuntimeException implements InvalidArgumentException
+{
+}