Facebook Query Builder

A query builder that makes it easy to create complex & efficient nested requests to Facebook's Graph API to get lots of specific data back with one request.

Facebook Query Builder has no production dependencies.

$fqb = new SammyK\FacebookQueryBuilder\FQB;

$photosEdge = $fqb->edge('photos')->fields(['id', 'source'])->limit(5);
$request = $fqb->node('me')->fields(['id', 'email', $photosEdge]);

echo (string) $request;
# https://graph.facebook.com/me?fields=id,email,photos.limit(5){id,source}

• Introduction
• Installation
• Usage
  • Initialization
  • A basic example
  • Get data across multiple edges
• Sending the nested request
• Obtaining an access token
• Configuration Settings
• Method Reference
• Handling the response
• Contributing
• License
• Security

Introduction

The Facebook Query Builder uses the same Graph API nomenclature for three main concepts:

1. Node: A node represents a "real-world thing" on Facebook like a user or a page.
2. Edge: An edge is the relationship between two or more nodes. For example a "photo" node would have a "comments" edge.
3. Field: Nodes have properties associated with them. These properties are called fields. A user has an "id" and "name" field for example.

When you send a request to the Graph API, the URL is structured like so:

https://graph.facebook.com/node-id/edge-name?fields=field-name

To generate the same URL with Facebook Query Builder, you'd do the following:

$edge = $fqb->edge('edge-name')->fields('field-name');
echo $fqb->node('node-id')->fields($edge);

If you were to execute that script, you might be surprised to see the URL looks a little different because it would output:

https://graph.facebook.com/node-id?fields=edge-name{field-name}

The two URL's are functionally identical with the exception of how the Graph API returns the response data. What makes the URL generated with Facebook Query Builder different is that it is being expressed as a nested request.

And that is what makes Facebook Query Builder so powerful. It does the heavy lifting to generate properly formatted nested requests from a fluent, easy-to-read PHP interface.

Installation

Facebook Query Builder is installed using Composer. Add the Facebook Query Builder package to your composer.json file.

{
    "require": {
        "sammyk/facebook-query-builder": "^2.0"
    }
}

Usage

Initialization

To start interfacing with Facebook Query Builder you simply instantiate a FQB object.

// Assuming you've included your composer autoload.php file before this line.
$fqb = new SammyK\FacebookQueryBuilder\FQB;

There are a number of configuration options you can pass to the FQB constructor.

A basic example

Below is a basic example that gets the logged in user's id & email (assuming the user granted your app the email permission).

$fqb = new SammyK\FacebookQueryBuilder\FQB;

$request = $fqb->node('me')
               ->fields(['id', 'email'])
               ->accessToken('user-access-token')
               ->graphVersion('v3.1');

echo $request;
# https://graph.facebook.com/v3.1/me?access_token=user-access-token&fields=id,email

$response = file_get_contents((string) $request);

var_dump($response);
# string(50) "{"id":"12345678","email":"foo-bar\u0040gmail.com"}"

Get data across multiple edges

The bread and butter of the Facebook Query Builder is its support for nested requests. Nested requests allow you to get a lot of data from the Graph API with just one request.

The following example will get the logged in user's name & first 5 photos they are tagged in with just one call to Graph.

$fqb = new SammyK\FacebookQueryBuilder\FQB([/* . . . */]);

$photosEdge = $fqb->edge('photos')->fields(['id', 'source'])->limit(5);
$request = $fqb->node('me')->fields(['name', $photosEdge]);

echo $request;
# https://graph.facebook.com/me?fields=name,photos.limit(5){id,source}

// Assumes you've set a default access token
$response = file_get_contents((string) $request);

var_dump($response);
# string(1699) "{"name":"Sammy Kaye Powers","photos":{"data":[{"id":"123","source":"https:\/\/scontent.xx.fbcdn.net\/hphotos-xfp1 . . .

And edges can have other edges embedded in them to allow for infinite deepness. This allows you to do fairly complex calls to Graph while maintaining very readable code.

The following example will get user 1234's name, and first 10 photos they are tagged in. For each photo it gets the first 2 comments and all the likes.

$fqb = new SammyK\FacebookQueryBuilder\FQB([/* . . . */]);

$likesEdge = $fqb->edge('likes');
$commentsEdge = $fqb->edge('comments')->fields('message')->limit(2);
$photosEdge = $fqb->edge('photos')
                  ->fields(['id', 'source', $commentsEdge, $likesEdge])
                  ->limit(10);

$request = $fqb->node('1234')->fields(['name', $photosEdge]);

echo $request;
# https://graph.facebook.com/1234?fields=name,photos.limit(10){id,source,comments.limit(2){message},likes}

// Assumes you've set a default access token
$response = file_get_contents((string) $request);

var_dump($response);
# string(10780) "{"name":"Some Foo User","photos":{"data":[ . . .

Sending the nested request

Since Facebook Query Builder is just a tool that generates nested request syntax, it doesn't make any requests to the Graph API for you. You'll have to use some sort of HTTP client to send the requests.

We'll assume you've already created an app in Facebook and have obtained an access token.

Requests with The Facebook PHP SDK

The recommended way to send requests & receive responses is to use the official Facebook PHP SDK v5. You'll need to create an instance of the Facebook\Facebook super service class from the native Facebook PHP SDK.

$fb = new Facebook\Facebook([
    'app_id' => 'your-app-id',
    'app_secret' => 'your-app-secret',
    'default_graph_version' => 'v3.1',
    ]);
$fqb = new SammyK\FacebookQueryBuilder\FQB;

$fb->setDefaultAccessToken('my-access-token');

$request = $fqb->node('me')->fields(['id', 'name', 'email']);

echo $request->asEndpoint();
# /me?fields=id,name,email

try {
    $response = $fb->get($request->asEndpoint());
} catch (Facebook\Exceptions\FacebookSDKException $e) {
    echo $e->getMessage();
    exit;
}

var_dump($response->getDecodedBody());

You'll noticed we're using the asEndpoint() method to send the generated request to the SDK. That's because the SDK will automatically prefix the URL with the Graph API hostname. The asEndpoint() method will return an un-prefixed version of the URL.

The official Facebook PHP SDK will automatically add the Graph API version, the app secret proof, and the access token to the URL for you, so you don't have to worry about setting those options on the FQB object.

Requests with native PHP

As you've already seen in the basic examples above, you can simply use PHP's flexible file_get_contents() to send the requests to the Graph API. Just be sure to set your Graph API version prefix with default_graph_version & set your app secret with app_secret to ensure all the requests get signed with an app secret proof.

$fqb = new SammyK\FacebookQueryBuilder\FQB([
    'default_graph_version' => 'v3.1',
    'app_secret'            => 'your-app-secret',
]);

// Grab Mark Zuckerberg's public info
$request = $fqb->node('4')->accessToken('my-access-token');

echo $request;
# https://graph.facebook.com/v3.1/4?access_token=my-access-token&appsecret_proof=2ad43b865030f51531ac36bb00ce4f59d9f879ecce31b0977dbfd73fa4eca7b6

$response = file_get_contents((string) $request);

var_dump($response);

For more info about handling the response, check out responses with native PHP below.

Obtaining an access token

As the Facebook Query Builder is exclusive to building nested request syntax, it cannot be used directly to obtain an access token.

The Facebook login process uses OAuth 2.0 behind the scenes. So you can use any OAuth 2.0 client library to obtain a user access token from Facebook. Here are a few recommendations:

• The official [Facebook PHP SDK v5](h