6.0.0-git
2024-03-29

Diff for Doc/Dev/Horde_Service_Facebook between 2 and 3

[[toc]]



+ 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);

</code>



++ 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 thevarious 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();

if ($haveSession) {

    $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.

$facebook->users->getLoggedInUser();

</code>



If you do not have a valid session you will have to ask the user to log into Facebook:



<code type="php">

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

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

</code>



This link will take the user to a page that will first ask them to login, and then requests permission for you application to interface with their Facebook profile. Once that happens, Facebook will redirect back to your callbackurl. Once back on your callback page, you will need to capture the values that Facebook has sent back to you. The same validateSession() method takes care of that.



<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.

$facebook->auth->validateSession(true);



// After we call this method, if it's successful we will have

// values for user and session.

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

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



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

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

</code>



At this point you could store the uid and sid locally, and use them to manually set up the session instead 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();

</code>





The session key returned by Facebook at this point would only be good until the user logs out.  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.



<code type="php">



</code>