GraphQL with GraphQLite integration

TDBM offers a native integration with GraphQLite

GraphQLite is a PHP library to easily develop a GraphQL library. GraphQLite core principle is to declare GraphQL types using PHP annotations.

For instance:

/**
 * @Type()
 */
class Product
{
    // ...

    /**
     * @Field()
     */
    public function getName(): string
    {
        return $this->name;
    }
}

However, in TDBM, the classes and getters are generated by TDBM itself. The getters are in the generated abstract classes and you cannot edit those files (as they are overwritten by TDBM each time you generate the beans and DAOs).

TDBM-GraphQL is a library that can read annotations from the database model and forward those annotations to the PHP classes.

You put @Type or @Field annotations in your database tables and columns and TDBM will generate these annotations in the beans and DAOs.

Installation

Installation for Symfony

Open a terminal in your current project directory and run:

$ composer require thecodingmachine/tdbm-graphql-bundle

Enable the library by adding it to the list of registered bundles in the config/bundles.php file (app/AppKernel.php for Symfony 3.x):

config/bundles.php

return [
    // ...
    'TheCodingMachine\\Tdbm\Graphql\\Bundle\\TdbmGraphqlBundle' => ['all' => true],
}

Configuration

The parameters are stored in the config/packages/tdbm-graphql.yaml file.

By default, generated types will go into App\Types.

If your default namespace for your application is not App, you should open this tdbm-graphql.yaml file and customize the tdbm-graphl.type_namespace and tdbm-graphl.generated_type_namespace (optionnal) to match your application namespace.

Here is a configuration file with all available options:

config/packages/tdbm-graphql.yaml

tdbm-graphql:
    type_namespace: App\Types
    generated_type_namespace: App\Types\Generated

Manual installation

Open a terminal in your current project directory and run:

$ composer require thecodingmachine/tdbm-graphql

The tdbm-graphql package provides a GraphQLTypeAnnotator. This class alters the way TDBM generates the beans and DAOs.

You must create an instance of this class and register it in the TDBM configuration:

use TheCodingMachine\Tdbm\GraphQL\GraphQLTypeAnnotator;
use TheCodingMachine\TDBM\Configuration;

// The parameter passed is the namespace in which the classes will be generated
$annotator = new GraphQLTypeAnnotator('App\\Types\\');
$configuration = new Configuration(
    'App\\Beans',
    'App\\DAOs',
    $connection,
    null,
    new ArrayCache(),
    null,
    null,
    [ $annotator ], // The annotator must be passed to the $generatorListeners parameter
    null,
    [ $annotator ] // and also to the $codeGeneratorListeners parameter
);

Annotating your DB model

In order to expose a bean as a GraphQL type, you must annotate the database model.

You can use the same annotations as in GraphQLite (but you must make sure they are fully qualified).

For each bean, you must put the @Type annotation in the class comment and the @Field annotation in each column you want to expose.

ALTER TABLE users COMMENT '@TheCodingMachine\\GraphQLite\\Annotations\\Type';
ALTER TABLE users MODIFY COLUMN `name` VARCHAR(255) NOT NULL COMMENT '@TheCodingMachine\\GraphQLite\\Annotations\\Field';

Adding comments on each column can be tedious. We highly recommend to use the TDBM Fluid Schema Builder to create the schema instead. The library provides a number of helpers to create the annotations for you:

$db->table('users')
   ->column('name')->string(50)->graphqlField();
   // The graphqlField() method will add the @Field annotation on the column AND the @Type annotation on the class at once.

Once your data model is commented with the annotations, you just have to regenerate the TDBM DAOs and beans:

bin/console tdbm:generate

You can check the getters in the generated beans, they should be annotated with the GraphQLite's @Field annotation.

Additional annotations supported

TDBM-GraphQL supports additional annotations to manage the fields' visibility:

ALTER TABLE users MODIFY COLUMN `name` VARCHAR(255) NOT NULL COMMENT '
  @TheCodingMachine\\GraphQLite\\Annotations\\Field
  @TheCodingMachine\\GraphQLite\\Annotations\\Logged
  @TheCodingMachine\\GraphQLite\\Annotations\\Right("CAN_SEE_NAME")
  @TheCodingMachine\\GraphQLite\\Annotations\\FailWith(null)
';

You can find more about these security annotations in the GraphQLite documentation.

You can also create these annotations using the TDBM Fluid Schema Builder.

$db->table('users')
   ->column('name')->string(50)->graphqlField()
   ->logged()->right('CAN_SEE_NAME')->failWith(null);

Found a typo? Something is wrong in this documentation? Just fork and edit it!