sammyk / facebook-query-builder
An elegant and efficient way to generate nested requests for Facebook's Graph API.
Installs: 157 198
Dependents: 0
Suggesters: 0
Security: 0
Stars: 91
Watchers: 10
Forks: 18
Open Issues: 4
Requires
- php: >=5.4.0
Requires (Dev)
- phpunit/phpunit: ~4.0
- squizlabs/php_codesniffer: ~2.0
README
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
- 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:
- Node: A node represents a "real-world thing" on Facebook like a user or a page.
- Edge: An edge is the relationship between two or more nodes. For example a "photo" node would have a "comments" edge.
- 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()
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
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.