Skip to main content
Version: 7.0.0

Annotations reference

Note: all annotations are available both in a Doctrine annotation format (@Query) and in PHP 8 attribute format (#[Query]). See Doctrine annotations vs PHP 8 attributes for more details.

@Query

The @Query annotation is used to declare a GraphQL query.

Applies on: controller methods.

AttributeCompulsoryTypeDefinition
namenostringThe name of the query. If skipped, the name of the method is used instead.
outputTypenostringForces the GraphQL output type of a query.

@Mutation

The @Mutation annotation is used to declare a GraphQL mutation.

Applies on: controller methods.

AttributeCompulsoryTypeDefinition
namenostringThe name of the mutation. If skipped, the name of the method is used instead.
outputTypenostringForces the GraphQL output type of a query.

@Subscription

The @Subscription annotation is used to declare a GraphQL subscription.

Applies on: controller methods.

AttributeCompulsoryTypeDefinition
namenostringThe name of the subscription. If skipped, the name of the method is used instead.
outputTypenostringDefines the GraphQL output type that will be sent for the subscription.

@Type

The @Type annotation is used to declare a GraphQL object type. This is used with standard output types, as well as enum types. For input types, use the @Input annotation directly on the input type or a @Factory annoation to make/return an input type.

Applies on: classes.

AttributeCompulsoryTypeDefinition
classnostringThe targeted class/enum for the actual type. If no "class" attribute is passed, the type applies to the current class/enum. The current class/enum is assumed to be an entity (not service). If the "class" attribute is passed, the class/enum annotated with @Type becomes a service.
namenostringThe name of the GraphQL type generated. If not passed, the name of the class is used. If the class ends with "Type", the "Type" suffix is removed
defaultnoboolDefaults to true. Whether the targeted PHP class should be mapped by default to this type.
externalnoboolWhether this is an external type declaration or not. You usually do not need to use this attribute since this value defaults to true if a "class" attribute is set. This is only useful if you are declaring a type with no PHP class mapping using the "name" attribute.

@ExtendType

The @ExtendType annotation is used to add fields to an existing GraphQL object type.

Applies on: classes.

AttributeCompulsoryTypeDefinition
classsee belowstringThe targeted class. The class annotated with @ExtendType is a service.
namesee belowstringThe targeted GraphQL output type.

One and only one of "class" and "name" parameter can be passed at the same time.

@Input

The @Input annotation is used to declare a GraphQL input type.

Applies on: classes.

AttributeCompulsoryTypeDefinition
namenostringThe name of the GraphQL input type generated. If not passed, the name of the class with suffix "Input" is used. If the class ends with "Input", the "Input" suffix is not added.
descriptionnostringDescription of the input type in the documentation. If not passed, PHP doc comment is used.
defaultnoboolName of the input type represented in your GraphQL schema. Defaults to true only if the name is not specified. If name is specified, this will default to false, so must also be included for true when name is used.
updatenoboolDetermines if the the input represents a partial update. When set to true all input fields will become optional and won't have default values thus won't be set on resolve if they are not specified in the query/mutation/subscription. This primarily applies to nullable fields.

@Field

The @Field annotation is used to declare a GraphQL field.

Applies on: methods or properties of classes annotated with @Type, @ExtendType or @Input. When it's applied on private or protected property, public getter or/and setter method is expected in the class accordingly whether it's used for output type or input type. For example if property name is foo then getter should be getFoo() or setter should be setFoo($foo). Setter can be omitted if property related to the field is present in the constructor with the same name.

AttributeCompulsoryTypeDefinition
namenostringThe name of the field. If skipped, the name of the method is used instead.
fornostring, arrayForces the field to be used only for specific output or input type(s). By default field is used for all possible declared types.
descriptionnostringField description displayed in the GraphQL docs. If it's empty PHP doc comment is used instead.
outputTypenostringForces the GraphQL output type of a query.
inputTypenostringForces the GraphQL input type of a query.

@SourceField

The @SourceField annotation is used to declare a GraphQL field.

Applies on: classes annotated with @Type or @ExtendType.

AttributeCompulsoryTypeDefinition
nameyesstringThe name of the field.
outputTypenostringForces the GraphQL output type of the field. Otherwise, return type is used.
phpTypenostringThe PHP type of the field (as you would write it in a Docblock)
descriptionnostringField description displayed in the GraphQL docs. If it's empty PHP doc comment of the method in the source class is used instead.
sourceNamenostringThe name of the property in the source class. If not set, the name will be used to get property value.
annotationsnoarray\<Annotations>A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here. Available in Doctrine annotations only (not available in the #SourceField PHP 8 attribute)

Note: outputType and phpType are mutually exclusive.

@MagicField

The @MagicField annotation is used to declare a GraphQL field that originates from a PHP magic property (using __get magic method).

Applies on: classes annotated with @Type or @ExtendType.

AttributeCompulsoryTypeDefinition
nameyesstringThe name of the field.
outputTypeno(*)stringThe GraphQL output type of the field.
phpTypeno(*)stringThe PHP type of the field (as you would write it in a Docblock)
descriptionnostringField description displayed in the GraphQL docs. If not set, no description will be shown.
sourceNamenostringThe name of the property in the source class. If not set, the name will be used to get property value.
annotationsnoarray\<Annotations>A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here. Available in Doctrine annotations only (not available in the #MagicField PHP 8 attribute)

(*) Note: outputType and phpType are mutually exclusive. You MUST provide one of them.

@Prefetch

Marks field parameter to be used for prefetching.

Applies on: parameters of methods annotated with @Query, @Mutation or @Field.

AttributeCompulsoryTypeDefinition
callablenocallableName of the prefetch method (in same class) or a full callable, either a static method or regular service from the container

@Logged

The @Logged annotation is used to declare a Query/Mutation/Field is only visible to logged users.

Applies on: methods or properties annotated with @Query, @Mutation or @Field.

This annotation allows no attributes.

The @Right annotation is used to declare a Query/Mutation/Field is only visible to users with a specific right.

Applies on: methods or properties annotated with @Query, @Mutation or @Field.

AttributeCompulsoryTypeDefinition
nameyesstringThe name of the right.

@FailWith

The @FailWith annotation is used to declare a default value to return in the user is not authorized to see a specific query/mutation/subscription/field (according to the @Logged and @Right annotations).

Applies on: methods or properties annotated with @Query, @Mutation or @Field and one of @Logged or @Right annotations.

AttributeCompulsoryTypeDefinition
valueyesmixedThe value to return if the user is not authorized.

@HideIfUnauthorized

This annotation only works when a Schema is used to handle exactly one use request. If you serve your GraphQL API from long-running standalone servers (like Laravel Octane, Swoole, RoadRunner etc) and share the same Schema instance between multiple requests, please avoid using @HideIfUnauthorized.

The @HideIfUnauthorized annotation is used to completely hide the query/mutation/subscription/field if the user is not authorized to access it (according to the @Logged and @Right annotations).

Applies on: methods or properties annotated with @Query, @Mutation or @Field and one of @Logged or @Right annotations.

@HideIfUnauthorized and @FailWith are mutually exclusive.

@InjectUser

Use the @InjectUser annotation to inject an instance of the current user logged in into a parameter of your query/mutation/subscription/field.

See the authentication and authorization page for more details.

Applies on: methods annotated with @Query, @Mutation or @Field.

AttributeCompulsoryTypeDefinition
foryesstringThe name of the PHP parameter

@Security

The @Security annotation can be used to check fin-grained access rights. It is very flexible: it allows you to pass an expression that can contains custom logic.

See the fine grained security page for more details.

Applies on: methods or properties annotated with @Query, @Mutation or @Field.

AttributeCompulsoryTypeDefinition
defaultyesstringThe security expression

@Factory

The @Factory annotation is used to declare a factory that turns GraphQL input types into objects.

Applies on: methods from classes in the "types" namespace.

AttributeCompulsoryTypeDefinition
namenostringThe name of the input type. If skipped, the name of class returned by the factory is used instead.
defaultnoboolIf true, this factory will be used by default for its PHP return type. If set to false, you must explicitly reference this factory using the @Parameter annotation.

@UseInputType

Used to override the GraphQL input type of a PHP parameter.

Applies on: methods annotated with @Query, @Mutation or @Field annotation.

AttributeCompulsoryTypeDefinition
foryesstringThe name of the PHP parameter
inputTypeyesstringThe GraphQL input type to force for this input field

@Decorate

The @Decorate annotation is used to extend/modify/decorate an input type declared with the @Factory annotation.

Applies on: methods from classes in the "types" namespace.

AttributeCompulsoryTypeDefinition
nameyesstringThe GraphQL input type name extended by this decorator.

@Autowire

Resolves a PHP parameter from the container.

Useful to inject services directly into @Field method arguments.

Applies on: methods annotated with @Query, @Mutation or @Field annotation.

AttributeCompulsoryTypeDefinition
foryesstringThe name of the PHP parameter
identifiernostringThe identifier of the service to fetch. This is optional. Please avoid using this attribute as this leads to a "service locator" anti-pattern.

@HideParameter

Removes an argument from the GraphQL schema.

AttributeCompulsoryTypeDefinition
foryesstringThe name of the PHP parameter to hide

@Cost

Sets complexity and multipliers on fields for automatic query complexity.

AttributeCompulsoryTypeDefinition
complexitynointComplexity for that field
multipliersnoarray\<string>Names of fields by value of which complexity will be multiplied
defaultMultipliernointDefault multiplier value if all multipliers are missing/null

@Validate

This annotation is only available in the GraphQLite Laravel package

Validates a user input in Laravel.

Applies on: methods annotated with @Query, @Mutation, @Field, @Factory or @Decorator annotation.

AttributeCompulsoryTypeDefinition
foryesstringThe name of the PHP parameter
rule*yesstringLaravel validation rules

Sample:

@Validate(for="$email", rule="email|unique:users")

@Assertion

Validates a user input.

The @Assertion annotation is available in the thecodingmachine/graphqlite-symfony-validator-bridge third party package. It is available out of the box if you use the Symfony bundle.

Applies on: methods annotated with @Query, @Mutation, @Field, @Factory or @Decorator annotation.

AttributeCompulsoryTypeDefinition
foryesstringThe name of the PHP parameter
constraint*yesannotationOne (or many) Symfony validation annotations.

@EnumType

Deprecated: Use PHP 8.1's native Enums instead with a @Type.

The @EnumType annotation is used to change the name of a "Enum" type. Note that if you do not want to change the name, the annotation is optionnal. Any object extending MyCLabs\Enum\Enum is automatically mapped to a GraphQL enum type.

Applies on: classes extending the MyCLabs\Enum\Enum base class.

AttributeCompulsoryTypeDefinition
namenostringThe name of the enum type (in the GraphQL schema)