Facebook has announced and released a new PHP SDK to use on the platform, making significant changes to the way developers can access the API and the new Graph API 2.0. The new PHP SDK splits the functions into multiple classes, so you only need to include the classes you need.

Basic Example

In essence, making API calls and getting data has changed significantly. Just look at the sample code below which asks the user to login and prints their profile data:

<?php
// include required files form Facebook SDK
require_once( 'Facebook/HttpClients/FacebookHttpable.php' );
require_once( 'Facebook/HttpClients/FacebookCurl.php' );
require_once( 'Facebook/HttpClients/FacebookCurlHttpClient.php' );
require_once( 'Facebook/Entities/AccessToken.php' );
require_once( 'Facebook/Entities/SignedRequest.php' );
require_once( 'Facebook/FacebookSession.php' );
require_once( 'Facebook/FacebookRedirectLoginHelper.php' );
require_once( 'Facebook/FacebookRequest.php' );
require_once( 'Facebook/FacebookResponse.php' );
require_once( 'Facebook/FacebookSDKException.php' );
require_once( 'Facebook/FacebookRequestException.php' );
require_once( 'Facebook/FacebookOtherException.php' );
require_once( 'Facebook/FacebookAuthorizationException.php' );
require_once( 'Facebook/GraphObject.php' );
require_once( 'Facebook/GraphSessionInfo.php' );
use Facebook\HttpClients\FacebookHttpable;
use Facebook\HttpClients\FacebookCurl;
use Facebook\HttpClients\FacebookCurlHttpClient;
use Facebook\Entities\AccessToken;
use Facebook\Entities\SignedRequest;
use Facebook\FacebookSession;
use Facebook\FacebookRedirectLoginHelper;
use Facebook\FacebookRequest;
use Facebook\FacebookResponse;
use Facebook\FacebookSDKException;
use Facebook\FacebookRequestException;
use Facebook\FacebookOtherException;
use Facebook\FacebookAuthorizationException;
use Facebook\GraphObject;
use Facebook\GraphSessionInfo;
// start session
session_start();
// init app with app id and secret
FacebookSession::setDefaultApplication( 'xxx','yyy' );
// login helper with redirect_uri
$helper = new FacebookRedirectLoginHelper( 'http://yourwebsite.com/app/' );
// see if a existing session exists
if ( isset( $_SESSION ) && isset( $_SESSION['fb_token'] ) ) {
// create new session from saved access_token
$session = new FacebookSession( $_SESSION['fb_token'] );
// validate the access_token to make sure it's still valid
try {
if ( !$session->validate() ) {
$session = null;
}
} catch ( Exception $e ) {
// catch any exceptions
$session = null;
}
}
if ( !isset( $session ) || $session === null ) {
// no session exists
try {
$session = $helper->getSessionFromRedirect();
} catch( FacebookRequestException $ex ) {
// When Facebook returns an error
// handle this better in production code
print_r( $ex );
} catch( Exception $ex ) {
// When validation fails or other local issues
// handle this better in production code
print_r( $ex );
}
}
// see if we have a session
if ( isset( $session ) ) {
// save the session
$_SESSION['fb_token'] = $session->getToken();
// create a session using saved token or the new one we generated at login
$session = new FacebookSession( $session->getToken() );
// graph api request for user data
$request = new FacebookRequest( $session, 'GET', '/me' );
$response = $request->execute();
// get response
$graphObject = $response->getGraphObject()->asArray();
// print profile data
echo '<pre>' . print_r( $graphObject, 1 ) . '</pre>';
// print logout url using session and redirect_uri (logout.php page should destroy the session)
echo '<a href="' . $helper->getLogoutUrl( $session, 'http://yourwebsite.com/app/logout.php' ) . '">Logout</a>';
} else {
// show login url
echo '<a href="' . $helper->getLoginUrl( array( 'email', 'user_friends' ) ) . '">Login</a>';
}
view raw fb_4.0.x.php hosted with ❤ by GitHub

You now need to include each individual class you require (require_once), set the namespace alias (use) and then calling the functions you need to achieve login and retrieval of API response.

Chaining

The good thing is that the code can be reduced from the example above using chaining. From the example above, you can turn lines 92-95 into just one (large) line. Take this example:

<?php
// turn this:
$request = new FacebookRequest( $session, 'GET', '/me' );
$response = $request->execute();
$graphObject = $response->getGraphObject();
// into this:
$graphObject = (new FacebookRequest( $session, 'GET', '/me' ))->execute()->getGraphObject()->asArray();

The new SDK will definitely take a while to get used to. In fact, the new documentation already has a few errors in it that makes it difficult to even get started…

Additional Permissions / Scope

If your application needs additional permissions from the user, you can pass these in as an array to the $helper->getLoginUrl() function. The first parameter takes an array of permissions like the example below:

<?php
// include code from https://gist.github.com/niraj-shah/ab1c74ad83df172e6075
// generate login url with scope, each permission as element in array
$loginUrl = $helper->getLoginUrl( array( 'email', 'user_friends' ) );
// output login link
echo '<a href="' . $loginUrl . '">Login</a>';

Note: The Facebook PHP SDK 4.0.0 contains more classes than used in the example above, but I’ve included the minimum number needed to achieve login and retrieval of profile information.

Logout Page

For those asking about how to log a user out from your application, you must clear the session or delete any cookies you set. In my example, the following is required on the logout.php page to clear the user’s session.

<?php
// start session
session_start();
// kill the session
session_destroy();
// redirect back to website home
header( 'Location: http://yourwebsite.com/login' );
view raw logout.php hosted with ❤ by GitHub

Update #1

8th May 2014: The original code in this post has been updated to include session management. The new code now remembers any saved access_tokens, validates the token and makes an API call without asking the user to login again. The code works for the changes included in Facebook PHP SDK v4.0.1 and v4.0.2. The new code also includes an extra line to generate the logout link for the user.

You can see the changes to the code here.


Update #2

21st May 2014: Facebook has yet again updated the Facebook PHP SDK, this time to version v4.0.5. The new changes are significant, adding a number of new files that are required for the Facebook SDK to work. I’ve updated my sample code yet again to account for these changes.

You can see the changes to the code here.

27th May 2014: Newly released version v4.0.6 continues to work with the above sample code.


Update #3

10th June 2014: Facebook has updated the PHP SDK to version v4.0.8. The new changes mode some of the classes into a sub-folder, breaking existing code. The below snipped shows how the class includes and use statements needs to be changes:

<?php
// Facebook PHP SDK v4.0.8
// path of these files have changes
require_once( 'Facebook/HttpClients/FacebookHttpable.php' );
require_once( 'Facebook/HttpClients/FacebookCurl.php' );
require_once( 'Facebook/HttpClients/FacebookCurlHttpClient.php' );
require_once( 'Facebook/Entities/AccessToken.php' );
require_once( 'Facebook/Entities/SignedRequest.php' );
// other files remain the same
require_once( 'Facebook/FacebookSession.php' );
require_once( 'Facebook/FacebookRedirectLoginHelper.php' );
require_once( 'Facebook/FacebookRequest.php' );
require_once( 'Facebook/FacebookResponse.php' );
require_once( 'Facebook/FacebookSDKException.php' );
require_once( 'Facebook/FacebookRequestException.php' );
require_once( 'Facebook/FacebookOtherException.php' );
require_once( 'Facebook/FacebookAuthorizationException.php' );
require_once( 'Facebook/GraphObject.php' );
require_once( 'Facebook/GraphSessionInfo.php' );
// path of these files have changes
use Facebook\HttpClients\FacebookHttpable;
use Facebook\HttpClients\FacebookCurl;
use Facebook\HttpClients\FacebookCurlHttpClient;
use Facebook\Entities\AccessToken;
use Facebook\Entities\SignedRequest;
// other files remain the same
use Facebook\FacebookSession;
use Facebook\FacebookRedirectLoginHelper;
use Facebook\FacebookRequest;
use Facebook\FacebookResponse;
use Facebook\FacebookSDKException;
use Facebook\FacebookRequestException;
use Facebook\FacebookOtherException;
use Facebook\FacebookAuthorizationException;
use Facebook\GraphObject;
use Facebook\GraphSessionInfo;

11th June 2014: New tutorial on how to create Facebook Tab Apps has been added. Required Facebook PHP SDK 4.0.7 or later.


Update #4

27th June 2014: I’ve made a change to the initial code to deal with session errors. Essentially, I’ve changed the first <code>IF…ELSE</code> statement into two separate <code>IF</code> statements to deal with session errors, like expired sessions. You can see the changes separately here.

Facebook has also made further changes to the SDK but failed to tag the new version as v4.0.9. Therefore my modifications in Update 3 has been updated to include the further file changes in the same version (v4.0.8). You can see the modifications separately here.


Update #5

27th October 2014: Added logout.php code due to multiple requests.