This is the new Facebook API Wrapper that utilizes the updated Facebook PHP SDK v3.0 .
Each pushing method (By pushing i mean method that pushes data into facebook not retrieving) requires certain user permissions to work properly. In most cases the permission 'publish_stream' is enough but sometimes there are certain operations that require more then that. For example to create user checkins you need the
'publish_checkins' user extended permissions, Referrer to the reference section above to see the list of user permissions and extended permissions.
In the actual class itself the 'FB' class you'll see a property '@permission' which is normally referees to the methods visibility in PHP (public, protected, private) but in this case it will show a list of the required facebook permission to have in order to use it.
Each method both reading and pushing accepts certain parameters. In most cases the first parameter is an array of parameters that specific method accepts, followed by the second parameter which is the user or object id that is set to null by default and is not required.
For example addWallPost($params, $objectId) accepts an array as the first parameter which should have the following keys: message, picture, link, name, caption, description, source, place, tags. Some are required (message, name) others are optional.
Unfortunately facebook does not show which are required and which are not so the more values you set the better.
Second parameter is optional and represents the user id or object id you would like to perform the operation on. In this case the objectId is the user id you would like to post the message on his wall, if you leave it as null it will use the current logged in user as the objectId, if you pass in a number as the second parameter it will try to post the message to that user profile (the user needs to have the required permissions that in this case posting a wall post requires the 'publish_stream' permissions), In other cases/methods the second argument is not the user id but an object id.
For example when you want to add a comment to a certain post you'd use the addComment($params, $objectId) the objectId is the post id (if you have it stored somewhere or you'd just posted a new post on a users wall and you have it's id).
To be certain referrer to the class API documentation to see the method parameters and read the description to see what keys it accepts in the first argument array and what is the objectId referees to in that case.
Inside the 'examples' folder you'll find several php files that show an example of each of the methods provided in the 'FB' class file.
Even though it covered in the actual 'FB' class and each example file shows the way to get the result and see if the operation was successful or not, I'll quickly cover how to check if the operation you tried to perform was successful or not.
This is mostly used when trying to push data as opposed to retrieve data since when retrieving data you'll get an array with the info, if the operation failed the array will be empty.
There are several convenient methods you can use to get the result you'd expect. For instance if we performed an operation for this example purposes we will use addWallPost($params, $objectId).
$wallPost = $facebook->addWallPost(array('message' => 'some message'));
if($facebook->isSuccess()) {
echo 'post created. ID:' . $facebook->getId();
} else {
echo $facebook->getErrorMessage();
}
After performing a certain operation you can check if it was successful or not and getting the info you would like to get by using the following methods:
$facebook->isSuccess() // check if last task was successful $facebook->isError() // check if the last operation failed $facebook->getError() // return an array with the last operation error info $facebook->getErrorCode() // return a string representation of the last error code $facebook->getErrorMessage() // return a string representation of the last error message $facebook->getResult() // return an array of the result from the last operation $facebook->getId() // return the id of the newly created object, usually after performing a push operation you'll get an id
// Require the only class you will be needing require 'FB.php'; // Create our Application instance (replace this with your appId and secret). $facebook = new FB(array( 'appId' => 'xxxxxxxx', // app id 'secret' => 'xxxxxxxx', // app secret 'fileUpload' => true, // optional if you want to allow file uploads, used when uploading photos to albums ));
// Get User ID
$user = $facebook->getUser();
// We may or may not have this data based on whether the user is logged in.
//
// If we have a $user id here, it means we know the user is logged into
// Facebook, but we don't know if the access token is valid. An access
// token is invalid if the user logged out of Facebook.
if ($user) {
try {
// Proceed knowing you have a logged in user who's authenticated.
$user_profile = $facebook->api('/me');
} catch (FacebookApiException $e) {
error_log($e);
$user = null;
}
}
// Login or logout url will be needed depending on current user state.
if ($user) {
$logoutUrl = $facebook->getLogoutUrl();
} else {
$loginUrl = $facebook->getLoginUrl(
array(
'scope' => 'email,offline_access,publish_stream,user_birthday,user_location,user_work_history,user_about_me,user_hometown',
)
);
}
In the above code we check if the user logged in before, if he was then we will have his user id. If he wasn't then we will show him the login url.
The login url accepts an array of parameters the important ones are 'scope' and 'redirect_uri' the former is a comma separated list of permission you would like the user to allow you to access to. The later is the url you would like to redirect the user to after he allows the permissions.
the 'redirect_uri' must be under the same domain name of the application domain name settings that were set when the application was created in the facebook site. Meaning when creating a new application facebook requires you to enter a domain name that will be used with that application lets say domain.com when setting 'redirect_uri' you need to make sure
it is located under the same domain name or sub-domain. if you set 'redirect_uri' as 'afterlogin.domain.com' then it will work if you set it to 'someotherdomain.com/login' this won't work and the user will see an error message when he clicks the login button.
When you choose to set the 'scope' which is the list of permissions you want to get from the user you need to make sure you set all the permission you'll be using if you don't you'll need to show the login button to the user again after adding new permissions to the 'scope' or you won't be able to perform the actions that require those new permissions.
You can clear the user state and by that forcing him to login again and giving those new updated permissions you require.
By default the user access token and data returned after logging in stored in the session, you can though override the methods: setPersistentData, getPersistentData, clearPersistentData, clearAllPersistentData
After logging in you'll get the user access info that will be stored in the session and will look similar to this:
Array
(
[fb_344617158898614_state] => XXXXXXXXXXXXXXX
[fb_340730982629661_code] => xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX
[fb_340730982629661_access_token] => xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX
[fb_340730982629661_user_id] => xxxxxxxxxxxx
)
You might want to store the access token for later use if you want to perform user operations across sessions. You can then use $facebook->getAccessToken() and $facebook->setAccessToken($token);
In the examples below all the get* methods have an objectId as an argument, by default it's null and it will use the current logged in user.
$facebook->getUserInfo(); // get current logged in user public info
$facebook->getUserInfo('xxxxx'); // get xxx user public info
$facebook->getObjectInfo($objectId); // get object public info for example $facebook->getObjectInfo('cocacola');
$operationResult = $facebook->addWallPost($params); // perform operation on the current logged in user
// $operationResult = $facebook->addWallPost($params, $objectId); // perform operation on a certain objectId
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addNote($params); // perform operation on the current logged in user
// $operationResult = $facebook->addNote($params, $objectId); // perform operation on a certain objectId
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addLink($params); // perform operation on the current logged in user
// $operationResult = $facebook->addLink($params, $objectId); // perform operation on a certain objectId
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addComment($params, $objectId); // perform operation on a certain objectId, objectId required
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->like($objectId); // perform operation on a certain objectId, objectId required
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addEvent($params); // perform operation on the current logged in user
// $operationResult = $facebook->addEvent($params, $objectId); // perform operation on a certain objectId
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addAlbum($params); // perform operation on the current logged in user
// $operationResult = $facebook->addAlbum($params, $objectId); // perform operation on a certain objectId
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addPhoto(array('message' => 'some message', 'image' => '@' . FILE_LOCATION), $_POST['albumid'], $objectId); // perform operation on a certain objectId, objectId is required in this case it's the album id
// FILE_LOCATION must be on the server see demo photo.php
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->addCheckin($params); // perform operation on the current logged in user
// $operationResult = $facebook->addCheckin($params, $objectId); // perform operation on a certain objectId
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->eventAttending($objectId); // perform operation on a certain objectId, objectId is required it's the even id
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->eventMaybe($objectId); // perform operation on a certain objectId, objectId is required it's the even id
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->eventDecline($objectId); // perform operation on a certain objectId, objectId is required it's the even id
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$operationResult = $facebook->search($searchQuery, $type); // perform search operation
// searchQuery is the text you would like to search in facebook
// type is the type of objects to search for. for example: user, post, group, event, page etc...
if($facebook->isSuccess()) {
// Operation was successful
// Use $facebook->getId(), or $facebook->getResult() or $operationResult to access the returned data
} else {
// Operation was not successful
// user $facebook->getError() or $facebook->getErrorMessage() to access the error info
}
$facebook->clear(); // will reset all the saved session states, basically invokes clearAllPersistentData $facebook->clearState($key); // deletes certain state from the persistent storage basically invokes clearPersistentData($key)
Facebook will be doing some changes to the API and starting May 1st 2012 it will remove the offline_access extended permission. Read More.
With this method you will be able to extend the current users access token to be valid up to 60 days.
$facebook->extenedAccessToken();
Usage example (also available under /examples/extendedaccesstoken.php)
$result = $facebook->extenedAccessToken();
if($facebook->isSuccess()) {
echo "Access token extended:\n";
echo $facebook->getAccessToken();
var_dump($result);
} else {
echo "There was an error extending the access token:\n";
echo $facebook->getErrorMessage();
}