Downloads

Google Ad

CakePHP Facebook Plugin -- Auth+Facebook and more

Date: Tue, Feb 9th 2010, 06:44 Author: nick Views: 298131 Comments share

CakePHP Facebook Plugin

Info:
Get it:
  • Download Now
  • git clone git://github.com/webtechnick/CakePHP-Facebook-Plugin facebook
The purpose of the Facebook plugin is to provide a seamless way to connect your cakePHP app to everyone's favorite social networking site -- Facebook. The goal for this plugin is to not only provide extremely useful dynamic features but to also provide a complete interface to the Facebook API.
This plugin is specifically for CakePHP 1.3
Example App: http://facebook.webtechnick.com Example App Source: http://svn.xp-dev.com/svn/facebook_example_app/
Version 3.0 Update (OAuth Update):
http://www.webtechnick.com/blogs/view/242/CakePHP_Facebook_Plugin_v3_0_OAuth_and_Registration

Version 2.0 Update (Graph System):
http://www.webtechnick.com/blogs/view/238/Facebook_Plugin_v2_0_Graph_System

UPDATE

I've recently made and submitted a screencast to http://tv.cakephp.org/video/webtechnick/2011/01/12/nick_baker_--_facebook_integration_with_cakephp on how to integrate Facebook into your CakePHP application.

Facebook Integration with CakePHP Screencast


Feature List

  • Full featured authentication via Facebook Connect. Facebook Authentication will work with or without a user login system already in place on your site. Works seamlessly with your already built in user authentication system via AuthComponent -OR- Facebook Connect can work as your primary authentication system.
    • Setup is as easy as dropping Facebook.Connect into your components array.
    • Retrieve Detailed User Information and gain access to protected data via extended permissions (user prompted to allowed)
  • Easily create dynamic and customizable Facebook content
    • Share (let your users share what they find on your site with their friends)
    • Like (let your users like what they find on your site with their friends)
    • Login/Logout/Disconnect (Facebook users can login and logout of your site with a single click.. no registration required)
    • Activity Feed (Display your application's and friends activity)
    • Friend Pile (Display your application's friends)
    • Recommendations (Display your recommendations based on your current url)
    • Fan Boxes (Allow users to become facebook fans of your site)
    • Profile Pictures (Display a facebook profile picture)
    • Live Streams (Create dynamic live stream events)
    • Comments (Connect with your users by allowing them to comment on any part of your site through Facebook
    • Status (Display the status of the logged in user)
  • Access to Facebook API anywhere in your app. Build custom content with direct access to the full Facebook API.
  • Everything is included. No need to download the Facebook API files or create Facebook specific files (xd_receiver.htm and the like). Everything is included in the plugin and will be maintained.

Configuration

To get started you'll first need to download and unpack the Facebook Plugin into your app/plugins/facebook directory. If you plan on using any features mentioned above (except the share feature, which will work with no further configuration), you will need to get an api_key and secret from Facebook.

Once you have your api_key, secret, and app_id from Facebook, you'll need to create a configuration file named 'facebook.php' within your app/config directory with this information.

  1. app/config/facebook.php
  2. $config = array(
  3.   'Facebook' => array(
  4.     'appId'  => 'YOUR_APP_ID',
  5.     'apiKey' => 'YOUR_API_KEY',
  6.     'secret' => 'YOUR_SECRET',
  7.     'cookie' => true,
  8.     'locale' => 'en_US'
  9.   )
  10. );

Setup

You'll more than likely at least want to use the bundled FacebookHelper.

  1. //app_controller.php
  2. var $helpers = array('Facebook.Facebook');

If all you want to use is the 'share' feature skip ahead to Usage Examples as there is no further setup required for 'share' to work. However, if you wish to use some of the more advanced features you will need to alter your layout a little to accommodate the fbxml (facebook-xml).

Alter your views/layouts/default.ctp

Replace:
[geshi=html] with
  1. <?= $facebook->html(); ?>

Add at bottom of your page:
  1. <?= $facebook->init(); ?>

Your layout should look something like this:
[geshi=html] html(); ?> Facebook Plugin Example init(); ?>
Now you're ready to start using the more advanced features included in the Facebook plugin.

Extended Permissions

You can ask for permissions using the Facebook API graph system (Auth Token required), or through the login() function.

The easiest way is through the included $facebook->login() function

Example:
  1. //Upon login, ask for email and ability to read/write to wall
  2. $facebook->login(array(
  3.  'perms' => 'email,read_stream,publish_stream'
  4. ));

For a full list of permissions you can ask for refer to:
http://developers.facebook.com/docs/authentication/permissions

Usage Examples

The Plugin comes with a whole slew of neat dynamic content from Facebook.

Share feature:
  1. //Create a share button
  2. $facebook->share(); //defaults to current page
  3.  
  4. //Share button with a different url
  5. $facebook->share('http://www.webtechnick.com');
  6.  
  7. //Share button with url and options
  8. $facebook->share('http://www.webtechnick.com', array('style' => 'link', 'label' => 'Check it out!'));
  9.  
  10. //Like button with url and options
  11. $facebook->like();
  12.  
  13. //Like button with options
  14. $facebook->like(array(
  15.   'font' => 'veranda',
  16.   'layout' => 'button_count',
  17.   'action' => 'recommend',
  18.   'colorscheme' => 'dark'));

Fanbox feature (app_id required):
  1. //Display Fan Box with minimal options
  2. $facebook->fanbox();
  3.  
  4. //Display fanbox with all the whistles and bells
  5. $facebook->fanbox(array('stream' => true, 'logobar' => true, 'connections' => true));

Live Stream feature:
  1. //Display livestream event
  2. $facebook->livestream();
  3.  
  4. //Display livestream event with all whistles and bells
  5. $facebook->livestream(array('width' => '300', 'height' => '500', 'xid' => 'YOUR_EVENT_XID', 'event_app_id' => 'CUSTOM_APP_ID'));

Comments feature:
  1. //Display comments section
  2. $facebook->comments();
  3.  
  4. //Display comments with all whistles and bells
  5. $facebook->comments(array('width' => '300', 'height' => '500'));

Profile Pictures feature:
  1. //Display picture of facebook user
  2. $facebook->picture($facebook_id);
  3.  
  4. /** Hint: if you're using the Facebook.Connect feature, set the Auth->user() to a variable and use that to show the logged in user's profile
  5. */
  6. $facebook->picture($user['User']['facebook_id']);
  7.  
  8. //Display picture of facebook user with all a size
  9. //options: thumb, small, normal, square (default thumb)
  10. $facebook->picture($facebook_id, array('size' => 'normal'));
  11.  
  12. //Or set your own size
  13. $facebook->picture($facebook_id, array('width' => '200', 'height' => '200'));
  14.  
  15. //Show a generic facebook logo until the picture is loaded
  16. $facebook->picture($facebook_id, array('facebook-logo' => true));

Recommendations:
  1. //Display Facebook Recommendations based on the current page
  2. $facebook->recommendations();
  3.  
  4. //Recommendations with some whistles and bells
  5. $facebook->recommendations(array(
  6.   'colorscheme' => 'dark',
  7.   'bordercolor' => 'black',
  8.   'width' => '100',
  9.   'height' => '100',
  10.   'header' => 'false'));

Facebook Connect (Authentication)

You can use the Facebook Plugin as your primary user authentication system or along side your current authentication system (currently only supports CakePHP's AuthComponent).

Setup is extremely simple. Just drop in Facebook.Connect into your app_controller's components array.
  1. //app_controller.php
  2. var $components = array('Auth', 'Facebook.Connect');

And add facebook_id to your user table (or the table you use for your Auth Component).
[geshi=sql] ALTER TABLE `users` ADD `facebook_id` BIGINT UNSIGNED NOT NULL

That's it! You're now ready to accept Facebook Login/Logout with your Authentication system.

Login Buttons To add a Facebook Connect login button use:
  1. //Display login button medium size button
  2. $facebook->login();
  3.  
  4. //Display a small button
  5. //options: small, medium, large, or xlarge
  6. $facebook->login(array('size' => 'small'));
  7.  
  8. //Display a login button with a different background
  9. //options: white, dark, light (default light)
  10. $facebook->login(array('background' => 'dark'));

Logout Buttons To add a Facebook Connect logout button use:
  1. //Display a logout button medium size
  2. $facebook->logout();
  3.  
  4. //Display a logout button small size
  5. $facebook->logout(array('size' => 'small'));
  6.  
  7. //Display a logout link with a redirect
  8. //label is 'logout' by default.
  9. $facebook->logout(array('redirect' => 'users/logout', 'label' => 'Sign Out'));
  10.  
  11. $facebook->logout(array(
  12.   'redirect' => array('controller' => 'users', 'action' => 'logout'),
  13.   'label' => 'Sign Out'));

If you already have a built in Authentication system you will need to redirect to your apps logout action. Do this by adding a redirect to the logout button.
  1. //Logout from facebook and then redirect to logout from app
  2. //NOTE: redirect can be CakePHP array based url
  3. $facebook->logout(array('redirect' => 'users/logout'));
  4.  
  5. //Change logout text ('logout' by default)
  6. $facebook->logout(array('redirect' => 'users/logout', 'label' => 'Sign Out'));

Facebook Connect User Information

While using the Facebook.Connect you can obtain more detailed information about your logged in user via the user() function. The result will return an array of useful information for your user. By default, only last_name, first_name, and email are returned. However, you can request anything you want that is an available option via facebook API: http://wiki.developers.facebook.com/index.php/Users.getInfo#Response

Example:
  1. var $components = array('Auth','Facebook.Connect');
  2.  
  3. function beforeFilter(){
  4.   //Get all the details on the facebook user
  5.   $this->set('facebookUser', $this->Connect->user());
  6.  
  7.   //retrieve only the id from the facebook user
  8.   $this->set('facebook_id', $this->Connect->user('id'));
  9.  
  10.   //retrieve only the email from the facebook user
  11.   $this->set('facebook_email', $this->Connect->user('email'));
  12. }

Facebook Registration (new in v3.x)

New social media registration plugin allows a user to fill out a registration form auto-populated by their information in their Facebook profile. The setup is simple. Use the FacebookHelper::registration() to show the registration form in an iframe.

  1. //Show registration form with default fields
  2. $this->Facebook->registration();
  3.  
  4. //Show registration form with custom fields and width
  5. $this->Facebook->registration(array(
  6.   'fields' => 'name,email,location,gender,favorite_team',
  7.   'width' => '500'
  8. ));

By default, once the user clicks "Register" the post is sent back to the same page the registration form was shown on. In your controller action simply check for registrationData and do with the data what you will (create/update a user etc...)

  1. function registration(){
  2.   if($user = $this->Connect->registrationData()){
  3.     //We have a registered user, look at it and do something with it.
  4.     print_r($user);
  5.   }
  6. }

You can change where you want the user to post to by setting 'redirect-uri' in the registration helper method.

  1. //Show registration form with custom url
  2. $this->Facebook->registration(array(
  3.   'redirect-uri' => 'http://www.example.com/facebook_registration',
  4. ));


Full Facebook API access

Access the Facebook API by importing Facebook.FB anywhere in your app then calling it to do various custom things. Depending on what version of PHP you're running you can make requests in a number of ways.

  1. App::import('Lib', 'Facebook.FB');
  2.  
  3. //PHP 5.3
  4. FB::api('/me'); //graph system call to /me
  5.  
  6. //PHP < 5.3
  7. $FacebookApi = new FB();
  8. $FacebookApi->api('/me');

The reason for the difference is the introduction of __callstatic() in PHP 5.3 that prior to 5.3 there's no way to overwrite the _call of a static method.

Take a look at all the available options and features you can use via the Facebook API here http://wiki.developers.facebook.com/index.php/Main_Page

Internationalization

You can set the locale of the plugin through the helper declaration or through the config/facebook.php configuration file (see top of document).

  1. var $helpers = array('Facebook.Facebook' => array('locale' => 'en_US'));

Facebook locales: http://developers.facebook.com/docs/internationalization/

Enjoy

If you have a feature request post a comment!

I hope you enjoy the work I put into this plugin. I encourage you to look at the API documentation for an in-depth look at all the available options for each feature.

As always, if you like the plugin, find a bug, or have a feature request post a comment. =) If you really like the plugin and want to help keep it maintained please consider a donation. It really does help!

Thanks,
Nick