Download the PHP package lastdragon-ru/lara-asp-graphql without Composer

(Laravel) GraphQL Extensions for Lighthouse

This package provides highly powerful @searchBy, @sortBy, @stream directives for lighthouse-php. The @searchBy directive provides basic conditions like =, >, <, etc, relations, not (<condition>), enums, and custom operators support. All are strictly typed so you no need to use Mixed type anymore. The @sortBy is not only about standard sorting by columns but also allows use relations. 😎

[include:exec]: <../../dev/artisan lara-asp-documentator:requirements>

Requirements

Installation

Configuration

Config can be used, for example, to customize supported operators for each type. Before this, you need to publish it via the following command, and then you can edit config/lara-asp-graphql.php.

Directives

@searchBy

Probably the most powerful directive to provide search (where conditions) for your GraphQL queries.

Read more.

@sortBy

Probably the most powerful directive to provide sort (order by conditions) for your GraphQL queries.

Read more.

@stream 🧪

Unlike the @paginate (and similar) directive, the @stream provides a uniform way to perform Offset/Limit and Cursor pagination of Eloquent/Query/Scout builders. Filtering and sorting enabled by default via @searchBy and @sortBy directives.

Read more.

@type

Converts scalar into GraphQL Type. Similar to Lighthouse's @scalar directive, but uses Laravel Container to resolve instance and also supports PHP enums.

Read more.

Scalars

[!IMPORTANT]

You should register the Scalar before use, it can be done via TypeRegistry, or as a custom scalar inside the Schema:

JsonString

Represents JSON string.

Read more.

Scout

Scout is also supported 🤩. You just need to add @search directive to an argument. Please note that available operators depend on Scout itself.

Please note that if the @search directive added, the generated query will expect the Scout builder only. So recommended using non-nullable String! type to avoid using the Eloquent builder (it will happen if the search argument missed or null; see also lighthouse#2465.

Input type auto-generation

The type used with the Builder directives like @searchBy/@sortBy may be Explicit (when you specify the input name field(where: InputTypeName @searchBy): [Object!]!) or Implicit (when the _ used, field(where: _ @searchBy): [Object!]!). They are processing a bit differently.

For Explicit type, all fields except unions and marked as ignored (if supported by the directive) will be included.

For Implicit type, the following rules are applied (in this order; concrete directive may have differences, please check its docs):

• Union? - exclude
• Has Operator of the concrete directive? - include
• Has Nuwave\Lighthouse\Support\Contracts\FieldResolver?
  • Yes
  • Is Nuwave\Lighthouse\Schema\Directives\RelationDirective? - Include if is the Object or list of Object
  • Is Nuwave\Lighthouse\Schema\Directives\RenameDirective? - Include if allowed, is scalar/enum (not Object), and no arguments
  • Otherwise - exclude
  • No
  • Is Object or has arguments - exclude
  • Otherwise - include
• Ignored (if supported)? - exclude

When converting the field, some of the original directives will be copied into the newly generated field. For the Explicit type, all directives except operators of other directives will be copied. For Implicit type, you can use builder.allowed_directives setting to control. Be aware of directive locations - the package doesn't perform any checks to ensure that the copied directive allowed on INPUT_FIELD_DEFINITION, it just copies it as is.

Builder field/column name

By default @searchBy/@sortBy will convert nested/related fields into dot string: eg {user: {name: asc}} will be converted into user.name. You can redefine this behavior by BuilderFieldResolver:

Builder type detection

Directives like @searchBy/@sortBy have a unique set of operators and other features for each type of Builder (Eloquent/Scout/etc). Detection of the current Builder works fine for standard Lighthouse directives like @all, @paginated, @search, etc and relies on proper type hints of Relations/Queries/Resolvers. You may get BuilderUnknown error if the type hint is missed or the union type is used.

If you implement custom directives which internally enhance the Builder (like standard directives do), you may get BuilderUnknown error because the proper/expected builder type was not detected. In this case, your directive should implement BuilderInfoProvider interface and to specify the builder type explicitly.

Printer

The package provides bindings for Printer so you can simply use:

Testing Assertions

assertGraphQLIntrospectionEquals

Compares default public schema (as the client sees it through introspection).

Read more.

assertGraphQLSchemaEquals

Compares default internal schema (with all directives).

Read more.

assertGraphQLSchemaNoBreakingChanges

Checks that no breaking changes in the default internal schema (with all directives).

Read more.

assertGraphQLSchemaNoDangerousChanges

Checks that no dangerous changes in the default internal schema (with all directives).

Read more.

assertGraphQLSchemaValid

Validates default internal schema (with all directives). Faster than lighthouse:validate-schema command because loads only used directives.

Read more.

Upgrading

Please follow Upgrade Guide.

Contributing

This package is the part of Awesome Set of Packages for Laravel. Please use the main repository to report issues, send pull requests, or ask questions.