Add code-first applied directives support for schema printing

[spawnia]

Adds support for printing applied directives from code-first schema definitions in the SchemaPrinter.

[spawnia]

Not sure if I like the naming of that one, but we can not simply call it directives like in other schema elements - as that is already taken.

[spawnia]

Those types could probably be moved to somewhere else and imported here.

[spawnia]

I don't love the pass-by-reference API of filling this, might redesign this to be functional.

[spawnia]

Duplicated with above, might extract.

[spawnia]

Needs tests/specification for conflicts between built-in directives (e.g. deprecationReason + manual @deprecated addition).

[spawnia]

This option might not be fine-grained enough. Printing extra directives is not necessarily all-or-nothing - depending on the use case (e.g. federation), we might only need to print selected directives. I think that selection is a function of the schema printer - otherwise, we require different schema constructions.

[spawnia]

@ruudk @simPod @LastDragon-ru First draft, what do you think? I have added some concrete discussion points. Feel free to comment and/or suggest anything else.

[LastDragon-ru]

/** @var array<GraphQL\Language\AST\DirectiveNode> */
public array $directives;

I'm not sure about suggested GraphQL\Language\AST\DirectiveNode because seems the only way to create it is Parser::directive("@directive(arg: 123)") (+ requires args escaping...).

If I understand correctly, now we have only \GraphQL\Type\Definition\Directive - the definition of the directive (and example in the documentation). So maybe a new type for "usage" will be better? (but we will also need a way to get the definition)

[spawnia]

Responding to #1857 (comment) by @LastDragon-ru:

I'm not sure about suggested GraphQL\Language\AST\DirectiveNode because seems the only way to create it is Parser::directive("@directive(arg: 123)") (+ requires args escaping...).

Direct instantiation is possible, albeit a bit cumbersome:

use GraphQL\Language\AST\ArgumentNode;
use GraphQL\Language\AST\DirectiveNode;
use GraphQL\Language\AST\IntValueNode;
use GraphQL\Language\AST\NameNode;
use GraphQL\Language\AST\NodeList;

$node = new DirectiveNode([
    'name' => new NameNode([
        'value' => 'directive',
    ]),
    'arguments' => new NodeList([
        new ArgumentNode([
            'name' => new NameNode([
                'value' => 'arg',
            ]),
            'value' => new IntValueNode([
                'value' => '123', // IntValueNode stores numeric literal as string
            ]),
        ]),
    ]),
]);

I guess this could be simplified through a dedicated type, but that makes it harder to handle directive applications in the printer, given we want to support printing from SDL-first and code-first schemas. A simplified version might look something like this:

$applied = new AppliedDirective([
    'name' => 'directive',
    'arguments' => [
        'arg' => 123,
    ],
]);

However, that runs into an issue of distinguishing between string and enum literals. 'arg' => 'FOO' might print as arg: "FOO" or arg: FOO, depending on the type of the directive argument. We could add an explicit marker, or require directive type information to print this correctly.

[LastDragon-ru]

However, that runs into an issue of distinguishing between string and enum literals

Good point. Another point - args: array[] is not strict, so we probably will need some checks to make phpstan happy :) I just personally prefer to avoid mixed. Although directives args never properly validated even in graphal-js... (#1539 graphql/graphql-js#1389)

I guess this could be simplified through a dedicated type, but that makes it harder to handle directive applications in the printer, given we want to support printing from SDL-first and code-first schemas.

Yep. But the current approach also makes it harder. If we have astNode and directives what should be used?

• astNode->directives
• directives
• both

One more question - will it ($directives) conflict with graphql/graphql-js#1343 ?

[Copilot]

Pull request overview

Adds code-first support for applied directives (as DirectiveNode instances) on schema/type/field/arg definitions, and enables optionally printing those applied directives in SDL via SchemaPrinter.

Changes:

• Add SchemaConfig::$schemaDirectives (+ getters/setter) to support schema-level applied directives in code-first schemas.
• Add directives config/property support (as DirectiveNode[]) to several definition classes (types, fields, args, enum values, input fields).
• Add SchemaPrinter option includeAppliedDirectives to print applied directives collected from config + AST nodes + extension AST nodes; add tests/docs.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Utils/SchemaPrinterTest.php	Adds coverage for applied-directive printing (off by default, on when enabled, includes AST + extensions).
tests/Type/SchemaConfigTest.php	Adds coverage for SchemaConfig::schemaDirectives getter/setter behavior.
src/Utils/SchemaPrinter.php	Implements applied-directive collection/printing behind includeAppliedDirectives.
src/Type/SchemaConfig.php	Introduces schemaDirectives storage and API on schema config.
src/Type/Definition/UnionType.php	Adds directives config/property for unions.
src/Type/Definition/ScalarType.php	Adds directives config/property for scalars.
src/Type/Definition/ObjectType.php	Adds directives config/property for objects.
src/Type/Definition/InterfaceType.php	Adds directives config/property for interfaces.
src/Type/Definition/InputObjectType.php	Adds directives config/property for input objects (and removes duplicated @throws).
src/Type/Definition/InputObjectField.php	Adds directives config/property for input fields.
src/Type/Definition/FieldDefinition.php	Adds directives config/property for field definitions.
src/Type/Definition/EnumValueDefinition.php	Adds directives config/property for enum values.
src/Type/Definition/EnumType.php	Adds directives config/property for enum types.
src/Type/Definition/CustomScalarType.php	Updates config phpdoc to mention directives.
src/Type/Definition/Argument.php	Adds directives config/property for arguments.
docs/class-reference.md	Documents schemaDirectives and includeAppliedDirectives options/type aliases.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

src/Utils/SchemaPrinter.php:410

• When includeAppliedDirectives is enabled, scalars that have specifiedByURL set (often derived from an @specifiedBy directive in the AST) will print @specifiedBy(...) twice: once via printSpecifiedBy() and again via applied directives collection. Exclude specifiedBy from applied directives when specifiedByURL is non-null to avoid duplicate directives in SDL output.

        return static::printDescription($options, $type)
            . "scalar {$type->name}"
            . static::printSpecifiedBy($type)
            . self::printAppliedDirectivesIfEnabled($options, $type);

docs/class-reference.md:3106

• This fenced block is marked as PHP (```php) but the @phpstan-type` ...` lines are PHPDoc annotations, not valid PHP code. With the newly added @phpstan-type` AppliedDirective*` lines the snippet becomes harder to copy/paste. Consider commenting these lines (or switching the code fence language to `text`) so the block content is syntactically valid.

  includeAppliedDirectives?: bool,
}
@phpstan-type AppliedDirectiveDefinition Schema|Argument|FieldDefinition|InputObjectField|EnumValueDefinition|ScalarType|ObjectType|InterfaceType|UnionType|EnumType|InputObjectType
@phpstan-type AppliedDirectiveAstNode SchemaDefinitionNode|SchemaExtensionNode|InputValueDefinitionNode|FieldDefinitionNode|EnumValueDefinitionNode|ScalarTypeDefinitionNode|ScalarTypeExtensionNode|ObjectTypeDefinitionNode|ObjectTypeExtensionNode|InterfaceTypeDefinitionNode|InterfaceTypeExtensionNode|UnionTypeDefinitionNode|UnionTypeExtensionNode|EnumTypeDefinitionNode|EnumTypeExtensionNode|InputObjectTypeDefinitionNode|InputObjectTypeExtensionNode