diff --git a/README.md b/README.md index 4c8afbc..f0d885f 100644 --- a/README.md +++ b/README.md @@ -197,24 +197,28 @@ public function getStatus(): string } ``` -The type must be the PHP class implementing the GraphQL type (see -[limitations](#limitations)). The declaration can be defined as nullable and/or as -an array with one the following syntaxes (PHP style or GraphQL style): - -- `?MyType` -- `null|MyType` -- `MyType|null` -- `MyType[]` -- `?MyType[]` -- `null|MyType[]` -- `MyType[]|null` -- `Collection` +### Type syntax + +In most cases, the type must use the `::class` notation to specify the PHP class that is either implementing the GraphQL +type or the entity itself (see [limitations](#limitations)). Use string literals only if you must define it as nullable +and/or as an array. Never use the short name of an entity (it is only possible for user-defined custom types). + +Supported syntaxes (PHP style or GraphQL style) are: + +- `MyType::class` +- `'?Application\MyType'` +- `'null|Application\MyType'` +- `'Application\MyType|null'` +- `'Application\MyType[]'` +- `'?Application\MyType[]'` +- `'null|Application\MyType[]'` +- `'Application\MyType[]|null'` +- `'Collection'` This attribute can be used to override other things, such as `name`, `description` and `args`. - -#### Override arguments +### Override arguments Similarly to `#[API\Field]`, `#[API\Argument]` allows to override the type of argument if the PHP type hint is not enough: @@ -293,7 +297,6 @@ implementation configured according to your needs. In the following example, we because it offers useful concepts such as: invokables, aliases, factories and abstract factories. But any other PSR-11 container implementation could be used instead. - The keys should be the whatever you use to refer to the type in your model. Typically, that would be either the FQCN of a PHP class "native" type such as `DateTimeImmutable`, or the FQCN of a PHP class implementing the GraphQL type, or directly the GraphQL type name: @@ -431,7 +434,7 @@ possible to write custom filters and sorting. #### Custom filters -A custom filer must extend `AbstractOperator`. This will allow to define custom arguments for +A custom filer must extend `AbstractOperator`. This will allow to define custom arguments for the API, and then a method to build the DQL condition corresponding to the argument. This would also allow to filter on joined relations by carefully adding joins when necessary. @@ -472,12 +475,13 @@ use GraphQLTests\Doctrine\Blog\Sorting\UserName; #[API\Sorting([UserName::class])] final class Post extends AbstractModel ``` + ## Limitations ### Namespaces -The `use` statement is not supported. So types in attributes or doc blocks should -either be the FQCN or in the same namespace as the getter. +The `use` statement is not supported. So types in attributes or doc blocks must +be the FQCN, or the name of a user-defined custom types (but never the short name of an entity). ### Composite identifiers @@ -513,7 +517,6 @@ Those cases would probably end up being too complex to handle on the client-side instead to implement them as a custom filter on the server side, in order to hide complexity from the client and benefit from Doctrine's QueryBuilder full flexibility. - ### Sorting on join Out of the box, it is not possible to sort by a field from a joined relation. diff --git a/src/Attribute/AbstractAttribute.php b/src/Attribute/AbstractAttribute.php index 42b9513..a63a25b 100644 --- a/src/Attribute/AbstractAttribute.php +++ b/src/Attribute/AbstractAttribute.php @@ -23,7 +23,7 @@ abstract class AbstractAttribute implements ApiAttribute private bool $hasDefaultValue = false; /** - * @param null|string $type FQCN of PHP class implementing the GraphQL type + * @param null|string $type FQCN of PHP class implementing the GraphQL type, see README.md#type-syntax */ public function __construct( private ?string $name, diff --git a/src/Attribute/Argument.php b/src/Attribute/Argument.php index 5ccdc32..e327245 100644 --- a/src/Attribute/Argument.php +++ b/src/Attribute/Argument.php @@ -16,7 +16,7 @@ final class Argument extends AbstractAttribute { /** - * @param null|string $type FQCN of PHP class implementing the GraphQL type + * @param null|string $type FQCN of PHP class implementing the GraphQL type, see README.md#type-syntax */ public function __construct( ?string $type = null, diff --git a/src/Attribute/Field.php b/src/Attribute/Field.php index f27bec6..7e97da1 100644 --- a/src/Attribute/Field.php +++ b/src/Attribute/Field.php @@ -22,7 +22,7 @@ final class Field implements ApiAttribute /** * @param null|string $name Can be used to alias the field - * @param null|string $type FQCN of PHP class implementing the GraphQL type + * @param null|string $type FQCN of PHP class implementing the GraphQL type, see README.md#type-syntax */ public function __construct( public ?string $name = null, diff --git a/src/Attribute/FilterGroupCondition.php b/src/Attribute/FilterGroupCondition.php index f783259..5d296a1 100644 --- a/src/Attribute/FilterGroupCondition.php +++ b/src/Attribute/FilterGroupCondition.php @@ -16,7 +16,7 @@ final class FilterGroupCondition implements ApiAttribute { /** - * @param string $type FQCN of PHP class implementing the GraphQL type + * @param string $type FQCN of PHP class implementing the GraphQL type, see README.md#type-syntax */ public function __construct(public readonly string $type) { diff --git a/src/Attribute/Input.php b/src/Attribute/Input.php index 47002eb..e69a1cf 100644 --- a/src/Attribute/Input.php +++ b/src/Attribute/Input.php @@ -16,7 +16,7 @@ final class Input extends AbstractAttribute { /** - * @param null|string $type FQCN of PHP class implementing the GraphQL type + * @param null|string $type FQCN of PHP class implementing the GraphQL type, see README.md#type-syntax */ public function __construct( ?string $type = null,