GraphQL
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. — graphql.org
Here is how you can create a GraphQL endpoint using Siler's simplicity powered by the PHP's GraphQL implemention.
First, let's require it:
$ composer require webonyx/graphql-php
Siler doesn't have direct dependencies, to stay fit, it favors peer dependencies, which means you have to explicitly declare a
graphql dependency in your project in order to use it.Now let's define our Schema. We're going to use a chat-like domain:
schema.graphql
type Message {
id: Int
roomId: Int
body: String
timestamp: String
}
type Room {
id: Int
name: String
messages: [Message]
}
type Query {
messages(roomName: String): [Message]
rooms: [Room]
}
type Mutation {
start(roomName: String): Room
chat(roomName: String, body: String): Message
}
Very simple, but if it's not familiar to you, take a look at GraphQL first since this docs will not cover what is it, but how to use it.
For each Query and Mutation we can define our resolver functions. We'll be using RedBean to help us as a simple SQLite storage ORM.
resolvers.php
<?php
use RedBeanPHP\R;
R::setup('sqlite:'.__DIR__.'/db.sqlite');
$roomByName = function ($name) {
return R::findOne('room', 'name = ?', [$name]);
};
$roomType = [
'messages' => function ($room) {
return R::findAll('message', 'room_id = ?', [$room['id']]);
},
];
$queryType = [
'rooms' => function () {
return R::findAll('room');
},
'messages' => function ($root, $args) use ($roomByName) {
$roomName = $args['roomName'];
$room = $roomByName($roomName);
$messages = R::find('message', 'room_id = ?', [$room['id']]);
return $messages;
},
];
$mutationType = [
'start' => function ($root, $args) {
$roomName = $args['roomName'];
$room = R::dispense('room');
$room['name'] = $roomName;
R::store($room);
return $room;
},
'chat' => function ($root, $args) use ($roomByName) {
$roomName = $args['roomName'];
$body = $args['body'];
$room = $roomByName($roomName);
$message = R::dispense('message');
$message['roomId'] = $room['id'];
$message['body'] = $body;
$message['timestamp'] = new \DateTime();
R::store($message);
return $message;
},
];
return [
'Room' => $roomType,
'Query' => $queryType,
'Mutation' => $mutationType,
];
Awesome. We have type definitions and resolver functions. Let's put them together in a Schema:
schema.php
<?php
use Siler\GraphQL;
$typeDefs = file_get_contents(__DIR__.'/schema.graphql');
$resolvers = include __DIR__.'/resolvers.php';
return GraphQL\schema($typeDefs, $resolvers);
Yeah, that simple! And it's exactly where Siler does it magic happen.
Thanks to
webonyx/graphql-php we can parse the schema.graphql into an actual Schema and Siler will override the default field resolver to work with the given $resolvers.Now, let's create our HTTP endpoint:
api.php
<?php
use Siler\GraphQL;
use Siler\Http\Request;
use Siler\Http\Response;
require 'vendor/autoload.php';
// Enable CORS
Response\cors();
// Respond only for POST requests
if (Request\method_is('post')) {
// Retrive the Schema
$schema = include __DIR__.'/schema.php';
// Give it to siler
GraphQL\init($schema);
}
Start the server:
$ php -S localhost:8000 api.php
Here are some queries you can execute:
Query available rooms:
query {
rooms {
id
name
}
}
Yeah, there isn't any Rooms yet:
{
"data": {
"rooms": []
}
}
But. It's working!. Thanks to RedBean + SQLite we can play around without worrying about database setup and migrations.
Creating a new Room:
mutation newRoom($roomName: String) {
start(roomName: $roomName) {
id
}
}
variables
{
"roomName": "graphql"
}
Then our first room is created:
{
"data": {
"start": {
"id": 1
}
}
}
Call the query that fetches Rooms to check again:
query {
rooms {
id
name
}
}
Yup! It's there:
{
"data": {
"rooms": [
{
"id": 1,
"name": "graphql"
}
]
}
}
Without any Messages yet:
query roomMessages($roomName: String) {
messages(roomName: $roomName) {
id
body
timestamp
}
}
variables
{
"roomName": "graphql"
}
No messages yet:
{
"data": {
"messages": []
}
}
So let's chat!
mutation newMessage($roomName: String) {
chat(roomName: $roomName, body: "hello") {
id
}
}
variables
{
"roomName": "graphql"
}
First message created:
{
"data": {
"chat": {
"id": 1
}
}
}
Let's refetch our messages to check:
query roomMessages($roomName: String) {
messages(roomName: $roomName) {
id
body
timestamp
}
}
variables
{
"roomName": "graphql"
}
Aha! Here we go:
{
"data": {
"messages": [
{
"id": 1,
"body": "hello",
"timestamp": "2017-04-20 14:58:07"
}
]
}
}
Liked it? What about listening to added messages and enable real-time features?
Sounds cool? That is GraphQL Subscriptions and we are going to cover next.
Here is how you can add real-time capabilities to your GraphQL applications.
We'll need some help to get WebSockets working, so let's require two libraries.
One is for the server-side:
$ composer require cboden/ratchet
And the other is for the client-side:
$ composer require textalk/websocket
First, let's add our Subscription type to our Schema:
schema.graphql
# (...previous work...)
type Subscription {
inbox(roomName: String): Message
}
Simple like that. We can subscribe to inboxes to receive new messages.
And our resolver will look like that:
resolvers.php
# (...previous work...)
$subscriptionType = [
'inbox' => function ($message) {
return $message;
},
];
Yeap, it is just resolving to the message that it receives.
But where this message comes from?
Siler has a function at the
Graphql namespace to define where your subscriptions are running:GraphQL\subscriptions_at('ws://127.0.0.1:3000');
Here we are assuming that they are running at localhost on port 8080.
This is just a helper that adds the Subscriptions endpoint to the Siler container so another function can actually use it when needed. And this function is
publish!Siler\GraphQL\publish will make a WebSocket call to the Subscriptions server notifying that something has happened.GraphQL\publish('inbox', $message);
It's first argument is the Subscription that will be triggered and the second argument is a data payload, in our case, the new message that has been created.
Our
resolvers.php will look like this:resolvers.php
<?php
use RedBeanPHP\R;
use Siler\GraphQL;
R::setup('sqlite:'.__DIR__.'/db.sqlite');
// Here we set where our subscriptions are running
GraphQL\subscriptions_at('ws://127.0.0.1:3000');
$roomByName = function ($name) {
return R::findOne('room', 'name = ?', [$name]);
};
$roomType = [
'messages' => function ($room) {
return R::findAll('message', 'room_id = ?', [$room['id']]);
},
];
$queryType = [
'rooms' => function () {
return R::findAll('room');
},
'messages' => function () use ($roomByName) {
$roomName = $args['roomName'];
$room = $roomByName($roomName);
$messages = R::find('message', 'room_id = ?', [$room['id']]);
return $messages;
},
];
$mutationType = [
'start' => function ($root, $args) {
$roomName = $args['roomName'];
$room = R::dispense('room');
$room['name'] = $roomName;
R::store($room);
return $room;
},
'chat' => function ($root, $args) use ($roomByName) {
$roomName = $args['roomName'];
$body = $args['body'];
$room = $roomByName($roomName);
$message = R::dispense('message');
$message['roomId'] = $room['id'];
$message['body'] = $body;
$message['timestamp'] = new \DateTime();
R::store($message);
// Then we can publish new messages that arrives from the chat mutation
GraphQL\publish('inbox', $message); // <- Exactly what "inbox" will receive
return $message;
},
];
// Our added Subscription type
$subscriptionType = [
'inbox' => function ($message) { // <- Received from "publish"
return $message;
},
];
return [
'Room' => $roomType,
'Query' => $queryType,
'Mutation' => $mutationType,
'Subscription' => $subscriptionType, // Add to the resolver functions array
];
As in
api.php endpoint we need to setup the Subscriptions server:subscriptions.php
<?php
use function Siler\{GraphQL, Ratchet};
require_once '/vendor/autoload.php';
$schema = require_once __DIR__ . '/schema.php';
$manager = GraphQL\subscriptions_manager($schema);
Ratchet\graphql_subscriptions($manager)->run();
Yeah, easy like that. Let Siler do the boring stuff. You just give a Schema to the
subscriptions function. This function will return an IoServer where you can call the run method.php subscriptions.php
By default, Siler will run the subscriptions at localhost on port 8080.
To run subscriptions server at a production-grade level, please consider using some long-running process manager like Supervisor. Take a look at http://socketo.me/docs/deploy#supervisor.
No kidding.
Behind the scenes ReactPHP, Ratchet and Pawl are doing the hard work of handling WebSocket communication protocol while Siler is doing the work of adding resolver resolution to webonyx/graphql-php and handling Apollo's sub-protocol.
A subscription query looks like this:
subscription newMessages($roomName: String) {
inbox(roomName: $roomName) {
id
body
}
}
variables
{
"roomName": "graphql"
}
The result will not be immediate since we are now listening to new messages, not querying them.
mutation newMessage($roomName: String) {
chat(roomName: $roomName, body: "hello") {
id
}
}
variables
{
"roomName": "graphql"
}
Now go back to the subscription tab and see the update!
{
"inbox": {
"id": 42,
"body": "hello"
}
}
Awesome! Just one thing you probably have noticed. We have subscribed to all rooms. Make a test: create another Room if you haven't already and add a new message to that to see that our subscription tab, with
{"roomName": "graphql"} as variables, just got this new message. How to solve this?Filters are part of Siler and based on Apollo's setup functions. Filter functions receives the published payload data as the first argument and the subscription variables as the second, so you can use them to perform matches:
subscriptions.php
<?php
use function Siler\{GraphQL, Ratchet};
require_once '/vendor/autoload.php';
$filters = [
'inbox' => function ($payload, $vars) {
return $payload['room_name'] == $vars['roomName'];
},
];
$schema = require_once __DIR__ . '/schema.php';
$manager = GraphQL\subscriptions_manager($schema, $filters);
Ratchet\graphql_subscriptions($manager)->run();
As you can see, we have extend our Subscriptions endpoint adding filters. The filters array keys should match corresponding Subscription names, in our case:
inbox. We are just checking if the given payload room_name is the same as the provided by the Subscription variable roomName. Siler will perform this checks for each subscription before trying to resolve and broadcast them.We need just a little thing to get working. Adding this
room_name field to our payload since Message only has the room_id. At the chat resolver, before the publish, add this line:$message['roomName'] = $roomName; // For the inbox filter
GraphQL\publish('inbox', $message); // <- Exactly what "inbox" will receive
When a
RedBeanObject is encoded to JSON it automatically converts camel case properties to underscore ones. That is why we give roomName, but receive as room_name.And that should be enough to solve our problem, now you only receive data from the subscribed rooms. Enjoy!
You can see a complete example including file uploads and directives at: github.com/leocavalcante/siler/examples/graphql.
Last modified 3yr ago