Skip to content

Commit cdf9611

Browse files
oojacoboooojacoboo
committed
Added versioned docs to website
1 parent fd6679b commit cdf9611

File tree

81 files changed

+13187
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

81 files changed

+13187
-0
lines changed

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

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

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

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

0 commit comments

Comments
 (0)