Note: If you’re not a programmer, you won’t be much interested in this, though if you do decide to continue reading, it may give you a hint as to why websites are so expensive.

It seems like every website these days has social media integration. On some websites you can simply “Like” something and have it shared on Facebook, while on others they actively pull your information from Twitter to create accounts for you. In some cases, they will even allow you to post custom messages or ask for the authority to autonomously post information to social networks in your name. These things are ubiquitous on the web, especially when it comes to the successful games like Farmville and its ilk.

So how do they do this? Websites utilize a special interface called an API (Application Programming Interface) which allows the website to access information from the server. Some APIs are open and require no authentication, but many, especially those that contain private or sensitive data (such as Facebook), require some sort of authentication. The current standard method of authentication on the web is known as OAuth.

What is OAuth?

OAuth stands for Open Authentication. It’s a method of verifying the identities of those involved in secure transactions. Three-Legged OAuth is the most common, and the process goes something like this:

User: Hey, I want to share this on a service.
Consumer (website): Hey Server, I got a user who wants to use your service.
Server (e.g. Twitter): Great! Give them this Request Token so I know they came from you.
Consumer: OK, click this link and sign into the server with this Request Token and tell Server that you’re okay with this.
User: Hey Server, here’s Consumer’s Request Token and I’m okay with this.
Server: Great! Give this Access Token to the Consumer.
Consumer: Hey Server, I got this Access Token. Is this the right one?
Server: Yep! Have a great day!
Consumer: All right, User. You’re authorized! Let’s share your stuff!

As you can see from the “conversation” above, the server needs to verify the identities of both the User and the Consumer to ensure that both of them are who they say they are. You can read more about it (and how insanely complex and ridiculous it is) at Oauth.net.

The reality

The reality is that OAuth transactions rarely go so smoothly. The reason is that some services such as Twitter use the full OAuth process, while others such as Facebook only use parts of the OAuth process. At any rate, implementing OAuth is often a huge headache to many programmers.

My Solution

I’ve written a handful of classes that you can use to connect to Facebook, Twitter and Google. Basically, I’ve locked down all the code that makes each of these connections possible and encapsulated them into a single file, so that all you really need to do is include the file, add a few lines of code in your existing website, and you’re good to go.

OAuth

The OAuth class is not of my own design. Honestly, I can’t remember where I got it, and the guy didn’t leave comments in the code indicating that he was the author. To whomever wrote this, if you want to let me know, I’ll give you credit.

At any rate, everyone who wants to do OAuth with PHP needs to download this file, and include it in your code, like so:

 include('OAuth.php');

That’s it. Moving on…

Facebook

I’ll start off with Facebook since it’s the most popular social network out there. Facebook kind of does a simpler handshake than the others, and they actually prefer that you use their custom FBML. That kind of stuff is more for people who don’t know much about programming, though, and it allows for really simple Like buttons and other similar widgets. When you use OAuth, you typically want more secure, more detailed information.

First, you need this file. Then you need to include it, of course, like so:

<?php
include('Facebook.class.php');

Second, you will need to register a new Application with Facebook. Once you do so, you will be given a Facebook App ID and a Facebook App Secret. These are very important. They identify your website with Facebook. Think of it as a username and password for your app. YOU DO NOT SHARE YOUR SECRET EVER! (That’s why it’s called a secret).

Once you have those, you need to define them in your code somewhere. You should know the best way to do this, but I generally define constants:

DEFINE("FACEBOOK_APP_ID", "1234567890");
DEFINE("FACEBOOK_APP_SECRET", "abcd1234efgh8910");

Generally on a website like ours there is a button or link that says “Connect to Facebook.” That link should go to a file that will instantiate the Facebook class and connect. Let’s call it “facebook_connect.php”. This file should look like this:

<?php
$callback_url = "http://www.example.com/facebook_callback.php";
$facebook = new Facebook(FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, $callback_url);
$facebook->start();

You can, of course, replace FACEBOOK_APP_ID with $facebook_app_id if you’d rather just store them in variables. Depends on how your code is structured.

The first line sets the callback URL. This is important for Step 2, because it tells Facebook where to send the Access Token. The second line instantiates the Facebook class. It creates the Facebook object, setting the App ID and Secret internally for future use. The third line starts the connection process by redirecting the user to the Authorization page. This is where the User gets to sign in and “Allow” access for the app.

Now that we’ve sent the user to the Authorization URL, we need to create a Callback page for them to come back to.

Create a new file: facebook_callback.php

It should look like this:

<?php
$callback_url = "http://www.example.com/facebook_callback.php";
$facebook = new Facebook(FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, $callback_url);
$access_token = $facebook->callback();

The first line does the same thing as it did earlier. The second line initiates the Callback sequence, which grabs the access token, makes a few more requests to verify its authenticity, and then returns the Access Token into the $access_token variable.

It’s up to you how to save this variable using the method of choice (e.g. database, cookies, session, etc).

Tada. Congratulations! Your user is now connected to Facebook via your web app!

What now?

Now you should have saved the user’s Access Token into a database, cookie or session somehow. This will ensure that you can make requests on behalf of this user from now on. Note: the access token is valid only for THIS user, not for any other.

First, let’s make a generic makeRequest method that will allow us to make a request on behalf of this user without repeating too much code:

function makeRequest($token, $url, $method = "GET", $params = null);
       $token = array("access_token" => $token);
       if(is_array($params)){
	    $params = array_merge($parameters, $token);
       } else {
            $params = $token;
       }
       ksort($params);

       if($method == "GET"){
            foreach($params as $key => $value){
                $url_params[] = $key . '='. ($value);
            }
            $url .= '?'.implode('&',$url_params);
       }
       $ch = curl_init();
       curl_setopt($ch, CURLOPT_URL, $url);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

       if($method == "POST"){
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
       }
       $response = curl_exec($ch);
       curl_close($ch);
       return $response;
}

This is a pretty straightforward class. It makes a cURL request and formats the parameters depending on whether we’re making a GET request or a POST request.

Let’s grab the information about this user from Facebook using this simple code:

$url = "https://graph.facebook.com/me";
$token = "ABC"; // Your stored Access Token for this user
makeRequest($token, $url, "GET");

The first line defines the URL to which we post our request. You can find a huge list of these in the Facebook API Documentation. The second line pulls our Access Token for this user. If you stored it in the database, you’ll have to make a database call to grab it. The third line, of course, uses our generic makeRequest function to make an API call using the above information. Since we don’t have any parameters, and they default to null, we don’t have to include the $params parameter.

The third parameter (“GET”) is important. Some Facebook requests require that you make a GET request (e.g. /me) and some require that you make a POST request (e.g. /me/feed). It depends on whether you’re READING or WRITING. The GET method is a READ action and the POST method is a WRITE action. Keep that in mind. The Facebook Graph API mentions which ones are supported. Anyway, I digress…

But what if we do have parameters? Let’s try posting something to our Facebook wall.

$url = "https://graph.facebook.com/me/feed";
$params = array("message" => "I'm using Brian's OAuth code to post this to Facebook!");
$token = "ABC"; // Your stored Access Token for this user
makeRequest($token, $url, "POST", $params);

You’ll notice there are three changes: I added “/feed” to the end of the URL. This tells Facebook that we want to post to the news feed. I added a line that defines what the parameters are, in this case the “message” is “I’m using Brian’s OAuth code to post this to Facebook!”. Finally, I added the $params parameter to the makeRequest method.

If you now run this code, it should post the message to your Facebook wall.

Here’s the final code in its entirety for you:

facebook_connect.php

<?php
DEFINE("FACEBOOK_APP_ID", "1234567890");
DEFINE("FACEBOOK_APP_SECRET", "abcd1234efgh8910");
include('OAuth.php');
include('Facebook.class.php');
include('functions.php');

$callback_url = "http://www.example.com/facebook_callback.php";
$facebook = new Facebook(FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, $callback_url);
$facebook->start();

facebook_callback.php

<?php
DEFINE("FACEBOOK_APP_ID", "1234567890");
DEFINE("FACEBOOK_APP_SECRET", "abcd1234efgh8910");
include('OAuth.php');
include('Facebook.class.php');
include('functions.php');

$callback_url = "http://www.example.com/facebook_callback.php";
$facebook = new Facebook(FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, $callback_url);
$access_token = $facebook->callback();

// Store $access_token using database call, cookie, or session

functions.php

<? php
function makeRequest($token, $url, $method = "GET", $params = null){
       $token = array("access_token" => $token);

	if(is_array($parameters)){
			$params = array_merge($parameters, $token);
    	} else {
    		$params = $token;
    	}
    	ksort($params);

    	if($method == "GET"){
	    	foreach($params as $key => $value){
	    		$url_params[] = $key . '='. ($value);
	    	}

	    	$url .= '?'.implode('&',$url_params);
		}
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

        if($method == "POST"){
        	curl_setopt($ch, CURLOPT_POST, 1);
        	curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
        }
        $response = curl_exec($ch);
        curl_close($ch);
	return $response;
}

get_facebook_info.php

<?php
DEFINE("FACEBOOK_APP_ID", "1234567890");
DEFINE("FACEBOOK_APP_SECRET", "abcd1234efgh8910");
include('OAuth.php');
include('Facebook.class.php');
include('functions.php');

$url = "https://graph.facebook.com/me";
$token = "ABC"; // Your stored Access Token for this user
$result = makeRequest($token, $url, "GET");

// Convert JSON result to array
$data = json_decode($result);

// Print data to screen
print_r($data);

That should do it. Of course, if you were so inclined, you could have an includes file that automatically includes the OAuth, Facebook and Functions class on every page, eliminating the need to include those each time. My framework does this automatically, so my code winds up having fewer lines than the above. However, in the interests of this tutorial, I’ve included those in each file.

I’ve set up a basic demo for you to look at to see how this works. Check it out here: DEMO.

Tune in next time when I go over how to use Twitter and OAuth using a very similar class.

Any comments, questions or suggestions? Hit me up in the comments below.