Skip to content

Commit 9aba230

Browse files
moufmoufmoufmouf
authored
Merge pull request #214 from moufmouf/versioning_docs_4.0
Versioning docs for the 4.0
2 parents c37808e + 31b2dc1 commit 9aba230

36 files changed

+4602
-1
lines changed

‎docs/other_frameworks.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ In order to bootstrap GraphQLite, you will need:
2424
Additionally, you will have to route the HTTP requests to the underlying GraphQL library.
2525

2626
GraphQLite relies on the [webonyx/graphql-php](http://webonyx.github.io/graphql-php/) library internally.
27-
This library plays well with PSR-7 requests and we also provide a [PSR-15 middleware](https://github.com/phps-cans/psr7-middleware-graphql).
27+
This library plays well with PSR-7 requests and we also provide a [PSR-15 middleware](#psr-15-middleware).
2828

2929
## Integration
3030

‎website/versioned_docs/version-4.0/CHANGELOG.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: version-4.0-changelog
3+
title: Changelog
4+
sidebar_label: Changelog
5+
original_id: changelog
6+
---
7+
8+
## 4.0
9+
10+
This is a complete refactoring from 3.x. While existing annotations are kept compatible, the internals have completely
11+
changed.
12+
13+
New features:
14+
15+
- You can directly [annotate a PHP interface with `@Type` to make it a GraphQL interface](inheritance-interfaces.md#mapping-interfaces)
16+
- You can autowire services in resolvers, thanks to the new `@Autowire` annotation
17+
- Added [user input validation](validation.md) (using the Symfony Validator or the Laravel validator or a custom `@Assertion` annotation
18+
- Improved security handling:
19+
- Unauthorized access to fields can now generate GraphQL errors (rather that schema errors in GraphQLite v3)
20+
- Added fine-grained security using the `@Security` annotation. A field can now be [marked accessible or not depending on the context](fine-grained-security.md).
21+
For instance, you can restrict access to the field "viewsCount" of the type `BlogPost` only for post that the current user wrote.
22+
- You can now inject the current logged user in any query / mutation / field using the `@InjectUser` annotation
23+
- Performance:
24+
- You can inject the [Webonyx query plan in a parameter from a resolver](query_plan.md)
25+
- You can use the [dataloader pattern to improve performance drastically via the "prefetchMethod" attribute](prefetch_method.md)
26+
- Customizable error handling has been added:
27+
- You can throw [GraphQL errors](error_handling.md) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLException`
28+
- You can specify the HTTP response code to send with a given error, and the errors "extensions" section
29+
- You can throw [many errors in one exception](error_handling.md#many-errors-for-one-exception) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLAggregateException`
30+
- You can map [a given PHP class to several PHP input types](input_types.md#declaring-several-input-types-for-the-same-php-class) (a PHP class can have several `@Factory` annotations)
31+
- You can force input types using `@UseInputType(for="$id", inputType="ID!")`
32+
- You can extend an input types (just like you could extend an output type in v3) using [the new `@Decorate` annotation](extend_input_type.md)
33+
- In a factory, you can [exclude some optional parameters from the GraphQL schema](input_types#ignoring-some-parameters)
34+
35+
36+
Many extension points have been added
37+
38+
- Added a "root type mapper" (useful to map scalar types to PHP types or to add custom annotations related to resolvers)
39+
- Added ["field middlewares"](field_middlewares.md) (useful to add middleware that modify the way GraphQL fields are handled)
40+
- Added a ["parameter type mapper"](argument_resolving.md) (useful to add customize parameter resolution or add custom annotations related to parameters)
41+
42+
New framework specific features:
43+
44+
Symfony:
45+
46+
- The Symfony bundle now provides a "login" and a "logout" mutation (and also a "me" query)
47+
48+
Laravel:
49+
50+
- [Native integration with the Laravel paginator](laravel-package-advanced.md#support-for-pagination) has been added
51+
52+
Internals:
53+
54+
- The `FieldsBuilder` class has been split in many different services (`FieldsBuilder`, `TypeHandler`, and a
55+
chain of *root type mappers*)
56+
- The `FieldsBuilderFactory` class has been completely removed.
57+
- Overall, there is not much in common internally between 4.x and 3.x. 4.x is much more flexible with many more hook points
58+
than 3.x. Try it out!

‎website/versioned_docs/version-4.0/annotations_reference.md

+244
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
id: version-4.0-annotations_reference
3+
title: Annotations reference
4+
sidebar_label: Annotations reference
5+
original_id: annotations_reference
6+
---
7+
8+
## @Query annotation
9+
10+
The `@Query` annotation is used to declare a GraphQL query.
11+
12+
**Applies on**: controller methods.
13+
14+
Attribute | Compulsory | Type | Definition
15+
---------------|------------|------|--------
16+
name | *no* | string | The name of the query. If skipped, the name of the method is used instead.
17+
[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of a query.
18+
19+
## @Mutation annotation
20+
21+
The `@Mutation` annotation is used to declare a GraphQL mutation.
22+
23+
**Applies on**: controller methods.
24+
25+
Attribute | Compulsory | Type | Definition
26+
---------------|------------|------|--------
27+
name | *no* | string | The name of the mutation. If skipped, the name of the method is used instead.
28+
[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of a query.
29+
30+
## @Type annotation
31+
32+
The `@Type` annotation is used to declare a GraphQL object type.
33+
34+
**Applies on**: classes.
35+
36+
Attribute | Compulsory | Type | Definition
37+
---------------|------------|------|--------
38+
class | *no* | string | The targeted class. If no class is passed, the type applies to the current class. The current class is assumed to be an entity. If the "class" attribute is passed, [the class annotated with `@Type` is a service](external_type_declaration.md).
39+
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
40+
default | *no* | bool | Defaults to *true*. Whether the targeted PHP class should be mapped by default to this type.
41+
external | *no* | bool | Whether this is an [external type declaration](external_type_declaration.md) 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.
42+
43+
## @ExtendType annotation
44+
45+
The `@ExtendType` annotation is used to add fields to an existing GraphQL object type.
46+
47+
**Applies on**: classes.
48+
49+
Attribute | Compulsory | Type | Definition
50+
---------------|------------|------|--------
51+
class | see below | string | The targeted class. [The class annotated with `@ExtendType` is a service](extend_type.md).
52+
name | see below | string | The targeted GraphQL output type.
53+
54+
One and only one of "class" and "name" parameter can be passed at the same time.
55+
56+
## @Field annotation
57+
58+
The `@Field` annotation is used to declare a GraphQL field.
59+
60+
**Applies on**: methods of classes annotated with `@Type` or `@ExtendType`.
61+
62+
Attribute | Compulsory | Type | Definition
63+
---------------|------------|------|--------
64+
name | *no* | string | The name of the field. If skipped, the name of the method is used instead.
65+
[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of a query.
66+
67+
## @SourceField annotation
68+
69+
The `@SourceField` annotation is used to declare a GraphQL field.
70+
71+
**Applies on**: classes annotated with `@Type` or `@ExtendType`.
72+
73+
Attribute | Compulsory | Type | Definition
74+
---------------|------------|------|--------
75+
name | *yes* | string | The name of the field.
76+
[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of the field. Otherwise, return type is used.
77+
phpType | *no* | string | The PHP type of the field (as you would write it in a Docblock)
78+
annotations | *no* | array<Annotations> | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here.
79+
80+
**Note**: `outputType` and `phpType` are mutually exclusive.
81+
82+
## @MagicField annotation
83+
84+
The `@MagicField` annotation is used to declare a GraphQL field that originates from a PHP magic property (using `__get` magic method).
85+
86+
**Applies on**: classes annotated with `@Type` or `@ExtendType`.
87+
88+
Attribute | Compulsory | Type | Definition
89+
---------------|------------|------|--------
90+
name | *yes* | string | The name of the field.
91+
[outputType](custom_output_types.md) | *no*(*) | string | The GraphQL output type of the field.
92+
phpType | *no*(*) | string | The PHP type of the field (as you would write it in a Docblock)
93+
annotations | *no* | array<Annotations> | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here.
94+
95+
(*) **Note**: `outputType` and `phpType` are mutually exclusive. You MUST provide one of them.
96+
97+
## @Logged annotation
98+
99+
The `@Logged` annotation is used to declare a Query/Mutation/Field is only visible to logged users.
100+
101+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
102+
103+
This annotation allows no attributes.
104+
105+
## @Right annotation
106+
107+
The `@Right` annotation is used to declare a Query/Mutation/Field is only visible to users with a specific right.
108+
109+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
110+
111+
Attribute | Compulsory | Type | Definition
112+
---------------|------------|------|--------
113+
name | *yes* | string | The name of the right.
114+
115+
## @FailWith annotation
116+
117+
The `@FailWith` annotation is used to declare a default value to return in the user is not authorized to see a specific
118+
query / mutation / field (according to the `@Logged` and `@Right` annotations).
119+
120+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` and one of `@Logged` or `@Right` annotations.
121+
122+
Attribute | Compulsory | Type | Definition
123+
---------------|------------|------|--------
124+
*default* | *yes* | mixed | The value to return if the user is not authorized.
125+
126+
## @HideIfUnauthorized annotation
127+
128+
The `@HideIfUnauthorized` annotation is used to completely hide the query / mutation / field if the user is not authorized
129+
to access it (according to the `@Logged` and `@Right` annotations).
130+
131+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` and one of `@Logged` or `@Right` annotations.
132+
133+
`@HideIfUnauthorized` and `@FailWith` are mutually exclusive.
134+
135+
## @InjectUser annotation
136+
137+
Use the `@InjectUser` annotation to inject an instance of the current user logged in into a parameter of your
138+
query / mutation / field.
139+
140+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
141+
142+
Attribute | Compulsory | Type | Definition
143+
---------------|------------|--------|--------
144+
*for* | *yes* | string | The name of the PHP parameter
145+
146+
## @Security annotation
147+
148+
The `@Security` annotation can be used to check fin-grained access rights.
149+
It is very flexible: it allows you to pass an expression that can contains custom logic.
150+
151+
See [the fine grained security page](fine-grained-security.md) for more details.
152+
153+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
154+
155+
Attribute | Compulsory | Type | Definition
156+
---------------|------------|--------|--------
157+
*default* | *yes* | string | The security expression
158+
159+
## @Factory annotation
160+
161+
The `@Factory` annotation is used to declare a factory that turns GraphQL input types into objects.
162+
163+
**Applies on**: methods from classes in the "types" namespace.
164+
165+
Attribute | Compulsory | Type | Definition
166+
---------------|------------|------|--------
167+
name | *no* | string | The name of the input type. If skipped, the name of class returned by the factory is used instead.
168+
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` annotation](http://localhost:3000/docs/input-types#declaring-several-input-types-for-the-same-php-class).
169+
170+
## @UseInputType annotation
171+
172+
Used to override the GraphQL input type of a PHP parameter.
173+
174+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` annotation.
175+
176+
Attribute | Compulsory | Type | Definition
177+
---------------|------------|------|--------
178+
*for* | *yes* | string | The name of the PHP parameter
179+
*inputType* | *yes* | string | The GraphQL input type to force for this input field
180+
181+
## @Decorate annotation
182+
183+
The `@Decorate` annotation is used [to extend/modify/decorate an input type declared with the `@Factory` annotation](extend_input_type.md).
184+
185+
**Applies on**: methods from classes in the "types" namespace.
186+
187+
Attribute | Compulsory | Type | Definition
188+
---------------|------------|------|--------
189+
name | *yes* | string | The GraphQL input type name extended by this decorator.
190+
191+
## @Autowire annotation
192+
193+
[Resolves a PHP parameter from the container](autowiring.md).
194+
195+
Useful to inject services directly into `@Field` method arguments.
196+
197+
**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` annotation.
198+
199+
Attribute | Compulsory | Type | Definition
200+
---------------|------------|------|--------
201+
*for* | *yes* | string | The name of the PHP parameter
202+
*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.
203+
204+
## @HideParameter annotation
205+
206+
Removes [an argument from the GraphQL schema](input_types.md#ignoring_some_parameters).
207+
208+
Attribute | Compulsory | Type | Definition
209+
---------------|------------|------|--------
210+
*for* | *yes* | string | The name of the PHP parameter to hide
211+
212+
213+
## @Validate annotation
214+
215+
<div class="alert alert-info">This annotation is only available in the GraphQLite Laravel package</div>
216+
217+
[Validates a user input in Laravel](laravel-package-advanced.md).
218+
219+
**Applies on**: methods annotated with `@Query`, `@Mutation`, `@Field`, `@Factory` or `@Decorator` annotation.
220+
221+
Attribute | Compulsory | Type | Definition
222+
---------------|------------|------|--------
223+
*for* | *yes* | string | The name of the PHP parameter
224+
*rule* | *yes | string | Laravel validation rules
225+
226+
Sample:
227+
228+
```
229+
@Validate(for="$email", rule="email|unique:users")
230+
```
231+
232+
## @Assertion annotation
233+
234+
[Validates a user input](validation.md).
235+
236+
The `@Assertion` annotation is available in the *thecodingmachine/graphqlite-symfony-validator-bridge* third party package.
237+
It is available out of the box if you use the Symfony bundle.
238+
239+
**Applies on**: methods annotated with `@Query`, `@Mutation`, `@Field`, `@Factory` or `@Decorator` annotation.
240+
241+
Attribute | Compulsory | Type | Definition
242+
---------------|------------|------|--------
243+
*for* | *yes* | string | The name of the PHP parameter
244+
*constraint* | *yes | annotation | One (or many) Symfony validation annotations.

0 commit comments

Comments
 (0)