Facebook PHP Tutorial

Facebook Is The New Black.

Everyone is talking about Facebook and their new Application Platform:

• Techcrunch – Facebook Launches Facebook Platform; They are the Anti-MySpace
• Mashable – Facebook Powertools: 150+ Apps, Scripts and Add-ons for Facebook
• Digg – The Impact of Facebook’s Platform
• Mashable – Facebook Platform: 30+ Awesome Applications for Facebook
• Valleywag – Developers, beware. Facebook really is the new Microsoft.
• Facebook’s Blog Post on the Facebook Platform
• Inside Facebook – Hottest Facebook Apps: July 28th

And I have to admit I think it’s pretty cool too. So I decided to create an application that uses the Facebook Platform. I’m writing the application in PHP and I thought it might be useful for others to know how to write their own Facebook applications with PHP. So here we are.

What Will I Learn?

I will cover the basics of using the Facebook PHP library and how to get your application started, including:

1. Installing The Facebook Developer Application
2. Downloading The Facebook PHP Client Library
3. Creating Your Application
4. Hello Facebook! Example
5. FBML – Facebook Markup Language
6. Using the Facebook API

Getting Started As A Facebook Developer

The first thing you need of course is a Facebook account. You can sign up for Facebook at www.facebook.com. Once you have your account you’ll need to install the Facebook developer application. This little tool will allow you to generate your application profile and get an API key (more on that later). Once you’ve logged into Facebook visit: www.facebook.com/developers/ or click below to install the developer application:

Add The Facebook Developer Application.

PHP Facebook API Client Library

Facebook has created a nice php library that allows you to use their API without writing a lot of extra code. You can grab the PHP version of the library at developers.facebook.com/resources.php. Download the ‘PHP (4 and 5) Client Library’.

Once you’ve downloaded the library unzip it into a folder that is accessible by your PHP scripts. So you would have something like /php_include_directory/facebook/ and in that folder you will have the entire Facebook PHP Client Library (3 folders: client, footprints, php4client). I’m using PHP5 so my examples will be using the “client” directory of the library. The footprints folder is an example application.

Creating Your Application Profile And API Key

Facebook requires that you register each application you make. Once you’ve logged into Facebook and installed the developer application go to the developer panel (or click here). Inside the developer application click “Set Up New Application”.

Choose a name for your application. This is important because it’s what users will see when they are browsing the application directory. Currently the name field is the only thing used when searching for applications. So it’s doubly important at this point.

Click on “Optional Fields”. Then fill out the Callback Url with the location of your script. This is the public URL on your webserver where the Facebook application will be.

Next fill out the “Canvas Page URL”. This is your application URL within Facebook. For example if the application was called “Makebeta Is Cool” then the application URL could be: “makebeta” which would make the full URL: http://apps.facebook.com/makebeta/.

Check Yes for Can your application be added on Facebook?

You should check the Developer Mode checkbox so that no one can add your application until you are done working on it.

Under Integration Points fill out Side Nav URL with the full Canvas Page URL. In the example above it would be http://apps.facebook.com/makebeta/. This allows users to add your application to their Facebook left side bar navigation.

All of these settings can be changed after the application has been created. But it’s a good idea not to change the Canvas Page URL or Name once you have users that have installed your application.

Further Reading: Starting your First Facebook App: Demystifying Application Form Field by Field

Get the API Key and Secret. You should now see your application listed with a unique API Key and Secret code. You’ll use these within your application.

Hello Facebook!

Let’s create a really simple first application that just says hello to the current Facebook user. Here’s the code for the Hello Facebook! application:

<?php
/* include the PHP Facebook Client Library to help
  with the API calls and make life easy */
require_once('facebook/client/facebook.php');

/* initialize the facebook API with your application API Key
  and Secret */
$facebook = new Facebook(YOUR_API_KEY,YOUR_SECRET_CODE);

/* require the user to be logged into Facebook before
  using the application. If they are not logged in they
  will first be directed to a Facebook login page and then
  back to the application's page. require_login() returns
  the user's unique ID which we will store in fb_user */
$fb_user = $facebook->require_login();

/* now we will say:
  Hello USER_NAME! Welcome to my first application! */
?>

Hello <fb:name uid='<?php echo $fb_user; ?>' useyou='false' possessive='true' />! Welcome to my first application!

<?php

/* We'll also echo some information that will
  help us see what's going on with the Facebook API: */
echo "<pre>Debug:" . print_r($facebook,true) . "</pre>";

?>

So what happens when a user hits the Canvas Page URL (from the example it would be: http://apps.facebook.com/makebeta/)? The require_login() call will produce a screen like this for the user:

If you change require_login() to require_add() the user will get a page that looks like this:

After the user logs into or adds the application they will get the canvas page with the “Hello…” text. It should look something like this:

Facebook Markup Language – FBML

Facebook has provided a bunch of built in tags that will render dynamic data inside your application. All you have to do is include the tags with the correct parameters. In the example above the fb:name tag is used to generate the user’s name on the canvas page. fb:name has a couple of parameters, one of which is uid. In the example above we set uid = $fb_user which is the unique ID of the current user. There are lots of FBML tags you can use, check them all out at: developers.facebook.com/documentation.php?doc=fbml

Facebook API REST-based Interface

The Facebook Client Library provides you with an easy to use wrapper for the Facebook API REST interface. All of the API calls are available under the $facebook->api_client object (after you initiate the $facebook object). Many of the calls will require that the user has either added or logged into the application. Here’s an example call that would retrieve the user’s About Me text from their profile:

$fb_user = $facebook->user;
$about = $facebook->api_client->users_getInfo($fb_user,'about_me');

There are a number of API calls, and a list of them can be found here:
developers.facebook.com/documentation.php

Resources and Further Reading

These are very helpful pieces of information that I highly recommend reading before you get too far into making your Facebook application.

• Basic Facebook Application Architecture
• How URLs Are Handled Within An Application
• Understanding Your Callback Page

And of course the official documentation / developer site:

• Facebook Developers Site
• Facebook Developers Wiki

Other Facebook tutorials and how-to articles:

• Tucows – Getting Started With Facebook Application Development
• 10 Things That Would Have Been Nice to Know When Starting My Facebook Application
• Developing with the Facebook Platform and PHP