diff --git a/website/docs/annotations-reference.md b/website/docs/annotations-reference.md index c0df8e6749..98c66c3943 100644 --- a/website/docs/annotations-reference.md +++ b/website/docs/annotations-reference.md @@ -7,56 +7,78 @@ sidebar_label: Attributes reference Note: all annotations are available in PHP 8 attribute format (`#[Query]`), support of Doctrine annotation format was dropped. See [Doctrine annotations vs PHP 8 attributes](doctrine-annotations-attributes.mdx) for more details. -## #[Query] +Attributes are listed in alphabetical order. -The `#[Query]` attribute is used to declare a GraphQL query. +## #[Assertion] -**Applies on**: controller methods. +[Validates a user input](validation.mdx). + +The `#[Assertion]` attribute 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]` attribute. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -name | *no* | string | The name of the query. If skipped, the name of the method is used instead. -[outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of a query. -description | *no* | string | Description of the query in the documentation. When omitted, the method's PHP docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. +*for* | *yes* | string | The name of the PHP parameter +*constraint* | *yes | annotation | One (or many) Symfony validation attributes. -## #[Mutation] +## #[Autowire] -The `#[Mutation]` attribute is used to declare a GraphQL mutation. +[Resolves a PHP parameter from the container](autowiring.mdx). -**Applies on**: controller methods. +Useful to inject services directly into `#[Field]` method arguments. + +**Applies on**: methods annotated with `#[Query]`, `#[Mutation]` or `#[Field]` attribute. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -name | *no* | string | The name of the mutation. If skipped, the name of the method is used instead. -[outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of a query. -description | *no* | string | Description of the mutation in the documentation. When omitted, the method's PHP docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. +*for* | *yes* | string | The name of the PHP parameter +*identifier* | *no* | string | The identifier of the service to fetch. This is optional. Please avoid using this attribute as this leads to a "service locator" anti-pattern. -## #[Subscription] +## #[Cost] -The `#[Subscription]` attribute is used to declare a GraphQL subscription. +Sets complexity and multipliers on fields for [automatic query complexity](operation-complexity.md#static-request-analysis). -**Applies on**: controller methods. +Attribute | Compulsory | Type | Definition +--------------------|------------|-----------------|----------------------------------------------------------------- +*complexity* | *no* | int | Complexity for that field +*multipliers* | *no* | array\ | Names of fields by value of which complexity will be multiplied +*defaultMultiplier* | *no* | int | Default multiplier value if all multipliers are missing/null + +## #[Decorate] + +The `#[Decorate]` attribute is used [to extend/modify/decorate an input type declared with the `#[Factory]` attribute](extend-input-type.mdx). + +**Applies on**: methods from classes in the "types" namespace. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -name | *no* | string | The name of the subscription. If skipped, the name of the method is used instead. -[outputType](custom-types.mdx) | *no* | string | Defines the GraphQL output type that will be sent for the subscription. -description | *no* | string | Description of the subscription in the documentation. When omitted, the method's PHP docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. +name | *yes* | string | The GraphQL input type name extended by this decorator. -## #[Type] +## #[EnumValue] -The `#[Type]` attribute 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] attribute](#input-annotation) directly on the input type or a [#[Factory] attribute](#factory-annotation) to make/return an input type. +The `#[EnumValue]` attribute attaches GraphQL schema metadata (description, deprecation reason) +to an individual case of a PHP 8.1+ native enum that is exposed as a GraphQL enum type. -**Applies on**: classes. +**Applies on**: cases of an enum annotated (directly or indirectly) with `#[Type]`. -Attribute | Compulsory | Type | Definition ----------------|------------|------|-------- -class | *no* | string | The 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](external-type-declaration.mdx). -name | *no* | string | The 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 -default | *no* | bool | Defaults to *true*. Whether the targeted PHP class should be mapped by default to this type. -external | *no* | bool | Whether this is an [external type declaration](external-type-declaration.mdx) 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. -description | *no* | string | Description of the GraphQL type in the schema documentation. When omitted, the class docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. +Attribute | Compulsory | Type | Definition +------------------|------------|--------|----------- +description | *no* | string | Description of the enum value. When omitted, the case's PHP docblock summary is used (see [schema descriptions](descriptions.md#enum-value-descriptions)). An explicit empty string `''` deliberately suppresses the docblock fallback. +deprecationReason | *no* | string | Deprecation reason published to the schema. When omitted, the `@deprecated` tag on the case docblock is used. An explicit empty string `''` deliberately clears any inherited `@deprecated` tag. + +```php +#[Type] +enum Genre: string +{ + #[EnumValue(description: 'Fiction works including novels and short stories.')] + case Fiction = 'fiction'; + + #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')] + case Poetry = 'poetry'; +} +``` ## #[ExtendType] @@ -72,18 +94,28 @@ description | *no* | string | Description of the extended GraphQL type. One and only one of "class" and "name" parameter can be passed at the same time. -## #[Input] +## #[Factory] -The `#[Input]` attribute is used to declare a GraphQL input type. +The `#[Factory]` attribute is used to declare a factory that turns GraphQL input types into objects. -**Applies on**: classes. +**Applies on**: methods from classes in the "types" namespace. -Attribute | Compulsory | Type | Definition ----------------|------------|--------|-------- -name | *no* | string | The 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. -description | *no* | string | Description of the input type in the documentation. If not passed, PHP doc comment is used. -default | *no* | bool | Name 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. -update | *no* | bool | Determines 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. +Attribute | Compulsory | Type | Definition +---------------|------------|------|-------- +name | *no* | string | The name of the input type. If skipped, the name of class returned by the factory is used instead. +default | *no* | bool | If `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]` attribute](input-types.mdx#declaring-several-input-types-for-the-same-php-class). +description | *no* | string | Description of the GraphQL input type produced by this factory. When omitted, the factory method's docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. + +## #[FailWith] + +The `#[FailWith]` attribute 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]` attributes). + +**Applies on**: methods or properties annotated with `#[Query]`, `#[Mutation]` or `#[Field]` and one of `#[Logged]` or `#[Right]` attributes. + +Attribute | Compulsory | Type | Definition +---------------|------------|------|-------- +value | *yes* | mixed | The value to return if the user is not authorized. ## #[Field] @@ -101,22 +133,60 @@ description | *no* | string | Field description d [outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of a query. [inputType](input-types.mdx) | *no* | string | Forces the GraphQL input type of a query. -## #[SourceField] +## #[HideIfUnauthorized] -The `#[SourceField]` attribute is used to declare a GraphQL field. +
This attribute 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].
-**Applies on**: classes annotated with `#[Type]` or `#[ExtendType]`. +The `#[HideIfUnauthorized]` attribute 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]` attributes). + +**Applies on**: methods or properties annotated with `#[Query]`, `#[Mutation]` or `#[Field]` and one of `#[Logged]` or `#[Right]` attributes. + +`#[HideIfUnauthorized]` and `#[FailWith]` are mutually exclusive. + +## #[HideParameter] + +Removes [an argument from the GraphQL schema](input-types.mdx#ignoring-some-parameters). Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -name | *yes* | string | The name of the field. -[outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of the field. Otherwise, return type is used. -phpType | *no* | string | The PHP type of the field (as you would write it in a Docblock) -description | *no* | string | Field description displayed in the GraphQL docs. If it's empty PHP doc comment of the method in the source class is used instead. -sourceName | *no* | string | The name of the property in the source class. If not set, the `name` will be used to get property value. -annotations | *no* | array\ | A set of annotations that apply to this field. You would typically used a "#[Logged]" or "#[Right]" attribute as class here. +*for* | *yes* | string | The name of the PHP parameter to hide -**Note**: `outputType` and `phpType` are mutually exclusive. +## #[InjectUser] + +Use the `#[InjectUser]` attribute 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](authentication-authorization.mdx) for more details. + +**Applies on**: methods annotated with `#[Query]`, `#[Mutation]` or `#[Field]`. + +Attribute | Compulsory | Type | Definition +---------------|------------|--------|-------- +*for* | *yes* | string | The name of the PHP parameter + +## #[Input] + +The `#[Input]` attribute is used to declare a GraphQL input type. + +**Applies on**: classes. + +Attribute | Compulsory | Type | Definition +---------------|------------|--------|-------- +name | *no* | string | The 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. +description | *no* | string | Description of the input type in the documentation. If not passed, PHP doc comment is used. +default | *no* | bool | Name 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. +update | *no* | bool | Determines 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. + +## #[Logged] + +The `#[Logged]` attribute 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 attribute allows no arguments. ## #[MagicField] @@ -135,6 +205,18 @@ annotations | *no* | array\ | A set of annotations that (*) **Note**: `outputType` and `phpType` are mutually exclusive. You MUST provide one of them. +## #[Mutation] + +The `#[Mutation]` attribute is used to declare a GraphQL mutation. + +**Applies on**: controller methods. + +Attribute | Compulsory | Type | Definition +---------------|------------|------|-------- +name | *no* | string | The name of the mutation. If skipped, the name of the method is used instead. +[outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of a query. +description | *no* | string | Description of the mutation in the documentation. When omitted, the method's PHP docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. + ## #[Prefetch] Marks field parameter to be used for [prefetching](prefetch-method.mdx). @@ -145,14 +227,17 @@ Attribute | Compulsory | Type | Definition ------------------------------|------------|----------|-------- callable | *no* | callable | Name of the prefetch method (in same class) or a full callable, either a static method or regular service from the container +## #[Query] -## #[Logged] - -The `#[Logged]` attribute is used to declare a Query/Mutation/Field is only visible to logged users. +The `#[Query]` attribute is used to declare a GraphQL query. -**Applies on**: methods or properties annotated with `#[Query]`, `#[Mutation]` or `#[Field]`. +**Applies on**: controller methods. -This attribute allows no arguments. +Attribute | Compulsory | Type | Definition +---------------|------------|------|-------- +name | *no* | string | The name of the query. If skipped, the name of the method is used instead. +[outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of a query. +description | *no* | string | Description of the query in the documentation. When omitted, the method's PHP docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. ## #[Right] @@ -164,43 +249,6 @@ Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- name | *yes* | string | The name of the right. -## #[FailWith] - -The `#[FailWith]` attribute 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]` attributes). - -**Applies on**: methods or properties annotated with `#[Query]`, `#[Mutation]` or `#[Field]` and one of `#[Logged]` or `#[Right]` attributes. - -Attribute | Compulsory | Type | Definition ----------------|------------|------|-------- -value | *yes* | mixed | The value to return if the user is not authorized. - -## #[HideIfUnauthorized] - -
This attribute 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]` attribute 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]` attributes). - -**Applies on**: methods or properties annotated with `#[Query]`, `#[Mutation]` or `#[Field]` and one of `#[Logged]` or `#[Right]` attributes. - -`#[HideIfUnauthorized]` and `#[FailWith]` are mutually exclusive. - -## #[InjectUser] - -Use the `#[InjectUser]` attribute 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](authentication-authorization.mdx) for more details. - -**Applies on**: methods annotated with `#[Query]`, `#[Mutation]` or `#[Field]`. - -Attribute | Compulsory | Type | Definition ----------------|------------|--------|-------- -*for* | *yes* | string | The name of the PHP parameter - ## #[Security] The `#[Security]` attribute can be used to check fin-grained access rights. @@ -214,69 +262,60 @@ Attribute | Compulsory | Type | Definition ---------------|------------|--------|-------- *default* | *yes* | string | The security expression -## #[Factory] +## #[SourceField] -The `#[Factory]` attribute is used to declare a factory that turns GraphQL input types into objects. +The `#[SourceField]` attribute is used to declare a GraphQL field. -**Applies on**: methods from classes in the "types" namespace. +**Applies on**: classes annotated with `#[Type]` or `#[ExtendType]`. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -name | *no* | string | The name of the input type. If skipped, the name of class returned by the factory is used instead. -default | *no* | bool | If `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]` attribute](input-types.mdx#declaring-several-input-types-for-the-same-php-class). -description | *no* | string | Description of the GraphQL input type produced by this factory. When omitted, the factory method's docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. +name | *yes* | string | The name of the field. +[outputType](custom-types.mdx) | *no* | string | Forces the GraphQL output type of the field. Otherwise, return type is used. +phpType | *no* | string | The PHP type of the field (as you would write it in a Docblock) +description | *no* | string | Field description displayed in the GraphQL docs. If it's empty PHP doc comment of the method in the source class is used instead. +sourceName | *no* | string | The name of the property in the source class. If not set, the `name` will be used to get property value. +annotations | *no* | array\ | A set of annotations that apply to this field. You would typically used a "#[Logged]" or "#[Right]" attribute as class here. -## #[UseInputType] +**Note**: `outputType` and `phpType` are mutually exclusive. -Used to override the GraphQL input type of a PHP parameter. +## #[Subscription] -**Applies on**: methods annotated with `#[Query]`, `#[Mutation]` or `#[Field]` attribute. +The `#[Subscription]` attribute is used to declare a GraphQL subscription. + +**Applies on**: controller methods. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -*for* | *yes* | string | The name of the PHP parameter -*inputType* | *yes* | string | The GraphQL input type to force for this input field +name | *no* | string | The name of the subscription. If skipped, the name of the method is used instead. +[outputType](custom-types.mdx) | *no* | string | Defines the GraphQL output type that will be sent for the subscription. +description | *no* | string | Description of the subscription in the documentation. When omitted, the method's PHP docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. -## #[Decorate] +## #[Type] -The `#[Decorate]` attribute is used [to extend/modify/decorate an input type declared with the `#[Factory]` attribute](extend-input-type.mdx). +The `#[Type]` attribute 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] attribute](#input-annotation) directly on the input type or a [#[Factory] attribute](#factory-annotation) to make/return an input type. -**Applies on**: methods from classes in the "types" namespace. +**Applies on**: classes. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- -name | *yes* | string | The GraphQL input type name extended by this decorator. - -## #[Autowire] +class | *no* | string | The 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](external-type-declaration.mdx). +name | *no* | string | The 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 +default | *no* | bool | Defaults to *true*. Whether the targeted PHP class should be mapped by default to this type. +external | *no* | bool | Whether this is an [external type declaration](external-type-declaration.mdx) 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. +description | *no* | string | Description of the GraphQL type in the schema documentation. When omitted, the class docblock summary is used (see [schema descriptions](descriptions.md)). An explicit empty string `''` deliberately suppresses the docblock fallback. -[Resolves a PHP parameter from the container](autowiring.mdx). +## #[UseInputType] -Useful to inject services directly into `#[Field]` method arguments. +Used to override the GraphQL input type of a PHP parameter. **Applies on**: methods annotated with `#[Query]`, `#[Mutation]` or `#[Field]` attribute. Attribute | Compulsory | Type | Definition ---------------|------------|------|-------- *for* | *yes* | string | The name of the PHP parameter -*identifier* | *no* | string | The 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](input-types.mdx#ignoring-some-parameters). - -Attribute | Compulsory | Type | Definition ----------------|------------|------|-------- -*for* | *yes* | string | The name of the PHP parameter to hide - -## #[Cost] - -Sets complexity and multipliers on fields for [automatic query complexity](operation-complexity.md#static-request-analysis). - -Attribute | Compulsory | Type | Definition ---------------------|------------|-----------------|----------------------------------------------------------------- -*complexity* | *no* | int | Complexity for that field -*multipliers* | *no* | array\ | Names of fields by value of which complexity will be multiplied -*defaultMultiplier* | *no* | int | Default multiplier value if all multipliers are missing/null +*inputType* | *yes* | string | The GraphQL input type to force for this input field ## #[Validate] @@ -296,41 +335,3 @@ Sample: ```php #[Validate(for: "$email", rule: "email|unique:users")] ``` - -## #[Assertion] - -[Validates a user input](validation.mdx). - -The `#[Assertion]` attribute 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]` attribute. - -Attribute | Compulsory | Type | Definition ----------------|------------|------|-------- -*for* | *yes* | string | The name of the PHP parameter -*constraint* | *yes | annotation | One (or many) Symfony validation attributes. - -## #[EnumValue] - -The `#[EnumValue]` attribute attaches GraphQL schema metadata (description, deprecation reason) -to an individual case of a PHP 8.1+ native enum that is exposed as a GraphQL enum type. - -**Applies on**: cases of an enum annotated (directly or indirectly) with `#[Type]`. - -Attribute | Compulsory | Type | Definition -------------------|------------|--------|----------- -description | *no* | string | Description of the enum value. When omitted, the case's PHP docblock summary is used (see [schema descriptions](descriptions.md#enum-value-descriptions)). An explicit empty string `''` deliberately suppresses the docblock fallback. -deprecationReason | *no* | string | Deprecation reason published to the schema. When omitted, the `@deprecated` tag on the case docblock is used. An explicit empty string `''` deliberately clears any inherited `@deprecated` tag. - -```php -#[Type] -enum Genre: string -{ - #[EnumValue(description: 'Fiction works including novels and short stories.')] - case Fiction = 'fiction'; - - #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')] - case Poetry = 'poetry'; -} -```