README

This Symfony bundle provides integration of GraphQL using Railt GraphQL.

Requirements

• php: ^8.1
• symfony: ^5.4|^6.0
• railt/railt: ^2.0

Installation

Library is available as composer repository and can be installed using the following command in a root of your project.

$ composer require railt/symfony-bundle

Then add bundle into the registered config/bundles.php list:

<?php

return [
    // ...
    Railt\SymfonyBundle\RailtBundle::class => ['all' => true],
];

Configuration

The fastest way to get started is to create the following configuration file in config/packages/railt.yaml.

railt:
  endpoints:
    default:
      route: /graphql
      schema: '%kernel.project_dir%/resources/schema.graphqls'

  playground:
    default:
      endpoint: default
      route: /graphiql

And schema.graphqls files inside the resources directory in root of your project with the following content:

schema {
    query: Query
}

type Query {
    hello: String @route(action: "App\Controller\ExampleController")
}

Then create the following controller:

<?php

namespace App\Controller;

final class ExampleController
{
    public function __invoke(): string
    {
        return 'Hello!';
    }
}

All Configuration Options

Below is an example of a bundle configuration with all possible options.

railt:
  #
  # List of defined compilers.
  #
  # ```
  # compilers:
  #   <name-1>:
  #     option: value-1
  #   <name-2>:
  #     option: value-2
  # ```
  #
  compilers:
    default:
      #
      # Reference to the PSR-6 or PSR-16 cache service.
      #
      # default: null
      #
      cache: 'cache.app'

      #
      # Compiler's specification version.
      #
      # Should be one of:
      # - "railt" - Modern extended version of specification.
      # - "draft" - See https://spec.graphql.org/draft/
      # - "october-2021" - See https://spec.graphql.org/October2021/
      # - "june-2018" - See https://spec.graphql.org/June2018/
      # - "october-2016" - See https://spec.graphql.org/October2016/
      # - "april-2016" - See https://spec.graphql.org/April2016/
      # - "october-2015" - See https://spec.graphql.org/October2015/
      # - "july-2015" - See https://spec.graphql.org/July2015/
      #
      # default: "railt"
      #
      spec: railt

      #
      # Reference to predefined types service.
      #
      # Should be instance of `Railt\TypeSystem\DictionaryInterface`.
      #
      # default: null
      #
      types: null

      #
      # Autogenerated root types stubs.
      #
      generate:
        #
        # Generated root object type name for queries.
        #
        # default: "Query"
        #
        query: Query

        #
        # Generated root object type name for mutations.
        #
        # default: null
        #
        mutation: null

        #
        # Generated root object type name for subscriptions.
        #
        # default: null
        #
        subscription: null

      #
      # Auto casting types compiler's options.
      #
      cast:
        #
        # Allow to cast integer values as floats.
        #
        # ```
        # input Example {
        #
        #   "Allow Int(1) as default of Float"
        #   inCaseOfEnabled(arg: Float = 1): Any
        #
        #   "Allow only Float(1.0) as default of Float"
        #   inCaseOfDisabled(arg: Float = 1.0): Any
        #
        # }
        # ```
        #
        # default: true
        #
        int_to_float: true

        #
        # Allow to cast scalar values as strings.
        #
        # ```
        # input Example {
        #
        #   "Allow Float(1.0) as default of String"
        #   inCaseOfEnabled(arg: String = 1.0): Any
        #
        #   "Allow only String("1.0") as default of String"
        #   inCaseOfDisabled(arg: String = "1.0"): Any
        #
        # }
        # ```
        #
        # default: true
        #
        scalar_to_string: true

      #
      # Default values extraction logic.
      #
      extract:
        #
        # Allow to extract nullable types as default values.
        #
        # ```
        # input Example {
        #
        #   "Allow nullables as default values"
        #   inCaseOfEnabled(arg: String): Any
        #
        #   "In case of disabled the default value must be defined explicitly"
        #   inCaseOfDisabled(arg: String = null): Any
        #
        # }
        # ```
        #
        # default: true
        #
        nullable: true

        #
        # Allow to extract list types as default values.
        #
        # ```
        # input Example {
        #
        #   "Allow lists as default values"
        #   inCaseOfEnabled(arg: [String]!): Any
        #
        #   "In case of disabled the default value must be defined explicitly"
        #   inCaseOfDisabled(arg: [String]! = []): Any
        #
        # }
        # ```
        #
        # default: true
        #
        list: true

      #
      # List of directories from which GraphQL files should be loaded.
      #
      # In the case that a "%kernel.project_dir%/resources" directory is
      # specified, then in case when assembling the schema, type "Example" is
      # required (for example: `field(arg: Example): String`) then
      # "%kernel.project_dir%/resources/Example.graphqls" or
      # "%kernel.project_dir%/resources/Example.graphql" will be loaded
      # (if exists).
      #
      # default: []
      #
      autoload:
        - '%kernel.project_dir%/resources'

  #
  # List of public GraphQL endpoints.
  #
  # ```
  # endpoints:
  #   <name-1>:
  #     option: value-1
  #   <name-2>:
  #     option: value-2
  # ```
  #
  endpoints:
    default:
      #
      # URI pathname to the GraphQL endpoint.
      #
      # required
      #
      route: /graphql

      #
      # Pathname to the GraphQL schema file.
      #
      # required
      #
      schema: '%kernel.project_dir%/resources/schema.graphqls'

      #
      # List of variables passed to the schema file.
      #
      # You can use these values inside the schema file:
      #
      # ```
      # variables:
      #   exampleController: "Path\To\ExampleController"
      # ```
      #
      # ```
      # type UserList {
      #     get(count: Int! = 100): [User!]
      #         @route(action: $exampleController)
      # }
      # ```
      #
      # default: []
      #
      variables:
        isDebug: '%kernel.debug%'

      #
      # Reference to defined compiler (from "compilers" section) name or
      # reference to Symfony's DI service.
      #
      # default: null
      #
      compiler: default

      #
      # List of GraphQL middleware.
      #
      # Should be instance of `Railt\Contracts\Http\Middleware\MiddlewareInterface`.
      #
      # default: []
      #
      middleware: []

      #
      # List of Railt GraphQL extensions (plugins).
      #
      # Should be instance of `Railt\Foundation\Extension\ExtensionInterface`.
      #
      # default: []
      #
      extensions:
        - Railt\Extension\Router\RouterExtension
        - Railt\Extension\DefaultValue\DefaultValueExtension

  #
  # List of GraphQL playground (GraphiQL) endpoints.
  # See: https://github.com/graphql/graphiql
  #
  # ```
  # playground:
  #   <name-1>:
  #     option: value-1
  #   <name-2>:
  #     option: value-2
  # ```
  #
  playground:
    default:
      #
      # Reference to "endpoints" section for which this
      # playground will be used.
      #
      # required
      #
      endpoint: default

      #
      # URI pathname of playground.
      #
      # required
      #
      route: /graphiql

      #
      # List of additional optional headers that be used for each request.
      #
      # default: []
      #
      headers:
        X-Api-Playground: GraphiQL