[cvs] [Wiki] changed: Doc/Dev/Horde_Service_Facebook

[Michael Rubinsky]

mrubinsk  Sun, 01 Mar 2009 10:35:54 -0500

Modified page: http://wiki.horde.org/Doc/Dev/Horde_Service_Facebook
New Revision:  1.5
Change log:  Start fleshing out the rest of the docs

@@ -24,8 +24,10 @@
  $facebook = new Horde_Service_Facebook($key, $secret, $context);
  </code>

  ++ Authentication
+http://wiki.developers.facebook.com/index.php/Authorizing_Applications
+
  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:

@@ -83,8 +85,9 @@

  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
+http://wiki.developers.facebook.com/index.php/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">
@@ -107,4 +110,38 @@
  // 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)));
  </code>
+
+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(
+                             
Horde_Service_Facebook_Auth::EXTEND_PERMS_STATUSUPDATE,
+                            $uid);
+if ($haveStatusUpdatePerm) {
+  // Display input box
+} else {
+  $url = $facebook->auth->getExtendedPermsUrl(
+             Horde_Service_Facebook_Auth::EXTEND_PERMS_STATUSUPDATE,
+             'http://callbackurl/for/success',
+             'http://callbackurl/for/failure');
+  echo '<a href="' . $url . '">Allow application to update status</a>';
+}
+</code>
+
+++ 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.');
+</code>
+
++++ Horde_Service_Facebook_Friends
++++ Horde_Service_Facebook_Notifications
++++ Horde_Service_Facebook_Photos
+
+++ Batch Requests
+++ FQL Queries