Skip to content

Commit d6ac98d

Browse files
moufmoufmoufmouf
authored
Merge pull request #319 from moufmouf/versioning_4.1_doc
Versioning doc for 4.1 release
2 parents 21b924a + 2472801 commit d6ac98d

32 files changed

+5908
-0
lines changed

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
id: version-4.1-changelog
3+
title: Changelog
4+
sidebar_label: Changelog
5+
original_id: changelog
6+
---
7+
8+
## 4.1
9+
10+
Breaking change:
11+
12+
There is one breaking change introduced in the minor version (this was important to allow PHP 8 compatibility).
13+
14+
- The **ecodev/graphql-upload** package (used to get support for file uploads in GraphQL input types) is now a "recommended" dependency only.
15+
If you are using GraphQL file uploads, you need to add `ecodev/graphql-upload` to your `composer.json`.
16+
17+
New features:
18+
19+
- All annotations can now be accessed as PHP 8 attributes
20+
- The `@deprecated` annotation in your PHP code translates into deprecated fields in your GraphQL schema
21+
- You can now specify the GraphQL name of the Enum types you define
22+
- Added the possibility to inject pure Webonyx objects in GraphQLite schema
23+
24+
Minor changes:
25+
26+
- Migrated from `zend/diactoros` to `laminas/diactoros`
27+
- Making the annotation cache directory configurable
28+
29+
Miscellaneous:
30+
31+
- Migrated from Travis to Github actions
32+
33+
34+
## 4.0
35+
36+
This is a complete refactoring from 3.x. While existing annotations are kept compatible, the internals have completely
37+
changed.
38+
39+
New features:
40+
41+
- You can directly [annotate a PHP interface with `@Type` to make it a GraphQL interface](inheritance-interfaces.md#mapping-interfaces)
42+
- You can autowire services in resolvers, thanks to the new `@Autowire` annotation
43+
- Added [user input validation](validation.md) (using the Symfony Validator or the Laravel validator or a custom `@Assertion` annotation
44+
- Improved security handling:
45+
- Unauthorized access to fields can now generate GraphQL errors (rather that schema errors in GraphQLite v3)
46+
- 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).
47+
For instance, you can restrict access to the field "viewsCount" of the type `BlogPost` only for post that the current user wrote.
48+
- You can now inject the current logged user in any query / mutation / field using the `@InjectUser` annotation
49+
- Performance:
50+
- You can inject the [Webonyx query plan in a parameter from a resolver](query_plan.md)
51+
- You can use the [dataloader pattern to improve performance drastically via the "prefetchMethod" attribute](prefetch_method.md)
52+
- Customizable error handling has been added:
53+
- You can throw [GraphQL errors](error_handling.md) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLException`
54+
- You can specify the HTTP response code to send with a given error, and the errors "extensions" section
55+
- You can throw [many errors in one exception](error_handling.md#many-errors-for-one-exception) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLAggregateException`
56+
- 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)
57+
- You can force input types using `@UseInputType(for="$id", inputType="ID!")`
58+
- 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)
59+
- In a factory, you can [exclude some optional parameters from the GraphQL schema](input_types#ignoring-some-parameters)
60+
61+
62+
Many extension points have been added
63+
64+
- Added a "root type mapper" (useful to map scalar types to PHP types or to add custom annotations related to resolvers)
65+
- Added ["field middlewares"](field_middlewares.md) (useful to add middleware that modify the way GraphQL fields are handled)
66+
- Added a ["parameter type mapper"](argument_resolving.md) (useful to add customize parameter resolution or add custom annotations related to parameters)
67+
68+
New framework specific features:
69+
70+
Symfony:
71+
72+
- The Symfony bundle now provides a "login" and a "logout" mutation (and also a "me" query)
73+
74+
Laravel:
75+
76+
- [Native integration with the Laravel paginator](laravel-package-advanced.md#support-for-pagination) has been added
77+
78+
Internals:
79+
80+
- The `FieldsBuilder` class has been split in many different services (`FieldsBuilder`, `TypeHandler`, and a
81+
chain of *root type mappers*)
82+
- The `FieldsBuilderFactory` class has been completely removed.
83+
- 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
84+
than 3.x. Try it out!

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

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

0 commit comments

Comments
 (0)