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 (recommended)
• The PHP League's OAuth 2.0 Client and the corresponding Facebook Provider
• Laravel 5's Socialite library

Configuration settings

A number of configuration settings can be set via the FQB constructor.

• The default_access_token option lets you define a default fallback access token for all generated queries.
• The default_graph_version option lets you define the default Graph API version URL prefix for all generated queries.
• An important security layer to the Graph API is the app secret proof which should be enabled on your app by default. You can sign each request generated by Facebook Query Builder with an app secret proof by setting the app_secret option with your app secret.

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

Setting the access token

If you're using the Facebook PHP SDK and have set a default access token for the SDK to use, then you won't need to worry about appending the access token to the request.

If you're using some other HTTP client, you can set the default fallback access token when you instantiate the FQB service with the default_access_token option or you can append the access token to the nested request using the accessToken() method.

$fqb = new SammyK\FacebookQueryBuilder\FQB([
    'default_access_token' => 'fallback_access_token',
]);

$request = $fqb->node('me');
echo $request->asEndpoint();
# /me?access_token=fallback_access_token

$request = $fqb->node('me')->accessToken('bar_token');
echo $request->asEndpoint();
# /me?access_token=bar_token

Setting the Graph version

It's important that you set the version of the Graph API that you want to use since the Graph API is subject to a breaking change schedule.

If you're using the Facebook PHP SDK and have set a default Graph version for the SDK to use, then you won't need to worry about setting the Graph version in the Facebook Query Builder.

If you're using some other HTTP client, you can set the default fallback Graph version when you instantiate the FQB service with the default_graph_version option or you can set it on a per-request basis using the graphVersion() method.

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

$request = $fqb->node('me');
echo $request->asEndpoint();
# /v3.1/me

$request = $fqb->node('me')->graphVersion('v1.0');
echo $request->asEndpoint();
# /v1.0/me

PS: Graph v1.0 is dead. 💀

Enabling app secret proof

As an added security feature, you can sign each request to the Graph API with an app_secretproof. It is highly recommended that you edit your app settings to require the app secret proof for all requests.

If you're using the Facebook PHP SDK to send requests to the Graph API, it will automatically append the app secret proof for you.

If you're using some other HTTP client, the app secret proof will be generated for a request if both an access token and app secret are set for a request. You can set the app secret when you instantiate the FQB service using the app_secret option.

$fqb = new SammyK\FacebookQueryBuilder\FQB([
    'app_secret' => 'foo_secret',
]);

$request = $fqb->node('me')->accessToken('bar_token');
echo $request->asEndpoint();
# /me?access_token=bar_token&appsecret_proof=2ceec40b7b9fd7d38fff1767b766bcc6b1f9feb378febac4612c156e6a8354bd

Enabling the beta version of Graph

Before changes to the Graph API are rolled out to production, they are deployed to the beta tier first.

By default, when you generate a nested request, it will be prefixed with the production hostname for the Graph API which is https://graph.facebook.com/.

echo (string) $fqb->node('4');
# https://graph.facebook.com/4

To enable the beta tier for the requests generated by FQB, set the enable_beta_mode option to true. Once enabled, all generated URL's will be prefixed with the beta hostname of the Graph API which is https://graph.beta.facebook.com/.

$fqb = new SammyK\FacebookQueryBuilder\FQB([
    'enable_beta_mode' => true,
]);

echo (string) $fqb->node('4');
# https://graph.beta.facebook.com/4

Method reference

• node()
• edge()
• fields()
• modifiers()
• limit()
• accessToken()
• graphVersion()
• asUrl()
• asEndpoint()

node()

node(string $graphNodeName): FQB

Returns a new mutable instance of the FQB entity. Any valid Graph node or endpoint on the Graph API can be passed to node().

$userNode = $fqb->node('me');

edge()

node(string $edgeName): GraphEdge

Returns an mutable instance of GraphEdge entity to be passed to the FQB::fields() method.

$photosEdge = $fqb->edge('photos');

fields()

fields(mixed $fieldNameOrEdge[, mixed $fieldNameOrEdge[, ...]]): FQB

Set the fields and edges for a GraphNode or GraphEdge entity. The fields and edges can be passed as an array or list of arguments.

$edge = $fqb->edge('some_edge')->fields(['field_one', 'field_two']);
$node = $fqb->node('some_node')->fields('my_field', 'my_other_field', $edge);

modifiers()

modifiers(array $modifiers): FQB

Some endpoints of the Graph API support additional parameters called "modifiers".

An example endpoint that supports modifiers is the /{object-id}/comments edge.

// Order the comments in chronological order
$commentsEdge = $fqb->edge('comments')->modifiers(['filter' => 'stream']);
$request = $fqb->node('1044180305609983')->fields('name', $commentsEdge);

limit()

limit(int $numberOfResultsToReturn): FQB

You can specify the number of results the Graph API should return from an edge with the limit() method.

$edge = $fqb->edge('photos')->limit(7);

Since the "limit" functionality is just a modifier in the Graph API, the limit() method is a convenience method for sending the limit param to the modifiers() method. So the same functionality could be expressed as:

$edge = $fqb->edge('photos')->modifiers(['limit' => 7]);

accessToken()

accessToken(string $accessToken): FQB

You can set the access token for a specific request with the accessToken() method.

$request = $fqb->node('BradfordWhelanPhotography')->accessToken('foo-token');

echo $request->asEndpoint();
# /BradfordWhelanPhotography?access_token=foo-token

graphVersion()

graphVersion(string $graphApiVersion): FQB

You can set the Graph version URL prefix for a specific request with the graphVersion() method.

$request = $fqb->node('me')->graphVersion('v3.1');

echo $request->asEndpoint();
# /v3.1/me

asUrl()

asUrl(): string

You can obtain the generated request as a full URL using the asUrl() method.

$request = $fqb->node('me');

echo $request->asUrl();
# https://graph.facebook.com/me

The magic method __toString() is a alias to the asUrl() method so casting the FQB instance as a string will perform the same action.

$request = $fqb->node('me');

echo (string) $request;
# https://graph.facebook.com/me

asEndpoint()

asEndpoint(): string

The asEndpoint() is identical to the asUrl() method except that it will return the URL without the Graph API hostname prefixed to it.

$request = $fqb->node('me');

echo $request->asEndpoint();
# /me

This is particularly handy for working with the official Facebook PHP SDK which will automatically prefix the Graph hostname to the URL for you.

Handling the response

Responses will vary depending on what HTTP client you're using to interface with the Graph API.

Responses with the Facebook PHP SDK

All responses from the get(), post(), and delete() methods return a Facebook\FacebookResponse from the native Facebook PHP SDK.

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

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

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

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

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

$userNode = $response->getGraphUser();

// Access properties like an array
$email = $userNode['email'];

// Get data as array
$userNodeAsArray = $userNode->asArray();

// Get data as JSON string
$userNodeAsJson = $userNode->asJson();

// Iterate over the /photos edge
foreach ($userNode['photos'] as $photo) {
    // . . .
}

// Morph the data with a closure
$userNode['photos']->each(function ($value) {
    $value->new_height = $value->height + 22;
});

See the official documentation for more information on the FacebookResponse entity.

Responses with native PHP

If you're using file_get_contents() to send requests to the Graph API, the responses will be a string of JSON from the Graph API. You can decode the JSON responses to a plain-old PHP array.

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

$request = $fqb->node('4')
               ->fields(['id', 'name'])
               ->accessToken('user-access-token');

echo $request;
# https://graph.facebook.com/4?access_token=user-access-token&fields=id,name

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

$data = json_decode($response, true);

var_dump($data);
# array(2) { ["id"]=> string(1) "4" ["name"]=> string(15) "Mark Zuckerberg" }

If there was an error response from the Graph API, file_get_contents() will return false and raise a warning. This can be problematic since the Graph API returns error details in the body of the response.

To get the error response data we need to tell file_get_contents() to return the response body even when the response contains an error HTTP status code. We can do this by setting ignore_errors to true with the stream_context_create() function.

You can also investigate the error response further by examining the response headers. The headers are stored in the $http_response_header variable which gets set automatically by file_get_contents().

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

$request = $fqb->node('Some-Invalid-Node')->accessToken('user-access-token');

echo $request;
# https://graph.facebook.com/Some-Invalid-Node?access_token=user-access-token

$context = stream_context_create(['http' => ['ignore_errors' => true]]);
$response = file_get_contents((string) $request, null, $context);

$data = json_decode($response, true);
var_dump($data);
/*
array(1) {
  ["error"]=>
  array(4) {
    ["message"]=>
    string(27) "Invalid OAuth access token."
    ["type"]=>
    string(14) "OAuthException"
    ["code"]=>
    int(190)
    ["fbtrace_id"]=>
    string(11) "A8oB9BtqtZ4"
  }
}
*/

var_dump($http_response_header);
/*
array(14) {
  [0]=>
  string(24) "HTTP/1.1 400 Bad Request"
  [1]=>
  string(89) "WWW-Authenticate: OAuth "Facebook Platform" "invalid_token" "Invalid OAuth access token.""
  [2]=>
  string(30) "Access-Control-Allow-Origin: *"
  [3]=>
  string(44) "Content-Type: text/javascript; charset=UTF-8"
  [4]=>
  string(26) "X-FB-Trace-ID: h8oB7BtrtZ3"
  [5]=>
  string(17) "X-FB-Rev: 4971439"
  [6]=>
  string(16) "Pragma: no-cache"
  [7]=>
  string(23) "Cache-Control: no-store"
  [8]=>
  string(38) "Expires: Sat, 01 Jan 2000 00:00:00 GMT"
  [9]=>
  string(21) "Vary: Accept-Encoding"
  [10]=>
  string(100) "X-FB-Debug: FOOE54KJadh9P2HOSUlSFQmNEEf/9CF4ZtgZQ=="
  [11]=>
  string(35) "Date: Fri, 09 Oct 2015 04:43:44 GMT"
  [12]=>
  string(17) "Connection: close"
  [13]=>
  string(19) "Content-Length: 113"
}
*/

Testing

Just run phpunit from the root directory of this project.

$ ./vendor/bin/phpunit

Contributing

Please see CONTRIBUTING for details.

CHANGELOG

Please see CHANGELOG for history.

Credits

• Sammy Kaye Powers
• All Contributors

License

The MIT License (MIT). Please see License File for more information.## License

Security

If you find a security exploit in this library, please notify the project maintainer privately to get the issue resolved.