Introduce scope-aware Context and #[MapContext]

Resolvers often need per-request data that is neither a GraphQL input
nor a DI service: the current HTTP request, the authenticated user, or a
value computed by an ancestor field. Until now the generated resolver
closures ignored webonyx's context value entirely, so the only escape
hatches were `#[Arg]` (client input) and `#[Autowire]` (container), and
there was no way to thread request state to a resolver.

This adds a first-class `Context` value object and a `#[MapContext]`
parameter attribute. `Context` is a webonyx `ScopedContext` that stores
objects by class (`attachObject`/`getObject`/`maybeGetObject`) and also
implements `ArrayAccess`; because it is scoped, a value attached by a
resolver is visible to its descendants without leaking to siblings.
`#[MapContext]` injects an object from the `Context` into a resolver
parameter by its type — nullable parameters resolve to `null` when
absent, non-nullable parameters throw.

The generated query, mutation, and field closures now receive webonyx's
context as a `mixed` value and pass it through to `ArgumentNodeResolver`.
The value is left untouched (it can be anything the server provides);
only `#[MapContext]` resolution requires it to be a `Context`, throwing a
`ContextException` otherwise. Wiring a `Context` onto the server is up to
the consumer via the webonyx `context` option (see the docs).

Author: ruudk

docs/getting_started.md

@@ -45,6 +45,10 @@ $server = new StandardServer(ServerConfig::create([
 ]));
 ```
 
+💡 *Want to pass per-request data (the HTTP request, the current user, …) to your resolvers? Set a*
+`Context` *as the server's context value and read it with* `#[MapContext]`*. See*
+[#[MapContext]](usage.md#mapcontext) *and* [Context](usage.md#context).
+
 📌 *This library does not create a GraphQL server for you.*  
 
 To learn how to set up a server, check the [webonyx documentation](https://webonyx.github.io/graphql-php/executing-queries/#using-server).

docs/usage.md

@@ -21,6 +21,7 @@ You can use the following attributes:
 - [#[Field]](#field)
 - [#[Arg]](#arg)
 - [#[Autowire]](#autowire)
+- [#[MapContext]](#mapcontext)
 - [#[Scalar]](#scalar)
 - [#[Cursor]](#cursor)
 
@@ -492,6 +493,107 @@ By default, the service to inject is determined by the parameter type. If needed
 |-----------|------------------------------------------------------------------------------------|
 | `service` | *(Optional)* Custom service identifier to retrieve from the DI container (PSR-11). |
 
+### #[MapContext]
+
+Webonyx/graphql-php passes a **context value** to every resolver. This library wraps it in a
+`Context` object (see [Context](#context)) that you can populate per request — for example with the
+current HTTP request, the authenticated user, or any value resolved higher up in the query tree.
+
+`#[MapContext]` injects an object stored in that `Context` into a resolver parameter, looked up by the
+parameter's type. It works on `#[Query]`, `#[Mutation]`, and `#[Field]` method parameters.
+
+```php
+use Jerowork\GraphqlAttributeSchema\Attribute\MapContext;
+use Jerowork\GraphqlAttributeSchema\Attribute\Query;
+use Symfony\Component\HttpFoundation\Request;
+
+final readonly class YourQuery
+{
+    #[Query]
+    public function yourQuery(
+        int $filter,
+        #[MapContext]
+        Request $request,
+    ): YourType {
+        // $request is fetched from the Context by its class
+    }
+}
+```
+
+A resolver can also attach objects to the `Context` so descendant fields can read them through
+`#[MapContext]`. Because `Context` is a webonyx `ScopedContext`, children receive a clone, so values
+attached by a resolver are visible to its descendants without leaking to sibling fields:
+
+```php
+#[Field]
+public function getChild(Context $context): ChildType
+{
+    $context->attachObject(new Locale('en'));
+    // ... children resolving under this field can now `#[MapContext] Locale $locale`
+}
+```
+
+#### Nullable parameters
+
+- A **non-nullable** parameter (`Request $request`) throws a `ContextException` when no matching object
+  is present in the `Context`.
+- A **nullable** parameter (`?Request $request`) resolves to `null` when no matching object is present.
+
+#### Requirements
+
+- The parameter must be type-hinted with a class (not a built-in type).
+- The GraphQL context value **must** be an instance of
+  `Jerowork\GraphqlAttributeSchema\Context`. If it is anything else, a `ContextException` is thrown when
+  the parameter is resolved. See [Context](#context) for how to set this up on your server.
+
+### Context
+
+`Jerowork\GraphqlAttributeSchema\Context` is the per-request context value passed to your resolvers. It
+stores objects keyed by their class and also implements `ArrayAccess`, so you can use it as a typed
+container or as a simple map.
+
+```php
+use Jerowork\GraphqlAttributeSchema\Context;
+
+$context = new Context();
+
+// Attach by class
+$context->attachObject($request);            // stored under Request::class
+$request = $context->getObject(Request::class);      // throws if missing/wrong type
+$request = $context->maybeGetObject(Request::class); // null if missing
+
+// Or as an array (any key)
+$context[Request::class] = $request;
+$locale = $context['locale'] ?? null;
+```
+
+Set it on your server through the webonyx `context` option. Using a callable means a fresh `Context`
+is built per request:
+
+```php
+use GraphQL\Error\DebugFlag;
+use GraphQL\Server\ServerConfig;
+use GraphQL\Server\StandardServer;
+use Jerowork\GraphqlAttributeSchema\Context;
+use Symfony\Component\HttpFoundation\Request;
+
+$config = [
+    'schema' => $this->createSchema(),
+    'context' => function () {
+        $context = new Context();
+        $context[Request::class] = $this->requestStack->getMainRequest();
+
+        return $context;
+    },
+];
+
+if ($this->environment !== EnvironmentName::PROD) {
+    $config['debugFlag'] = DebugFlag::INCLUDE_DEBUG_MESSAGE | DebugFlag::INCLUDE_TRACE | DebugFlag::RETHROW_INTERNAL_EXCEPTIONS;
+}
+
+return new StandardServer(ServerConfig::create($config));
+```
+
 ### #[Scalar]
 
 Webonyx/graphql-php comes with four built-in scalar types:

phpstan-baseline.php

@@ -8,7 +8,7 @@
 	'path' => __DIR__ . '/src/Node/Child/ArgNode.php',
 ];
 $ignoreErrors[] = [
-	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\FieldNode\\:\\:toArray\\(\\) should return array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>, payload\\: array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, propertyName\\: string\\}\\|array\\{service\\?\\: string, propertyName\\: string\\}\\}\\>, fieldType\\: string, methodName\\: string\\|null, propertyName\\: string\\|null, deprecationReason\\: string\\|null, \\.\\.\\.\\} but returns array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}\\>, fieldType\\: \'method\'\\|\'property\', methodName\\: string\\|null, propertyName\\: string\\|null, deprecationReason\\: string\\|null, \\.\\.\\.\\}\\.$#',
+	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\FieldNode\\:\\:toArray\\(\\) should return array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>, payload\\: array\\{className\\: class\\-string, propertyName\\: string, nullable\\: bool\\}\\|array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, propertyName\\: string\\}\\|array\\{service\\?\\: string, propertyName\\: string\\}\\}\\>, fieldType\\: string, methodName\\: string\\|null, propertyName\\: string\\|null, deprecationReason\\: string\\|null, \\.\\.\\.\\} but returns array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}\\>, fieldType\\: \'method\'\\|\'property\', methodName\\: string\\|null, propertyName\\: string\\|null, deprecationReason\\: string\\|null, \\.\\.\\.\\}\\.$#',
 	'identifier' => 'return.type',
 	'count' => 1,
 	'path' => __DIR__ . '/src/Node/Child/FieldNode.php',
@@ -20,7 +20,7 @@
 	'path' => __DIR__ . '/src/Node/Child/FieldNode.php',
 ];
 $ignoreErrors[] = [
-	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\MutationNode\\:\\:toArray\\(\\) should return array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>, payload\\: array\\{propertyName\\: string\\}\\|array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, propertyName\\: string\\}\\}\\>, outputReference\\: array\\{type\\: class\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\} but returns array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}\\>, outputReference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\}\\.$#',
+	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\MutationNode\\:\\:toArray\\(\\) should return array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>, payload\\: array\\{className\\: class\\-string, propertyName\\: string, nullable\\: bool\\}\\|array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, propertyName\\: string\\}\\|array\\{service\\?\\: string, propertyName\\: string\\}\\}\\>, outputReference\\: array\\{type\\: class\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\} but returns array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}\\>, outputReference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\}\\.$#',
 	'identifier' => 'return.type',
 	'count' => 1,
 	'path' => __DIR__ . '/src/Node/MutationNode.php',
@@ -32,7 +32,7 @@
 	'path' => __DIR__ . '/src/Node/MutationNode.php',
 ];
 $ignoreErrors[] = [
-	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\QueryNode\\:\\:toArray\\(\\) should return array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>, payload\\: array\\{propertyName\\: string\\}\\|array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, propertyName\\: string\\}\\}\\>, outputReference\\: array\\{type\\: class\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\} but returns array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}\\>, outputReference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\}\\.$#',
+	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\QueryNode\\:\\:toArray\\(\\) should return array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>, payload\\: array\\{className\\: class\\-string, propertyName\\: string, nullable\\: bool\\}\\|array\\{reference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>, payload\\: array\\<string, mixed\\>\\}, name\\: string, description\\: string\\|null, propertyName\\: string\\}\\|array\\{service\\?\\: string, propertyName\\: string\\}\\}\\>, outputReference\\: array\\{type\\: class\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\} but returns array\\{className\\: class\\-string, name\\: string, description\\: string\\|null, argumentNodes\\: list\\<array\\{node\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\Child\\\\ArgumentNode\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}\\>, outputReference\\: array\\{type\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Node\\\\TypeReference\\\\TypeReference\\>&literal\\-string, payload\\: array\\<string, mixed\\>\\}, methodName\\: string, deprecationReason\\: string\\|null, deferredTypeLoader\\: class\\-string\\<Jerowork\\\\GraphqlAttributeSchema\\\\Type\\\\Loader\\\\DeferredTypeLoader\\>\\|null\\}\\.$#',
 	'identifier' => 'return.type',
 	'count' => 1,
 	'path' => __DIR__ . '/src/Node/QueryNode.php',
@@ -97,6 +97,12 @@
 	'count' => 1,
 	'path' => __DIR__ . '/src/NodeParser/Child/CursorNodeParser.php',
 ];
+$ignoreErrors[] = [
+	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\NodeParser\\\\Child\\\\MapContextNodeParser\\:\\:getAttribute\\(\\) has parameter \\$reflector with generic class ReflectionClass but does not specify its types\\: T$#',
+	'identifier' => 'missingType.generics',
+	'count' => 1,
+	'path' => __DIR__ . '/src/NodeParser/Child/MapContextNodeParser.php',
+];
 $ignoreErrors[] = [
 	'message' => '#^Method Jerowork\\\\GraphqlAttributeSchema\\\\NodeParser\\\\EnumNodeParser\\:\\:getAttribute\\(\\) has parameter \\$reflector with generic class ReflectionClass but does not specify its types\\: T$#',
 	'identifier' => 'missingType.generics',

src/Attribute/MapContext.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Jerowork\GraphqlAttributeSchema\Attribute;
+
+use Attribute;
+
+/**
+ * Maps a resolver method parameter to an object stored in the GraphQL Context.
+ *
+ * The object is fetched from the Context by the parameter's type. A nullable parameter resolves to
+ * null when the object is absent; a non-nullable parameter throws when it is absent.
+ */
+#[Attribute(Attribute::TARGET_PARAMETER)]
+final readonly class MapContext {}

src/Context.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Jerowork\GraphqlAttributeSchema;
+
+use ArrayAccess;
+use ArrayIterator;
+use GraphQL\Executor\ScopedContext;
+use IteratorAggregate;
+use Override;
+use Traversable;
+
+/**
+ * Per-request GraphQL context.
+ *
+ * Stores arbitrary values, keyed by class-string for objects (see attachObject/getObject) and by
+ * any key through the ArrayAccess interface. As a webonyx ScopedContext, child fields receive a
+ * clone, so values attached by a resolver are visible to its descendants without leaking to siblings.
+ *
+ * @implements ArrayAccess<array-key, mixed>
+ * @implements IteratorAggregate<array-key, mixed>
+ */
+final class Context implements ArrayAccess, IteratorAggregate, ScopedContext
+{
+    /**
+     * @param array<array-key, mixed> $store
+     */
+    public function __construct(
+        private array $store = [],
+    ) {}
+
+    public function attachObject(object $object): void
+    {
+        $this->store[$object::class] = $object;
+    }
+
+    /**
+     * @template T of object
+     *
+     * @param class-string<T> $fqcn
+     *
+     * @throws ContextException
+     *
+     * @return T
+     */
+    public function getObject(string $fqcn): object
+    {
+        if (!array_key_exists($fqcn, $this->store)) {
+            throw ContextException::missingObject($fqcn);
+        }
+
+        $object = $this->store[$fqcn];
+
+        if (!$object instanceof $fqcn) {
+            throw ContextException::unexpectedObjectType($fqcn);
+        }
+
+        return $object;
+    }
+
+    /**
+     * @template T of object
+     *
+     * @param class-string<T> $fqcn
+     *
+     * @throws ContextException
+     *
+     * @return null|T
+     */
+    public function maybeGetObject(string $fqcn): ?object
+    {
+        if (!array_key_exists($fqcn, $this->store)) {
+            return null;
+        }
+
+        $object = $this->store[$fqcn];
+
+        if (!$object instanceof $fqcn) {
+            throw ContextException::unexpectedObjectType($fqcn);
+        }
+
+        return $object;
+    }
+
+    #[Override]
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->store[$offset]);
+    }
+
+    #[Override]
+    public function offsetGet(mixed $offset): mixed
+    {
+        return $this->store[$offset] ?? null;
+    }
+
+    #[Override]
+    public function offsetSet(mixed $offset, mixed $value): void
+    {
+        if ($offset === null) {
+            $this->store[] = $value;
+
+            return;
+        }
+
+        $this->store[$offset] = $value;
+    }
+
+    #[Override]
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->store[$offset]);
+    }
+
+    #[Override]
+    public function getIterator(): Traversable
+    {
+        return new ArrayIterator($this->store);
+    }
+
+    #[Override]
+    public function clone(): self
+    {
+        return new self($this->store);
+    }
+}

src/ContextException.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Jerowork\GraphqlAttributeSchema;
+
+use RuntimeException;
+
+final class ContextException extends RuntimeException
+{
+    public static function contextNotAvailable(string $fqcn): self
+    {
+        return new self(sprintf(
+            'Cannot map context parameter of type %s: the GraphQL context value is not an instance of %s. '
+            . 'Provide a %s as the context value on your GraphQL server.',
+            $fqcn,
+            Context::class,
+            Context::class,
+        ));
+    }
+
+    public static function missingObject(string $fqcn): self
+    {
+        return new self(sprintf('No object of type %s found in context', $fqcn));
+    }
+
+    public static function unexpectedObjectType(string $fqcn): self
+    {
+        return new self(sprintf('Object in context is not of expected type %s', $fqcn));
+    }
+}