Update documentation: introduced options type and isRequired

jerowork · Jan 3, 2025 · 1ed9d21 · 1ed9d21
1 parent 86c3d47
commit 1ed9d21
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 20 deletions.
diff --git a/docs/todo.md b/docs/todo.md
@@ -2,7 +2,7 @@
 This library is still work in progress, and misses some valuable features:
 
 - Introduction of `#[Deprecated]` attribute
-- Overwrite type via attributes
+- ~~Overwrite type via attributes~~
 - Allow simple lists (array type)
 - Connection, edge, nodes (see https://relay.dev/graphql/connections.htm)
 - Make AST serializable (cacheable)

diff --git a/docs/usage.md b/docs/usage.md
@@ -1,6 +1,7 @@
 # Usage
 
 The following attributes can be used:
+
 - `#[Mutation]`
 - `#[Query]`
 - `#[InputType]`
@@ -34,6 +35,7 @@ final readonly YourQuery
 ```
 
 ### Automatic schema creation
+
 *GraphQL Attribute Schema* will read the available public method's signature: input arguments and output type. These
 will be automatically configured in the schema (this can be overwritten by using `#[Arg]`, see [Arg](#arg) section).
 
@@ -45,6 +47,7 @@ Also, the name of the mutation or query will be automatically read from the clas
 options).
 
 ### Requirements
+
 Mutations and queries:
 
 - must be in the namespace as defined at `Parser` creation (
@@ -57,13 +60,16 @@ Mutations and queries:
 
 Both `#[Mutation]` and `#[Query]` attribute can be configured:
 
-| Option      | Description                                                              |
-|-------------|--------------------------------------------------------------------------|
-| name        | Set custom name of mutation or query (instead of based on class)         |
-| description | Set description of the mutation or query, readable in the GraphQL schema |
+| Option      | Description                                                                   |
+|-------------|-------------------------------------------------------------------------------|
+| name        | Set custom name of mutation or query (instead of based on class)              |
+| description | Set description of the mutation or query, readable in the GraphQL schema      |
+| type        | Set custom return type (can be either a `#[Type]` FQCN or `ScalarType` (enum) |
+| isRequired  | When a custom type is set, isRequired should be set as well                   |
 
 ## InputType
-Input types can be defined with `#[InputType]`. 
+
+Input types can be defined with `#[InputType]`.
 In order to configure your class as input type, just add this attribute on class level:
 
 ```php
@@ -87,8 +93,10 @@ final readonly class YourInputType
 ```
 
 ### Automatic schema creation
-*GraphQL Attribute Schema* will read the `__construct` signature: input arguments. 
-Any input argument with a defined `#[Field]` will be automatically configured in the schema (this can be overwritten, see [Field](#field) section).
+
+*GraphQL Attribute Schema* will read the `__construct` signature: input arguments.
+Any input argument with a defined `#[Field]` will be automatically configured in the schema (this can be overwritten,
+see [Field](#field) section).
 
 Input can be both scalars or objects.
 When using objects, make sure these are defined as well with `#[InputType]` or `#[Enum]`.
@@ -106,6 +114,7 @@ options).
 | description | Set description of the input type, readable in the GraphQL schema |
 
 ## Type
+
 Types can be defined with `#[Type]`.
 In order to configure your class as type, just add this attribute on class level:
 
@@ -136,12 +145,16 @@ final readonly class YourType
 ```
 
 ### Automatic schema creation
+
 *GraphQL Attribute Schema* will both read the `__construct` signature: input arguments, as well as read all methods.
 
-Any input argument with a defined `#[Field]` will be automatically configured in the schema (this can be overwritten, see [Field](#field) section).
+Any input argument with a defined `#[Field]` will be automatically configured in the schema (this can be overwritten,
+see [Field](#field) section).
 
-Any method with a defined `#[Field]` will be automatically configured in the schema (this can be overwritten, see [Field](#field) section).
-The return type is seen as field type, any method input arguments are seen as filter arguments (this can be overwritten by using `#[Arg]`, see [Arg](#arg) section)..
+Any method with a defined `#[Field]` will be automatically configured in the schema (this can be overwritten,
+see [Field](#field) section).
+The return type is seen as field type, any method input arguments are seen as filter arguments (this can be overwritten
+by using `#[Arg]`, see [Arg](#arg) section)..
 
 Input can be both scalars or objects.
 When using objects, make sure these are defined as well with `#[InputType]` or `#[Enum]`.
@@ -159,6 +172,7 @@ options).
 | description | Set description of the type, readable in the GraphQL schema |
 
 ## Enum
+
 Enums can be defined with `#[Enum]`.
 In order to configure your enum class as enum, just add this attribute on class level:
 
@@ -173,14 +187,17 @@ enum YourEnumType: string
     case Baz = 'BAZ';
 }
 ```
+
 ### Automatic schema creation
+
 *GraphQL Attribute Schema* will read the enum signature.
 
 The values for the enum will be automatically read from the PHP `enum`; it uses the string version.
 
 The name of the enum will be automatically read from the class name (this can be overwritten, see options).
 
 ### Requirements
+
 Enums:
 
 - must be of the PHP native `enum` type (no classes with public constants)
@@ -196,6 +213,7 @@ Enums:
 | description | Set description of the enum, readable in the GraphQL schema |
 
 ## Field
+
 In `#[Type]` and `#[InputType]`, to define fields, the `#[Field]` attribute can be used.
 In order to configure any fields this can be set on constructor property (for `#[InputType]` or `#[Type]`) or
 on method (for `#[Type]` only).
@@ -243,14 +261,17 @@ final readonly class YourInputType
 
 `#[Field]` attribute can be configured:
 
-| Option      | Description                                                  |
-|-------------|--------------------------------------------------------------|
-| name        | Set custom name of field (instead of based on class)         |
-| description | Set description of the field, readable in the GraphQL schema |
+| Option      | Description                                                                            |
+|-------------|----------------------------------------------------------------------------------------|
+| name        | Set custom name of field (instead of based on class)                                   |
+| description | Set description of the field, readable in the GraphQL schema                           |
+| type        | Set custom type (can be either a `#[Type]`, `#[InputType]` FQCN or `ScalarType` (enum) |
+| isRequired  | When a custom type is set, isRequired should be set as well                            |
 
 ## Arg
+
 For `#[Mutation]`, `#[Query]` and `#[Type]` methods defined with `#[Field]`, input arguments are read
-automatically from the signature. 
+automatically from the signature.
 
 However, to overwrite e.g. name, `#[Arg]` can be used.
 
@@ -299,7 +320,9 @@ final readonly class YourType
 
 `#[Arg]` attribute can be configured:
 
-| Option      | Description                                                     |
-|-------------|-----------------------------------------------------------------|
-| name        | Set custom name of argument (instead of based on class)         |
-| description | Set description of the argument, readable in the GraphQL schema |
+| Option      | Description                                                            |
+|-------------|------------------------------------------------------------------------|
+| name        | Set custom name of argument (instead of based on class)                |
+| description | Set description of the argument, readable in the GraphQL schema        |
+| type        | Set custom type (can be either a `#[Type]` FQCN or `ScalarType` (enum) |
+| isRequired  | When a custom type is set, isRequired should be set as well            |