Download the PHP package rozbehsharahi/graphql3 without Composer

GraphQL3

This extension is brand-new still and lacks testing of real users. You are very welcome to contribute by testing and using the issue board.

This package enables you to register a graphql schema for your TYPO3 page.

If you register a schema, it is accessible via the tail /graphql or /graphiql on your site's root-page:

https://www.example.com/my-site-root/graphql
https://www.example.com/my-site-root/graphiql (TYPO3_CONTEXT=Development only)

Usage

Schemas are registered using webonyx/graphql-php package types.

Documentation: https://webonyx.github.io/graphql-php/

Schematically the usage of graphql3 is as following:

After that you should already be able to access your graphql endpoint.

The method register expects a schema of webonyx/graphql-php package, so you are free to do whatever you wish from here on.

However, the main focus of graphql3 is providing extendable builders/types/nodes/resolvers, which will facilitate the introduction of GraphQL on TYPO3 sites.

For instance the following code is completely equivalent, but uses one of the in-house types.

In order to have some real working TYPO3 code, continue to the next chapter Getting started.

Getting started

We assume you have a working TYPO3 extension and a Configuration/Services.yaml (as following), which will make constructor injection and service locating work.

https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/DependencyInjection/Index.html#dependency-injection-autoconfigure

Create a graphql setup class, somewhere in your extension's Classes directory.

It does not matter, where you place your GraphqlSetup class. As long as you implement GraphqlSetupInterface graphql3 will auto-detect your class and call the setup method. However, make sure to clear all caches!

At this point your graphql endpoint should already be accessible.

The build-in QueryType provides already a tca-based schema for following entities:

• pages
• tt_content
• languages

Try for instance:

Extending the schema is as simple as implementing the QueryTypeExtenderInterface.

The QueryType implementation is using built-in tca-based builders. If you want to add your own entities to graphql you can use them as well:

In the given example, record-node-builder and record-list-node-builder were used. These classes will auto generate a graphql schema, based on TCA configuration. Now it is for instance possible to run following query:

Registering a schema on graphql3 will activate the graphql endpoint. This is task should be done by only one single extension, in most cases your main project extension. Other extensions should only provide schema fields and types, ... which will be explained in the following chapter Documentation.

Documentation

Let's start off with the QueryType.

QueryType

Query type is basic query configuration, which you can use to start off. It already provides a couple of root-nodes, like page. However, it is possible to extend the query at run-time, which enables any extension to hook in.

You might already check out your /graphiql route and for instance send a query as following:

QueryType exposes the configuration of root nodes/fields by QueryTypeExtenderInterface. By implementing the interface you can edit all nodes on your root query.

Record Type Builder

In order to expose a TYPO3 table, a record graphql type is needed. Graphql3 provides a TCA based record type builder. The builder will generate webonyx/graphql object types based on TCA configuration.

In the following example a page node on root query is created with the help of record-type-builder.

The given example only passes a hard-coded page array to the type.

It does make a lot of sense to have a uid parameter and a resolver which loads the page by that uid. This will be tackled in the following chapters.

Apart from just creating the record type on the fly, the builder will also provide extendability and type caching.

Any extension can hook into the type creation of any table by implementing \RozbehSharahi\Graphql3\Builder\RecordTypeBuilderExtenderInterface.

The following code shows how the pages type can be extended by an additional node md5.

As long as the class implements \RozbehSharahi\Graphql3\Builder\RecordTypeBuilderExtenderInterface the position does not matter. Symfony dependency injection will take care of loading the extender. However, clear the caches!

It is also possible to remove or edit existing fields by extenders. For this check out GraphqlNodeCollection and GraphqlNode, which will be explained in chapter GraphqlNode and GraphqlNodeCollection.

Node builders

Graphql3 provides node builders in order to facilitate the creation of whole nodes. This includes type, resolver & arguments.

Every node builder implements NodeBuilderInterface which by definition means it provides a build method which returns an instance of GraphqlNode.

In following sections the record-type-builder is taken as an example. Check out vendor/rozbehsharahi/graphql3/Classes/Builder to see which other builders exist and can be used.

When creating a meaningful page node we most likely need:

• A resolver to load a page
• An uid argument which defines which page should be loaded
• A type which describes the fields of the page.

The RecordNodeBuilder can be used as following:

Under the hood this will:

• [x] Create an argument uid
• [x] Create a resolver via \RozbehSharahi\Graphql3\Resolver\RecordResolver
• [x] Create the page type via \RozbehSharahi\Graphql3\Builder\RecordTypeBuilder

There is a lot of features which will be activated by this. For instance:

• [x] Access check
• [x] Extendability via Extenders
• [x] Flexible mapping of tca fields to graphql fields

List node builders

As record-node-builders will create singular nodes as page, content, logs, list-node-builders will create pages , content, logs.

They come in with a pack of built-in features as:

• [x] Pagination
• [x] Filtering
• [x] Counting
• [ ] Faceting (will follow)

Let's say you added sys_log to your graphql endpoint as following:

By this you can already do following query:

A more complete documentation of built-in filters will follow.

Languages

The list-node-builder follows this logic regarding sys_language_uid relations:

Whenever a table has langagueField set on TCA it will add an extra query parameter for language filtering.

The parameter expects currently the twoLetterIsoCode. If the given language is available on the current site it will be set as a filter to the query. A none-available language will cause an exception with a descriptive error message.

Languages are inherited to child-relations. For instance fetching a page record for language "en" will result in children to be filtered for language "en" as well.

Access control

The access control of graphql3 is implemented on top of symfony/security-core package. It is implemented as a jwt token secured application.

JWT auth

All access control related code on graphql3 is based on jwt-authentication, which is abstract within the class \RozbehSharahi\Graphql3\Domain\Model\JwtUser. From core code perspective there is only authentication via JWT auth headers (Bearer token, header-line: Authorization). The core code will therefore not know the origin of the token but will require two fields to be set on jwt token username (string) and roles (array of string).

In order to create an access token you can use following commands:

All code will always act as if jwt-token authentication has taken place, however if graphql3 finds a currently logged in fe-user it will map that user to a jwt-token. This is reflected within the implemented \RozbehSharahi\Graphql3\Domain\Model\JwtUser::createFromTypo3Session.

In order to provide compatibility between JwtUser::$roles (array of strings) and TYPO3, a convention for mapping was implemented. Whenever a jwt-user shall match a TYPO3-Backend user group it has to contain a user-role with following scheme: ROLE_GROUP_ID::[fe_group.uid]. By this convention in-house voters will decide, whether the user has access to a specific record, which is restricted to certain typo3-user-groups. In order to abstract this convention there is a method JwtUser::hasGroupId(x), which will under the hood call JwtUser::hasRole('ROLE_GROUP_ID::x').

The mapping of TYPO3 users to JwtUser is currently very basic. Most of the cases should be satisfied by that. Nevertheless, if you for instance need user-group inheritance, an extension of graphql3 is necessary. Please let me know in an Issue-Entry on Github if you happen to need such.

Jwt auth setup / configuration

Currently graphql3 supports following algorithms:

• [x] RS256
• [x] RS256 with password secured secret
• [x] HS256
• [x] EdDSA

Following env vars you will need to set. If no public key is defined it will fall back to private key for none-asymmetric signatures as HS256.

• [x] Private key (needed for creating tokens, for instance vendor/bin/typo3 graphql3:create-token:manual)
• [x] Public key (needed on some algorithms like RS256 for validating tokens)
• [x] Algorithm (for instance RS256, HS256, EdDSA, default RS256)
• [x] Passphrase (needed if private key is password encrypted)

The following example configuration should be the most common setup:

With a correctly set up environment you can use the command to generate a token.

Please make sure your apache configuration or nginx configuration allows authorization headers.

Voting & ACL

Under the hood, RecordNodeBuilder is using an in-house RecordResolve, which is responsible to resolve a record based on the uid/slug given. However, the resolver does a bit more than that. For instance providing access control, which can be controlled on project level via Voters.

Whenever a record is resolved, it is passed to AccessDecisionManager. This is also the case inside of RecordListNodeBuilder, where every loaded record is checked for access.

In order to modify/add access control to your project, you can simply create a class which implements \RozbehSharahi\Graphql3\Voter\VoterInterface. When implementing the interface, your voter will be automatically added to the stack of voters, no matter where you place it.

Make sure to implement the Graphql3 variant of VoterInterface, instead of the Symfony VoterInterface.

A voter as shown here, is of course not needed, as this is already handled by a generic in-house RecordResolver.

The access-decision-manager is configured to use the UnanimousStrategy. This means all voters must grant or abstain access. If all voters abstain, access is given. Checkout symfony/security documentation for further understanding.

Modifying the existing \RozbehSharahi\Graphql3\Voter\RecordVoter can be done via symfony's dependency injection container in any extension's Configuration/Services.yaml.

Flex form

Intro

While graphql is a strongly typed query language, flex-forms are more loose. At least on database side. The data of flex-forms is typed, however if you step deeper in to TYPO3 logic you will see that things can get very washy.

It is possible to type a field, for instance settings.page as an integer on a flexform xml. However, due to TYPO3's feature of having dynamic flex form definitions for the same database-field (for instance pi_flexform) based on another table field (for instance list_type or even more complex list_type, CType see TCA documentation) it is not possible to verify that the field settings.page is always of type x. It would be possible to spread each flex-form definition into its own scope automatically, nevertheless it would cause heavy xml processing on creating the schema, and it would bring a lot of complexity to the code. Most probably the effort of implementation outweighs the usefulness of such an automatic schema creation.

Based on these thoughts graphql3 delegates the integration of flex-form fields to the user of the extension instead of magically building up huge schemas. However, it tries to facilitate the procedure.

Activate flex-form-fields on graphql

Activating a flex-form field via configuration is still in experimental state. The API might therefore change frequently. Please notice that you can also simply write your own record-type-extender in order to expose you flex-form fields !

Flex forms can be accessed in a plain way:

This will return a none-type-safe array, which is basically a json representation of the flex-form xml.

However, graphql3 brings a type-safe integration for your flex-form fields. In order to expose a flex form field to graphql you must configure your tables TCA in order to tell graphql3 the path to your flex-form configuration.

The path two a flex-form field is split into 3 parts:

• the base database column: pi_flexform
• the data structure variant default (see TCA documentation for config.ds)
• the flex-form-field: settings.myField

By this, graphql3 will internally create a "fake-tca-column" based on the flex-form definition of settings.myField and pass it to the stack of field-creators as if it was a normal column. A unique name for that field will be created: flex_piFlexform_default_settings_myField. You can configure your own name the same way you would to for normal DB columns.

If you look at the implementation of RozbehSharahi\Graphql3\Domain\Model\Record::get you will notice that values of column-names starting with flex:: will result into a flex-form value lookup.

This concept enables all field-creators to be compatible to flex-form columns as well. So in best-case whenever you write a field-creator, it will also be able to act as a flex-form-field-creator.

Please do not forget: In case of bugs you can always create your own record-type-extender to expose you flex-form fields, and you might send me a message eon the issue board ofc.

Mutations

For demonstration purposes graphql3 comes with a mutation for creating sys_news items. However, the implementation of mutations is very project & context specific and graphql3 will not make any assumptions on that. The existing example mutation createSysNews will only be available, when having a token with a role ROLE_CREATE::sys_news.

Mutations can be added via MutationTypeExtenderInterface and of course you can implement access-control by injection of AccessChecker.

Following code shows the implementation of a mutation:

In fact there is no difference between mutations and queries as you can also read up in webonyx/graphql documentation, therefore you can use the same methods and classes you use for queries on mutations.

GraphqlNode and GraphqlNodeCollection

When extending one of the build-in nodes/type/... you will receive relevant schema parts in your extender, which you are free to change. For instance a query type extender implementing the QueryTypeExtenderInterface, would receive the root-query nodes, which then can be edited. However, this will not be an array as you might expect. It will be a GraphqlNodeCollection.

This chapter will give an intro on how GraphqlNode and GraphqlNodeCollection work.

GraphqlNode is simply a representation of a webonyx/graphql-php array. It is used to have auto-complete and can simply be converted to an array.

On the other hand you have GraphqlNodeCollection, which is a collection of GraphqlNode objects.

Be aware, that graphql-nodes and -collections are immutables. Therefore, when calling methods like add or remove you will need to use return value.

The implementation of GraphqlArgument and GraphqlArgumentCollection, is pretty much the same. Checkout via auto-complete, which options you have.

Contribution

Checkout the contribution guide if you want to actively support this project or add features.

Continue here