sammyk/facebookquerybuilder

A query builder for nested requests in the Facebook Graph API.

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.

facebookquerybuilder's Issues

Make PSR-2 Compliant

This is some low-hanging fruit for anyone who wants to get involved! :)

Make the code PSR-2 Compliant.

Possible to retrieve metadata?

The graph API supports a request variable, metadata which brings back extra information about the object.

/me?fields=id,email&metadata=1

Is there a way to retrieve this info using this library?

In my case I'm specifically looking for the type of the object, and as far as I can tell this is the only way to do so.

Trying to use it with facebook php sdk by the following error is coming up on composer

Think it has to be last stable and not dev-master. I've already included facebook sdk on my composer.json.

  Problem 1
    - sammyk/facebook-query-builder 1.0.1 requires facebook/php-sdk-v4 dev-master -> no matching package found.
    - sammyk/facebook-query-builder 1.0.0 requires facebook/php-sdk-v4 dev-master -> no matching package found.
    - Installation request for sammyk/facebook-query-builder 1.0.* -> satisfiable by sammyk/facebook-query-builder[1.0.0, 1.0.1].

Potential causes:
 - A typo in the package name
 - The package is not available in a stable-enough version according to your minimum-stability setting
   see <https://groups.google.com/d/topic/composer-dev/_g3ASeIFlrc/discussion> for more details.

Read <http://getcomposer.org/doc/articles/troubleshooting.md> for further common problems.

[Question] Pagination

Hi
How can I make request for next page of results?
I need to get all user's likes and I'm getting only 25 without setting limit and with setting limit I can get max 100 on one request.
Thanks for your help.

Debug switch?

Is there any debug switch, to see full answer from Graph API?

$fb = App::make('facebook-query-builder');
$fb->setAccessToken('CAAIt8ie86xwBALP1tdkYTSctlj9dBc...');
$user = $fb->search('Bill', 'user')->get();

I don't know whats wrong, because all requests returns same error "Graph returned an error response."

Compatibility with Graph 2.1

A TODO list for Graph 2.1 compatibility.

• Updated nested requests syntax

[2.0] Refactor TODO list

TODO list for version 2.0.

• Update to Facebook SDK 4.1
• Remove dependencies on statics
• Consider multi-id-request support (see #16)
• Update docs

This will be a big breaking change upgrade but it'll be for the better. Working with multiple apps will be easier and since SDK 4.1 is hella better, there will be more fallbacks to their native objects. :)

[Feature request] Support for multi-id-lookup

A request to support multi-id-lookup.

Currently I have to use this work around to make multi-id-lookup requests.

$get = '/?ids={id-one},{id-two}&fields=id,name';
$object = Facebook::object($get)->get();

It would be great if you can make it this way...

$get = '/?ids={id-one},{id-two}';
$object = Facebook::object($get)->fields('id', 'name')->get();

or may be this way...

$object = Facebook::object('?ids')->ids->({id-one},{id-two})->fields('id', 'name')->get();

Can i do this query using Graph API?

Hello i would like to know if there is possible to run this query using Fracebook Graph API.

Can i get ALL the Facebook Pages, when the category of the facebook page, is Actor?

For example, something like this :

$c = 'actor';
 $fqb->edge('pages')->fields('category', $c);

If it possibe to this?

getGraphList() method

I was trying to use your pagination example without offset, but I get this error: Call to undefined method SammyK\FacebookQueryBuilder\GraphCollection::getGraphList() in /var/www/html/script/request.php on line 209
I actually checked in the GraphCollection Class and I couldn't find that method. Any idea how to solve this?
This is my FQB request:

$links = $fqb->object('me/links')
->fields('id','comments','likes')
->with(['offset' => $offset,
'since'=>1409529600])
->limit($limit)
->get();

Cheers

Save access_token to the users table?

Also, I have a user logging in fine and saving all of their info (id, name, email, etc) to the DB, but it does not seem to be saving the access_token? Isn't it supposed to be? I am not sure why it isn't saving that portion in the DB...I can't tell if it is a bug, or something I need to configure?

uploaded photos

i can bring the uploaded photos, is this ok?

Facebook::extend('getUserPhotosUpload', function($facebook)
{

$uploaded = $facebook->edge('uploaded')->fields('id')->limit(5);
return $facebook->object('me/photos')->fields($uploaded)->get();

});

isLongLived

Hi i was checking the isLongLived function and realize that from the start return false, so it always extend the token.

i check the expires_at and it issets at 1970

Timezone is accidentally overridden

Hey,

The following line overrides my timezone even though it has already been set with date_default_timezone_set

https://github.com/SammyK/FacebookQueryBuilder/blob/master/src/FQB.php#L7

Mathias

Example on how to obtain a Page Access Token

Hello SammyK,

Firstly thanks for all this great work that you are putting into this.

Is it possible to show an example on how to obtain a page access token ?

What i was able to do is :

1. Request user access token with manage_page permissions
2. Extend token to long lived one

Now i know that i have to use that token with a GET on 'me/accounts' but i just cant find out how...

Thanks!

Does it work with latest Graph versions and latest Graph PHP SDK?

Does this work with latest Graph versions (v9.0, v10.0) and latest Facebook Graph SDK (v5.7.0)?

"expires_at" bug?

I am just starting out with the Facebook API, so I am definitely just in the learning phase. I did find what seems to be a bug:

AccessToken.php > extend()

$expires_at = isset($data['expires_at']) ? $data['expires_at'] : 0;
should be
$expires_at = isset($data['expires']) ? $data['expires'] : 0;

If you look at $data that "expires" is the actual name of the key.

But even after I changed this it is still not converting the date correctly for the $token.
It is showing the expires_at date as public 'date' => string '1970-03-01 23:09:46.000000'

friends

have you been able to bring the list of friends? i try but it does not work

i did request for permission of 'user_friends'.