Skip to content

Update index.md #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 5, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 28 additions & 30 deletions docs/annotations/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,47 +50,46 @@ If you use mutations, you need a `RootMutation` type as well.

## Annotations & type inheritance

As PHP classes naturally support inheritances (and so is the annotation reader), it doesn't make sense to allow classes to use the "inherits" option.
The type will inherits the annotations declared on parent classes properties and methods. The annotation on the class itself will not be herited.

As PHP classes naturally support inheritance (and so is the annotation reader), it doesn't make sense to allow classes to use the "inherits" option (as on types declared using YAML).
The type will inherit annotations declared on parent class properties and methods. The annotation on the class itself will not be inherited.

## Annotations, value & default resolver

In GraphQL, when a type's field is resolved, GraphQL expect by default a property (for object) or an index (for array) on the corresponding value returned for the type.
In GraphQL, when a type's field is resolved, GraphQL expects by default a property (for object) or a key (for array) on the corresponding value returned for the type.

For example, if I have a type like that :
For example, if you have a type like that :

```graphql
type Character {
name: String!
}
```

If the field `name` is queried, on a `Character` type instance, the default resolver will try to find a property or index on the related object (the `value`).
So, the value could be an object instance with a `name` property or an array with a `name` index.
If the field `name` is queried, on a `Character` type instance, the default resolver will try to find a property or key on the related variable (the `value`).
So, the `value` could be an object instance with a `name` property or an array with a `name` key.

Except for the root query and the root mutation, the value object is always returned by an other resolver.
For the Root query and the root mutation, the value object is the service with an id equals to the fully qualified name of the query/mutation class.
Except for the root Query and root Mutation types, the `value` variable is always returned by another resolver.
For the root Query and the Root Mutation types, the `value` variable is the service with an id that equals to the fully qualified name of the query/mutation class.

On a `@Field` or `@Query` or `@Mutation`, the following rules apply to guess a resolver when no `resolver` attribute is define on the annotation:
The following rules apply for `@Field`, `@Query` and `@Mutation` annotations to guess a resolver when no `resolver` attribute is defined:

- If the `@Field` apply on a property :
- If the `@Field` attribute `name` is define and not equals to the property name
- `@=value.[property name]` for a regular type
- `@=service([FQN class]).[property name]` for root query or root mutation
- If `@Field` is defined on a property :
- If `@Field`'s attribute `name` is defined and is not equal to the property name
- `@=value.<property name>` for a regular type
- `@=service(<FQCN>).<property name>` for root query or root mutation

- If the `@Field` attribute `name` is not define or equals the property
- If `@Field`'s attribute `name` is not defined or is not equal to the property name
- The default GraphQL resolver will be use for a regular type (no `resolve` configuration will be define).
- `@=service([FQN class]).[name]` for root query or root mutation
- `@=service(<FQCN>).<name>` for root query or root mutation

- If the `@Field` apply on a method :
- `@=call(value.[method name], args)` for a regular type
- `@=call(service([FQN class]).[method name], args)` for root query or mutation
- If `@Field` is defined on a method :
- `@=call(value.<method name>, args)` for a regular type
- `@=call(service(<FQCN>).<method name>, args)` for root query or mutation


## Annotations, Root Query & Root Mutation

If you define your Root Query, or Root Mutation as a class with annotations, it will allow you to define methods directly on the class itself to be expose as GraphQL.
If you define your root Query or root Mutation type as a class with annotations, it will allow you to define methods directly on the class itself to be exposed as GraphQL fields.
For example:

```php
Expand All @@ -109,8 +108,8 @@ class RootQuery {
}
```

In order for this to work, the Root Query class must be instanciated at some point if we want to be able to call methods on it.
To do so, the RootQuery class must be define as a service with the class fully qualified name as id.
In order for this to work, the `RootQuery` class must be instanciated at some point if you want to be able to call methods on it.
To do so, the `RootQuery` class must be defined as a service with its FQCN as id.
In the previous example, we need a service name `App\GraphQL\Query\RootQuery`. It works the same way for mutations.
In the previous example, the generated `resolve` config of the `something` field will be `@=service('App\GraphQL\Query\RootQuery').getSomething()`.

Expand All @@ -121,9 +120,9 @@ In the previous example, the generated `resolve` config of the `something` field

Based on other Doctrine annotations on your fields, the corresponding GraphQL type can sometimes be guessed automatically.

The type can be auto-guess from :
The type can be auto-guessed from the following annotations:

- `@ORM\Column` annotations, based on the `type` attribute
- `@ORM\Column`, based on the `type` attribute
- `@ORM\ManyToOne`, `@ORM\ManyToMany`, `@ORM\OneToOne`, `@ORM\OneToMany`, based on the `targetEntity` attribute. The target entity must be a GraphQL type itself to work.
- `@ORM\ManyToOne`, `@ORM\OneToOne` The generated type will also use the `@ORM\JoinColumn` annotation and his `nullable` attribute to generate either `Type` or `Type!`
- `@ORM\ManyToMany`, `@ORM\OneToMany` The generated type will always be not null, like `[Type]!` as you're supposed to initialize corresponding properties with an ArrayCollection
Expand All @@ -143,9 +142,9 @@ overblog_graphql:
```


### @Field type auto-guessing when applied on a method with a return type hint
### @Field type auto-guessing when defined on a method with a return type hint

The type of a `@Field` annotation can be auto-guessed if it applies on a method with a return type hint.
The type of the `@Field` annotation can be auto-guessed if it's defined on a method with a return type hint.

For example:

Expand All @@ -165,9 +164,9 @@ class MyType {

In this example, the type `String!` will be auto-guessed from the return type hint of the method.

### @Field arguments auto-guessing when applied on a method with type hinted parameters
### @Field arguments auto-guessing when defined on a method with type hinted parameters

The arguments of a `@Field` annotation can be auto-guessed if it applies on a method with type hinted arguments. Arguments without default value will be consided required.
The arguments of the `@Field` annotation can be auto-guessed if it's defined on a method with type hinted arguments. Arguments without default value will be consided required.

For example:

Expand All @@ -194,7 +193,7 @@ The GraphQL arguments will be auto-guessed as:

### Limitation of auto-guessing:

When trying to auto-guess type or args based on PHP Reflection (from type hinted method parameters or type hinted return value), there is a limitation.
When trying to auto-guess a type or args based on PHP Reflection (from type hinted method parameters or type hinted return value), there is a limitation.
As PHP type hinting doesn't support "array of instances of class", we cannot rely on it to guess the type when dealing with collection of objects.
In these case, you'll need to declare your types or arguments type manually.

Expand All @@ -206,4 +205,3 @@ For example, in PHP, a signature like this : `public function getArrayOfStrings(