Decoding the new Facebook PHP SDK v4.0

Facebook SDK v4.0 for PHP - what you need to know

May 02, 2014

At this year's F8 2014, Facebook announced many new changes that will largely affect us developers who develop on the Facebook platform. In fact, you'll need to start upgrading your apps pretty soon. Specifically, you've got until April 30, 2015 to upgrade all your apps.

If you missed the livestream, Facebook posted all the talks.

Some of the most notable F8 2014 announcements...

And perhaps the most impactful announcement for us PHP developers is the brand new PHP SDK v4.0.

The old SDK sucked

For years Facebook treated their old PHP SDK like a red-headed step child. It lacked a proper project maintainer and pull requests from the community were ignored for years. Even with Facebook's commitment to contribute to the open source community which really kicked off back in 2009/2010, the PHP SDK was still largely ignored.

And what's worse, the old SDK was full of bugs and nearly impossible to extend forcing many developers (including myself) to write their own code to interface with the Graph API.

Fosco to the rescue!

After acquiring Parse, Facebook also acquired PHP SDK's savior - Fosco who now leads the development of the new SDK. I had the pleasure of meeting Fosco at Facebook HQ a few days before F8. From my visit I got the sense that Facebook has recommitted to making the PHP SDK not suck anymore. And they seem to be very open to community involvement. Good news for us!

The good

The new SDK was completely rewritten from scratch and embraces more of the PHP 5.4+ features that really place it in a great position to become something awesome.

Composer support & autoloading

The new SDK lives at a new project url on Packagist so you'll need to update your composer.json.

    "require" : {
        "facebook/php-sdk-v4" : "4.0.*"

Just a heads up - you especially don't want to require dev-master on production as there are going to be some serious refactoring soon. In fact, within 24 hours of its release, the SDK's GitHib repo already had 20+ issues and pull requests. Many of them were breaking changes.

Better object-oriented programming

The new SDK is actually broken up into 18 classes. By contrast, the old SDK had just 3 classes.

It's namespaced

Instead of dumping all the classes into the global namespace like the old SDK, the new SDK prefixes all the classes with the \Facebook namespace.

The Bad

The new SDK isn't all dandelions and rainbows. There are some pretty big issues that will hopefully be addressed soon.

The API is not very readable

When I design a package, I start with writing the API in a markdown document. I want to design how I interface with the package before writing a single line of code.

For example if I wanted to get a user's ID and name, I would like to interface with the SDK like this:

use Facebook\Sdk\Facebook;


$user = Facebook::object('user')->fields(['id', 'name'])->get();

But with this new SDK, to do the same thing you have to do this:

use Facebook\FacebookSession;
use Facebook\FacebookRequest;
use Facebook\GraphUser;

$session = new FacebookSession('access-token-here');

$user = (new FacebookRequest(
      $session, 'GET', '/me?fields=id,name'

I'm really going to be pushing for a more readable API on the GitHub repo after we address the more pressing issues.

The nomenclature is a bit confusing

My main beef is with the FacebookSession class. If you had to guess what that did out of context, you'd probably think it was a persistent data handler for the SDK. In fact it handles the access token for making requests to Graph.

Oh, and incase you're wondering, as of writing there is no dedicated persistent data handler for the SDK. I'm trying to change that. :)

The code is not very SOLID

Although the new object-oriented code is a huge step in the right direction, there are still several violations of the SOLID design principles. This just makes it harder to work with especially for extensibility.

Extensibility isn't fun

If you wanted to customize any of the functionality of the SDK, you have to extend the classes with your own custom classes. This is a huge pain in the ass as I've already pointed out on GitHub.

Hopefully the higher-ups will approve the usage of dependency injection and coding to an interface which would make extensibility of the SDK a dream.

You need a test app and internet connection to run tests

The unit tests also include functional tests right out of the box. The tests actually interface with the live Graph API which means in order to run the tests you need to create a test app & enter its credentials into a configuration file. You'll also have to be connected to the internet when you run the tests. This will make testing from an airplane or on a beach in the South Pacific rather difficult.

Unit tests should really be separated from functional or integration tests so that they can all be run in isolation.

Lots of class juggling for the developer

As you saw in the example above, there is a huge responsibility on the developer to really bring all the components of the SDK together. Which means you need to have a pretty in-depth knowledge of the inner-workings of the SDK.

And there are quite a few components to the SDK. If you have a website that uses the Javascript SDK but is also available within the app canvas, you could be juggling up to 10 classes. Not to mention the 8 exception classes.

This issue can be alleviated with a more readable API that I mentioned above. I'm pushing for it! :)


The new PHP SDK v4 is definitely a huge leap in the right direction. And with Fosco on our side, it has a very promising future.

And its future will be made even brighter with your contribution to the GitHub repo. Join me in forking and pull-requesting the hell out of this bad boy!

Oh! And mark your calendars for April 25, 2015. That's when F8 goes main stage again. And Facebook promised and bigger and awesomer venue.

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