Facebook Query Builder

An elegant way to send requests to the Facebook Graph API

May 14, 2014

Working with Facebook's Graph API has never been easier thanks to my just-released composer package, Facebook Query Builder.

What is it?

Inspired by Laravel's Query Builder which is used to easily interface with databases, Facebook Query Builder provides an easy API to interface with Graph.

You can install it using composer.

{
    "require": {
        "sammyk/facebook-query-builder": "1.0.*"
    }
}

View the documentation, source code and contribute at https://github.com/SammyK/FacebookQueryBuilder.

How easy is it?

Before a single line of code was written for Facebook Query Builder, I designed the API. I wanted a clear and concise syntax. As a result, after setting a little config and newing up a FQB object, you can do stuff like this:

$user_profile = $fqb->object('me')->get();

That will return a GraphObject collection of the logged in user's profile.

By contrast, this is how you do the same request to Graph working directly with Facebook's new PHP SDK v4:

$user_profile = (new FacebookRequest(
    $session, 'GET', '/me'
  ))->execute()->getGraphObject(GraphUser::className());

Can I do more complex things with it?

Yes! ...Geez, I feel like I'm in an infomercial.

I'm building an empire on this little package. An empire that deeply interfaces with Facebook. So I needed it to be powerful and efficient. Enter nested requests.

Nested requests, or "field expansion" let you get a whole lot of data from a bunch of different objects with just one request to Graph.

The syntax looks like this:

/{node-id}?fields={first-level}.fields({second-level})

So you can pull in the logged in user's name & latest 5 photos they are tagged in with one query.

/me?fields=name,photos.limit(5)

Pretty cool! But what if you had something more complex? Like say you wanted get the following info on a user in one call.

Believe it or not, that can be done with just one graph query! Ready for the URL? Hold your breath...

/me?fields=name,updated_time,photos.limit(5).fields(name,source),likes.limit(3).fields(name,link),events.limit(4).fields(name,start_time,end_time,photos.limit(2).fields(name,source))

Yikes! And the deeper you go, the more unreadable that becomes. Try maintaining that in your project over the years!

It's all about the edges

In Facebook nomenclature, an endpoint on the Graph API is called an "edge". And Facebook Query Builder adopts the same terminology.

This is how you write that complex Graph request above in Facebook Query Builder.

// Get first 5 photos the user is tagged in
$photos_user_tagged_in = $fqb
    ->edge('photos')
    ->fields('name', 'source')
    ->limit(5);

// Get first 3 pages this user likes
$pages_user_likes = $fqb
    ->edge('likes')
    ->fields('name', 'link')
    ->limit(3);

// Get first 4 events that this user is attending
// And first 2 photos from each event
$event_photos = $fqb
    ->edge('photos')
    ->fields('name', 'source')
    ->limit(2);
$events_user_attending = $fqb
    ->edge('events')
    ->fields('name', 'start_time', 'end_time', $event_photos)
    ->limit(4);

// Get the logged in user's name, last profile update time, and all those edges
$user_data = $fqb->object('me')
    ->fields('name', 'updated_time', $photos_user_tagged_in, $pages_user_likes, $events_user_attending);
    ->get();

You can see the full implementation of this example in more from the /examples directory.

It uses the latest v4 SDK from Facebook

Oh, and Facebook Query Builder leans on the latest cutting-edge code that Facebook has to offer. It's built on Facebook's brand new PHP SDK v4 which is getting better by the day thanks to a new commitment from Facebook to make their PHP SDK not suck and of course a little help from my friends.

Let me know what you think!

I'd love to get your feedback on this brand new package! So hit me up on GitHub. And feel free to fork the repo and start taking advantage of everything Graph has to offer!

If you found this guide helpful, say, "Hi" on twitter! I'd love to hear from you. :)