Client Library Primer

The official client libraries written by Facebook are of the PHP and Java variety. Other language libraries are listed on the Facebook developers web site, but in the interest of simplicity, I’ll cover only the PHP library (specifically the PHP 5 library). If you’re working with other languages, most of the concepts should be the same, but depending on how the developer who wrote the library chose to implement certain elements (and the characteristics of the language the libraries are being implemented in), the way methods are called and named might be slightly different. As a word of warning, some libraries are better documented than others; some have web sites replete with example code, and others have just a link for a download. If you run into a problem and you can’t get help with your language-specific version, take a look at the documentation for the “official” client libraries for PHP or Java.

Facebook’s PHP client library consists of two main object classes, Facebook (in facebook.php) and FacebookRestClient (in facebookapi_php5_restlib.php). As you might expect, the FacebookRestClient class abstracts interactions with Facebook’s API. The Facebook class utilizes the FacebookRestClient class’s methods to further abstract common interactions with the Facebook platform. For instance, instead of writing a procedure to require a user to have a session key to work with your application, the Facebook object has a method named require_login() that checks for the session key and, if it doesn’t find one, redirects the user to Facebook to perform the authentication and then returns the user to your application.

You use the classes just like any other PHP class with require_once (or your other favorite way to create objects):

<?php

/**

* Include the Facebook PHP client library

*/

require_once('<path_to_client_library>/facebook.php');

/**

* Set your API and secret keys

*/

$api_key = '<your_api_key>';

$secret_key = '<your_secret_key>';

/**

* Initialize a new instance of the Facebook client object

*/

$facebook = new Facebook($api_key, $secret_key);

?>

Your API and secret keys are assigned to you in your My Applications portion of Facebook’s Developer application (http://www.facebook.com/developers/apps.php). Once instantiated, the Facebook client libraries make it easy to interact with the Facebook platform.

If you actually look at the code in the library, you’ll notice that it contains a few different classes. For instance, when you create a Facebook object, that class is including a library to make the REST calls (facebookapi_php5_restlib.php). If you are using PHP to write a desktop application, the main change is that you would use the facebook_desktop.php file, which extends the Facebook object but is better suited to desktop applications. The facebookapi_php5_restlib.php file is the real workhorse for your application and is where you will find most of the functions you will use in your application.

One nice aspect is that the developers of the Facebook platform used phpDoc conventions, so generating complete documentation for the platform is relatively simple. If you don’t have a version of PhpDocumentor, you can download it from SourceForge at http://sourceforge.net/projects/phpdocu/ or use PEAR to install it: pear install PhpDocumentor

PEAR should install a new script that you can call from the command-line script, which you then can call to create the documentation: phpdoc -t /path/to/output -d /path/to/facebook_client_library -pp on –ti Facebook

Client Documentation
This line will set the output directory (-t), take a look at the client library path (-d ), parse private functions within the code (-pp), set an HTML title of “Facebook Client Documentation” (-ti), and then output the results in HTML using frames. There are many more options for producing documentation, but these options will produce very useful documentation while you develop your Facebook application. For more information about using this tool, check out the phpDocumentor web site at http://www.phpdoc.org/.