NAME
Plack::App::GraphQL - Serve GraphQL from Plack / PSGI
SYNOPSIS
use Plack::App::GraphQL;
my $schema = q|
type Query {
hello: String
}
|;
my %root_value = (
hello => 'Hello World!',
);
my $app = Plack::App::GraphQL
->new(schema => $schema, root_value => \%root_value)
->to_app;
Or mount under a given URL:
use Plack::Builder;
use Plack::App::GraphQL;
# $schema and %root_value as above
my $app = Plack::App::GraphQL
->new(schema => $schema, root_value => \%root_value)
->to_app;
builder {
mount "/graphql" => $app;
};
You can also use the 'endpoint' configuration option to set a root path to match. This is the most simple option if you application is not serving other endpoints or applications (See documentation below).
DESCRIPTION
Please note this is an early access / minimal documentation release. You should already be familiar with GraphQL. There's some examples in /examples
but few real test cases. If you are not comfortable using this based on reading the source code and can't accept the possibility that the underlying code might change (although I expect the configuration options are pretty set now) then you shouldn't use this. I recommend looking at official plugins for Dancer and Mojolicious: Dancer2::Plugin::GraphQL, Mojolicious::Plugin::GraphQL instead (or you can send me patches :) ).
This currently doesn't support an asychronous responses until updates are made in core GraphQL.
CONFIGURATION
This Plack applications supports the following configuration arguments:
schema
The GraphQL::Schema. Canonically this should be an instance of GraphQL::Schema but if you pass a string or a filehandle, we will assume that it is a parse-able graphql SDL document that we can build a schema object from. Makes for easy demos.
root_value
An object, hashref or coderef that field resolvers can use to look up requests. Generally the method or hash keys will match the query or mutation keys. See the examples for more.
You can override this at runtime (with for example a bit of middleware) by using the 'plack.graphql.root_value' key in the PSGI $env. This may or my not be considered a good practice :) Some examples suggest always using the $context for stuff like this while other examples seem to think its a good idea. I choose to rather enable this ability and let you decide what is right for your application.
resolver
Used to change how field resolvers work. See GraphQL (or ignore this since its likely something you really don't need for normal work.
convert
This takes a sub class of GraphQL::Plugin::Convert, such as GraphQL::Plugin::Convert::DBIC. Providing this will automatically provide "schema", "root_value" and "resolver".
You can shortcut the value of this with a '+' and we will assume the default namespace. For example '+DBIC' is the same as 'GraphQL::Plugin::Convert::DBIC'.
endpoint
The URI path part that is associated with the graphql API endpoint. Often this is set to 'graphql'. The default is '/'. You might prefer to use a custom or alternative router (for example Plack::Builder).
context_class
Default is Plack::App::GraphQL::Context. This is an object that is passed as the 'context' argument to your field resolvers. You might wish to subclass this to add additional useful methods such as simple access to a user object (if you you authentication for example).
graphiql_version
String that defaults to 'latest'. This allows you to specify the graphiql version to use.
NOTE Setting this does not enable GraphiQL.
graphiql
Boolean that defaults to FALSE. Turn this on to enable the HTML Interactive GraphQL query screen. Useful for leaning and debugging but you probably want it off in production.
NOTE If you want to use this you should also install Template::Tiny which is needed. We don't make Template::Tiny a dependency here so that you are not forced to install it where you don't want the interactive screens (such as production).
json_encoder
Lets you specify the instance of the class used for JSON encoding / decoding. The default is an instance of JSON::MaybeXS so you will want to be sure install a fast JSON de/encoder in production, such as Cpanel::JSON::XS (it will default to a pure Perl one which might not need your speed requirements).
exceptions_class
Class that provides the exception responses. Override the default (Plack::App::GraphQL::Exceptions) if you want complete control over how your errors look.
METHODS
TBD
AUTHOR
John Napiorkowski <jnapiork@cpan.org>
SEE ALSO
COPYRIGHT
Copyright (c) 2019 by "AUTHOR" as listed above.
LICENSE
This library is free software and may be distributed under the same terms as perl itself.