Diff for Doc/Dev/Horde_Service_Facebook between 5 and 6


+ Horde_Service_Facebook

Documentation on the Horde_Service_Facebook package.

++ General Info

This library is a general purpose client library for interacting with Facebook's API.  It's primary purpose is to allow other Horde applications to both receive and send content to Facebook.  Before using this library you will need to properly set up a web application with Facebook.  The details to do this are beyond the scope of this entry. You can find specific instructions at http://developers.facebook.com/get_started.php?tab=tutorial.  You will need to know the application api key as well as the application's secret key. You will also need a callback page that Facebook will redirect to after successful authentication events (see below).

Example Code to create an instance of Horde_Service_Facebook:

<code type="php">

$key = 'xxx';

$secret = 'xxx';

// We require a client and request object. We could also

// pass a logger if desired. If you have a Horde_Controller

// instance, you could pass that as 'controller' instead of

// the http_request.

$context = array('http_client' => new Horde_Http_Client(),

                 'http_request' => new Horde_Controller_Request_Http());

$facebook = new Horde_Service_Facebook($key, $secret, $context);


++ Authentication


Authenticating a Facebook application from another web application is not a simple task.  The user needs to first be logged into Facebook, then authorize your application to interact with the user's Facebook profile. In addition, in order to allow the application to interact with Facebook without having to redirect the user to a login for each new session, you will need an infinite session. There are also multiple other 'extended permissions' that Facebook requires to be approved **individually**. It is up to the client application to deal with these requirements. Here is some sample code demonstrating various authentication processes.

First, let's assume that the user has not done anything with your application yet. To check this we could do something like this:

<code type="php">

// See if we have a session (probably from a cookie)

$haveSession = $facebook->auth->validateSession();

    $uid = $facebook->auth->getUser();

    $sid = $facebook->auth->getSessionKey();

// You can always verify the session is good by calling

// this returns the userid that belongs to the current session.


<code type="php">

$url = $facebook->auth->getLoginUrl('http://yourcallbackurl');

echo '<a href="' . $url . '">Login to Facebook</a>';


<code type="php">

// The true parameter here is telling the library to ignore any

// seemingly valid sessions obtained from a cookie. This is to prevent

// an existing cookie (perhaps by another user on a shared computer) from

// interfering with this process.


$uid = $facebook->auth->getUser();

$sid = $facebook->auth->getSessionKey();

// You can also check that any user has accepted your application

$isAppUser = $facebook->users->isAppUser($uid);


At this point you could store the uid and sid locally, so that next time the user logs into your application, you can use them to manually set up the session instead of making a call to Facebook.

<code type="php">

// Get userAt this point you could store the uid and sid locally, so that next time the user logs into your application, you can use them to manually set up the session from storageinstead of making a call to Facebook.

<code type="php">

// Get user and session from storage

$uid = 'xxx';

$sid = 'xxx';

// Tell facebook client about it.

$facebook->auth->setUser($uid, $sid);

// Verify the session is still good by calling a method that requires a valid session

$haveSession = $facebook->users->getLoggedInUser();


The session key returned by Facebook at this point would only be good until the user logs out of Facebook.  Your user would have to login again to Facebook for each new session. To overcome this, you have to have the user authorize an extended permission called //offline_access//. Each and every extended permission must be authorized separately.

++ Extended Permissions


To have the user grant an extended permission to your application, such as //offline_access// you need to redirect the user to Facebook's authorize.php page, passing the information that you are requesting.

<code type="php">

$url = $facebook->auth->getExtendedPermsUrl(



echo '<a href="' . $url . '">Authorize offline access</a>';

// Again, make sure we ignore cookies since we are requesting

// a new, infinite, session_key


$uid = $facebook->auth->getUser();

// You *must* store these values for later use. You will

// *not* be able to obtain the session_key from Facebook again.

$prefs->setValue('facebook', serialize(array('uid' => $uid, 'sid' => $sid)));


The application can now interact with this user's Facebook account without having the user be logged into Facebook.  You just need to manually set up the session by calling //setUser()// as described above.

There will be times when you may need to know if a user has already allowed certain extended permissions. For example, the //status_update// permission is required in order to allow the user's status to updated via the API.  You could check that the user has the permission and then either show them an input box for status updates or a link to request the permission.

<code type="php">

$haveStatusUpdatePerm = $facebook->users->hasAppPermission(



if ($haveStatusUpdatePerm) {

  // Display input box

} else {

  $url = $facebook->auth->getExtendedPermsUrl(




  echo '<a href="' . $url . '">Allow application to update status</a>';



++ Doing Something Useful - Calling API Methods

The various API calls are seperated into various classes according to the part the Facebook API your interacting with. For example, as you may have noticed that most of the methods we have used so far have been in the Horde_Service_Facebook_Auth class.  The Horde_Service_Facebook object will lazy load the object that you need, so you don't have to worry about creating these classes yourself. There are some things to be aware of before querying any data from a user's Facebook account. First, you absolutely need to be familiar with Facebook's policies on data usage. There are restrictions on what can be shown to users, what can be stored locally and for how long, as well as other issues. You can read more at http://wiki.developers.facebook.com/index.php/Platform_Policy.  You will also find that there are often times more then one way to obtain information. You can make normal API calls or you can use the Facebook Query Language (FQL) a query language **very** similar to SQL.  It is often time more efficient to obtain the data you are after using FQL then to use API calls - especially when multiple API calls would be necessary.  In fact, a number of Facebook's API calls are actually just thin wrappers around the matching FQL query. See http://wiki.developers.facebook.com/index.php/FQL for more information on FQL and see the section below on FQL to see how to make these queries using this library.

+++ Horde_Service_Facebook_Users

<code type="php">

$success = $facebook->users->setStatus('playing around with the Horde_Service_Facebook library again.');


+++ Horde_Service_Facebook_Friends

+++ Horde_Service_Facebook_Notifications

+++ Horde_Service_Facebook_Photos

++ Batch Requests

++ FQL Queries