New Interfaces for Field Directives

The current set of Interfaces for Field Directives are FieldMiddleware and FieldResolver. While the are treated differently in directive resolution, they are functionally the same - both recieve and return a FieldValue.

This puts the burden of providing a stable, public API on FieldValue - so we would not be able to change its implementation should we require to do so. Also, since the FieldValue can be mutated in any way, it makes it really hard to know what a directive actually does.

First, i propose giving field directives access to the underlying FieldDefinitionNode. This is easy to do, since directives are already retrieved by looking at the definition, it can easily be passed in.

Second, i propose a set of interfaces. Field directives are allowed to implement any number of them, thus clearly specifying what they do.

<?php

interface FieldManipulator {
    // This is applied first and allows to change the underlying definition of the AST
    // It returns a new version of the AST
    public function manipulateSchema(ObjectTypeDefinitionNode $parentType, DocumentAST $current, DocumentAST $original): DocumentAST;
}

interface FieldArgumentsHandler {
    // Recieves the typical resolver arguments and is allowed to change them
    // ResolverArguments contains $rootValue, $args, $context and $resolveInfo
    public function handleArguments(ResolverArguments $resolverArguments): ResolverArguments;
} 

interface FieldResolver {
    // This does actually resolve the field and may return any value
    public function resolve(ResolverArguments $resolverArguments);
}

interface FieldValueHandler {
    // This recieves the resolved value and may further modify it before returning it
    public function handleValue($value);
}

Locate the existing FieldMiddleware and FieldResolver interfaces and the directive-resolution entry points first. Review how FieldValue currently flows through resolution and how the FieldDefinitionNode is available. Done means the proposed directive capabilities are represented by clear interfaces without requiring FieldValue to remain the public API.