Make context universal without class extension

[oprypkhantc]

Hey.

Currently, if a user wants to store custom information in the context, they either need to:

• extend the Context class that graphqlite provides - but this breaks as soon as two separate implementations want to extend the Context
• extend the ContextInterface interface that graphqlite provides, wrap the original one and delegate all property access and method calls to the original one - but this also breaks as soon as someone attempts to type-hint it, and the implementation would be quite verbose and unstable

Instead, I propose we make Context a little more universal and a little easier to use:

class Context implements ContextInterface, ResetableContextInterface
{
	/** @var SplObjectStorage<object, mixed> */
	private SplObjectStorage $data;

	public function has(ContextToken $token): bool
	{
		return isset($this->data[$token]);
	}

	/**
	 * @template T
	 *
	 * @param ContextToken<T> $token
	 *
	 * @return T
	 */
	public function get(ContextToken $token): mixed
	{
		if ($this->has($token)) {
			return $this->data[$token];
		}

		$value = ($token->default)();

		$this->set($token, $value);

		return $value;
	}

	/**
	 * @template T
	 *
	 * @param ContextToken<T> $token
	 * @param T $value
	 */
	public function set(ContextToken $token, mixed $value): mixed
	{
		return $this->data[$token] = $value;
	}

    /** @deprecated */
	public function getPrefetchBuffer(ParameterInterface $field): PrefetchBuffer
	{
		static $token;

		if (!$token) {
			$token = new ContextToken(fn () => new PrefetchBuffer());
		}

		return $this->get($token);
	}

	public function reset(): void
	{
		$this->data = new SplObjectStorage();
	}
}

/**
 * @template-covariant T
 */
final class ContextToken
{
	/**
	 * @param Closure(): T $default
	 */
	public function __construct(
		public readonly Closure $default,
	)
	{
	}
}

which is basically an array $data, but with type-safety, autocompletion and protection from clashing. It can later be used in userland like so:

/** @return ContextToken<MyPrefetchBuffer> */
function myOwnPrefetchBufferContextToken(): ContextToken {
    // PHP 8.3+
    static $token = new ContextToken(fn () => new MyPrefetchBuffer());

    return $token;
}

// PHPStan correctly infers the type of $buffer as MyPrefetchBuffer
$buffer = $context->get(myOwnPrefetchBufferContextToken());

It could be simplified further when PHP finally allows expressions as constant values:

const PREFETCH_BUFFER_CONTEXT_TOKEN = new ContextToken(fn () => new MyPrefetchBuffer());

// PHPStan correctly infers the type of $buffer as MyPrefetchBuffer
$buffer = $context->get(PREFETCH_BUFFER_CONTEXT_TOKEN);

---

This isn't a new concept, and is widely used in JS/TS ecosystem. For example, a very similar use case exists in Angular: https://angular.dev/api/common/http/HttpContext#usage-notes . PHP implementation is, admittedly, clunky, but we do get some benefits in return:

• context can be extended without extending the class
• context can be extended from multiple sources, independently
• ContextInterface would no longer be needed

It would be perfect to have this in webonyx/graphql, but it's a bigger change for them than it is for graphqlite, so I doubt they'd accept that idea. In case of graphqlite, we can, of course, preserve full backwards compatibility, simply deprecating the interface and getPrefetchBuffer. We could also get rid of reset() in the meantime :)

[oojacoboo]

Can you outline the use case here for custom context/prefetch buffers? I'm not really opposed to opening this up, but I am wondering if the increased complexity around prefetching can't be simplified in a much more user-friendly manner.

[oprypkhantc]

Sorry, didn't see your reply :)

It's not about prefetching, rather, it's about having a dynamic context object that could be used for other purposes:

• authentication (storing auth user)
• configuration (setting configuration before a graphql operation, so it can later be checked for in middleware/resolvers/controllers)
• storing temporary handles (like a handle to a database transaction) that can be accessed by nested fields

In our case, it is used to pass in a configuration parameter that's used later in the query. This could be worked around by storing it elsewhere, but context feels like the most appropriate place as it gets created new (or reset) on every request.

If we ever get closer to async request processing, this would also be greatly beneficial - because a single thread could be processing multiple requests at once, we'd have to have a way to pass in the "http request" instance or "authenticated user", and the perfect place to do that would be the context object.

Existing prefetch could be refactored to just be one of the keys, stored in the context. Authentication could be refactored this way too.

[oojacoboo]

Thanks - took a deeper look into this. The only issue I see here is that the ContextToken (closures) are being used as keys, which makes get and has checks difficult, as you'd need to build the full closure ContextToken object perfectly. Also, what's the point of the $value if you have this ContextToken with a closure? Why not have the ContextToken be the "value" and have a more generic/standard key (string)?

[oprypkhantc]

as you'd need to build the full closure ContextToken object perfectly

You'd usually either have it stored statically (in a constant or a static var), or in a DI container - so there is no need to build it every time.

Also, what's the point of the $value if you have this ContextToken with a closure?

The point of having a closure in ContextToken is to provide a default value. Conversely, the point of $value is to provide a value different than the default one.

We could remove that and have ContextToken be just an empty class, but having that default value in the token itself allows one cool thing: instead of having to check if context already has that token set, we can directly call $context->get() in different places and never have to worry where the value should come from if it wasn't set before.

E.g.:

class SomeMiddlewareThatAccessesAuth {
    /** @param ContextToken<User> $authContextToken */
    public function __construct(
        private readonly ContextToken $authContextToken,
    ) {}

    public function handle() {
        return $queryFieldDescriptor->withResolver(function (Context $context) {
            $auth = $context->get($this->authContextToken);

            // ...

             return null;
        });
    }
}

instead of:

class SomeMiddlewareThatAccessesAuth {
    /** @param ContextToken<User> $authContextToken */
    public function __construct(
        private readonly ContextToken $authContextToken,
        private readonly AuthenticationService $authService,
    ) {}

    public function handle() {
        return $queryFieldDescriptor->withResolver(function (Context $context) {
            if (!$context->has($this->authContextToken)) {
                $context->set($this->authContextToken, $this->authService->user());
            }             

            $auth = $context->get($this->authContextToken);

            // ...

             return null;
        });
    }
}

which requires adding more dependencies (like $authService) and checks everywhere you want to use the token, if it's not a simple configuration value.

That said, I copied this design from Angular, so I'm not sure if it 100% fits the backend.

Why not have the ContextToken be the "value" and have a more generic/standard key (string)?

There are two reasons why using a special class as key is beneficial:

• there's no chance of clashing, when multiple sources access the same key and expecting that they "own" it, e.g.:

// vendor/companyA/productA/SomeGraphQLiteSource.php:

if ($auth->isAdmin()) {
    $context->set('throttle', false);
}

// somewhere later on they would expect a boolean value here:
$context->get('throttle');



// vendor/companyB/productB/SomeOtherGraphQLiteSource.php:

if (in_array($request->ip(), ['127.0.0.1', 'localhost'], true)) {
    $context->set('throttle', new ThrottleIgnoringLimiter());
} else {
    $context->set('throttle', new InMemoryLimiter(attempts: 60, perSeconds: 10));
}

// somewhere later on they would expect some kind of object, like ThrottleIgnoringLimiter or InMemoryLimiter
$context->get('throttle');

They would both be expecting a value that they set, but there's a chance someone else chose that exact key name. The documentation could recommend adding a namespace prefix (vendorA:productA:throttle), but that's still just a recommendation. Objects as keys guarantees this never happens.

This is an unlikely scenario, but as I said above, I copied Angular's design and I believe they made the right choice with such a design.

• it allows inferring the value that you get, and a guarantee that you wont set a value of wrong type:

// PHPStan knows the type of this var is `ContextToken<User>`, based on the closure.
// Or, without the closure, it could be defined like `/** @var ContextToken<User> */`
$authContextToken = new ContextToken(fn () => $this->authService->user());

// Both PHPStan and the IDE infer the type as `User` automatically
$user = $context->get($authContextToken);

// PHPStan errors: Passed boolean value to an argument #2 of type `User`
$context->set($authContextToken, true);

while with string keys, no such guarantees or inference would be possible:

// Inferred type - `mixed`
$context->get('auth');

// No errors in all cases
$context->set('auth', true);
$context->set('auth', 123);
$context->set('auth', new User());

[oojacoboo]

You'd usually either have it stored statically (in a constant or a static var), or in a DI container - so there is no need to build it every time.

I understand what you're going for here, but I don't think this is how most people would use a context (key/value store) and don't think storing a closure on a constant or static var is particularly common, especially as a key. But, I do agree that people would likely start leaning towards doing that with a design like this. I don't consider assigning a bunch of closures to constants as a positive - more of a requirement to make this design work.

I had some comments in regards to the specifics of your examples and extra detail, but will just give my overall thoughts instead. Thanks for providing that BTW.

My opinion on this is that it's strange. It gets around some typing issues using PHPStan generics, which is nice. But, of course, there is no guarantee this will ever made it into the runtime (not of particular concern). I don't like the object as a key because you have to rebuild the object to check for it. That limits how you can store the keys too - storing in a database becomes significantly more challenging and a bunch of closures as constants in PHP code is pretty non-standard.

Overall, I'm not entirely opposed to this. It has some advantages, but tradeoffs as well. Maybe you or someone else has some other input here.

[oprypkhantc]

I understand what you're going for here, but I don't think this is how most people would use a context (key/value store) and don't think storing a closure on a constant or static var is particularly common, especially as a key. But, I do agree that people would likely start leaning towards doing that with a design like this. I don't consider assigning a bunch of closures to constants as a positive - more of a requirement to make this design work.

I see. Well, with or without closures, context keys must remain singletons, so their ID stays the same.

It gets around some typing issues using PHPStan generics, which is nice.

Lately I've been designing a lot of my code around proper typing and although it gets verbose sometimes, I think you get a better designed system in the end. Might not be the case here, but just saying :)

storing in a database becomes significantly more challenging and a bunch of closures as constants in PHP code is pretty non-standard.

Storing these in a database would not even be possible, as objects are identified by their ID, not properties. But I also don't believe it's a huge concern, as serializing values (for example, if DI container was inside the context, or auth user) is a much bigger problem anyway.