A fully unit-tested package for easily integrating the Facebook SDK v4.0 into Laravel 4 which also harnesses the power of Facebook Query Builder.
- Installation
- Facebook Query Builder
- Examples
- Extensibility
- Error Handling
- Testing
- Contributing
- Credits
- License
Add the Laravel Facebook Sdk package to your composer.json
file.
{
"require": {
"sammyk/laravel-facebook-sdk": "~1.1"
}
}
Or via the command line in the root of your Laravel installation.
$ composer require "sammyk/laravel-facebook-sdk:~1.1"
In your app config, add the LaravelFacebookSdkServiceProvider
to the providers array.
'providers' => [
'SammyK\LaravelFacebookSdk\LaravelFacebookSdkServiceProvider',
];
If you want to make use of the facade, add it to the aliases array in your app config.
'aliases' => [
'Facebook' => 'SammyK\LaravelFacebookSdk\FacebookFacade',
];
After creating an app in Facebook, you'll need to provide the app ID and secret. First publish the configuration file.
$ php artisan config:publish sammyk/laravel-facebook-sdk
Then you can update the app_id
and app_secret
values in the app/config/packages/sammyk/laravel-facebook-sdk/config.php
file.
If you plan on integrating Facebook user authentication with your existing User
model, you'll need to add some fields to your user table. LaravelFacebookSdk makes this a painless process with an artisan command to create a migration.
Note: Make sure to change
users
to the name of your user table.
$ php artisan laravel-facebook-sdk:table users
$ php artisan migrate
If you're using the Eloquent ORM, make sure to hide the access_token
field from possible exposure in your User
model.
Also add the FacebookableTrait
to your model to get some really great functionality for syncing Facebook data with your User
model.
use SammyK\LaravelFacebookSdk\FacebookableTrait;
class User extends Eloquent implements UserInterface
{
use FacebookableTrait;
protected $hidden = ['access_token'];
}
Check out the migration file that it generated. If you plan on using the Facebook user ID as the primary key, make sure you have a column called id
that is a big int and indexed. If you are storing the Facebook ID in a different field, make sure that field exists in the database and make sure to map to it in your model.
Since the names of the fields in your database might not match the names of the fields in Graph, you can map the field names in your User
model using the $facebook_field_aliases
static variable.
The keys of the array are the names of the fields in Graph. The values of the array are the names of the columns in the local database.
class User extends Eloquent implements UserInterface
{
protected static $facebook_field_aliases = [
'facebook_field_name' => 'database_column_name',
'id' => 'facebook_user_id',
'name' => 'full_name',
];
}
Any model that implements the FacebookableTrait
will have the createOrUpdateFacebookObject()
method applied to it. This method really makes it easy to take data that was returned directly from Facebook and create or update it in the local database.
$facebook_event = Facebook::object('some-event-id')->fields('id', 'name')->get();
// Create the event if not exists or update existing
$event = Event::createOrUpdateFacebookObject($facebook_event);
LaravelFacebookSdk is a wrapper for Facebook Query Builder. Any of the Facebook Query Builder methods are accessible via the Facebook
facade. For a full list of available methods, consult the Facebook Query Builder documentation.
// This is done for you automatically with the config you provide,
// but you can overwrite it here if you're working with multiple apps.
Facebook::setAppCredentials('your_app_id', 'your_app_secret');
// . . .
// This access token will be used for all calls to Graph.
Facebook::setAccessToken('access_token');
// . . .
// Get the logged in user's profile.
$user = Facebook::object('me')->fields('id', 'email')->get();
// . . .
// Get latest 5 photos of user and their name.
$photos = Facebook::edge('photos')->fields('id', 'source')->limit(5);
$user = Facebook::object('me')->fields('name', $photos)->get();
// . . .
// Post a status update.
$status_update = ['message' => 'My witty status update.'];
$response = Facebook::object('me/feed')->with($status_update)->post();
$status_update_id = $response['id'];
// Comment on said status update.
$comment = ['message' => 'My witty comment on your status update.'];
$response = Facebook::object($status_update_id . '/comments')->with($comment)->post();
// Delete the status update.
$response = Facebook::object($status_update_id)->delete();
You can get a login URL just like you can in Facebook Query Builder.
$login_link = Facebook::auth()->getLoginUrl('http://my-callback/url');
But if your callback URL is already set in the config file, you can use the wrapper which will default the callback and permission scope to whatever you set in the config file.
$login_link = Facebook::getLoginUrl();
Alternatively you can pass the permissions and a custom callback to the wrapper to overwrite the default config.
$login_link = Facebook::getLoginUrl(['email', 'user_status'], 'http://my-custom-callback/url');
Just like getLoginUrl()
, there is a wrapper for getTokenFromRedirect()
that defaults the callback URL to whatever is set in the config.
try
{
$token = Facebook::getTokenFromRedirect();
}
catch (FacebookQueryBuilderException $e)
{
// Failed to obtain access token
echo 'Error:' . $e->getMessage();
}
See the documentation for all the ways to obtain an AccessToken object.
Here's how you might log a user into your site, get a long-lived access token and save the user to your users
table if they don't already exist then log them in.
// Fancy wrapper for login URL
Route::get('/login', function()
{
return Redirect::to(Facebook::getLoginUrl());
});
// Endpoint that is redirected to after an authentication attempt
Route::get('/facebook/login', function()
{
/**
* Obtain an access token.
*/
try
{
$token = Facebook::getTokenFromRedirect();
if ( ! $token)
{
return Redirect::to('/')->with('error', 'Unable to obtain access token.');
}
}
catch (FacebookQueryBuilderException $e)
{
return Redirect::to('/')->with('error', $e->getPrevious()->getMessage());
}
if ( ! $token->isLongLived())
{
/**
* Extend the access token.
*/
try
{
$token = $token->extend();
}
catch (FacebookQueryBuilderException $e)
{
return Redirect::to('/')->with('error', $e->getPrevious()->getMessage());
}
}
Facebook::setAccessToken($token);
/**
* Get basic info on the user from Facebook.
*/
try
{
$facebook_user = Facebook::object('me')->fields('id','name')->get();
}
catch (FacebookQueryBuilderException $e)
{
return Redirect::to('/')->with('error', $e->getPrevious()->getMessage());
}
// Create the user if not exists or update existing
$user = User::createOrUpdateFacebookObject($facebook_user);
// Log the user into Laravel
Facebook::auth()->login($user);
return Redirect::to('/')->with('message', 'Successfully logged in with Facebook');
});
You can add extensibility is by registering a closure.
Facebook::extend('getUserEventsAndPhotos', function($facebook)
{
$events = $facebook->edge('events')->fields('id', 'name')->limit(10);
$photos = $facebook->edge('photos')->fields('id', 'source')->limit(10);
return $facebook->object('me')->fields('id', 'name', $events, $photos)->get();
});
Then you can call getUserEventsAndPhotos()
from the Facade.
$users_events_and_photos = Facebook::getUserEventsAndPhotos()
There are three types of exceptions that can be thrown.
- In most cases a
\SammyK\FacebookQueryBuilder\FacebookQueryBuilderException
will be thrown from the Facebook Query Builder. Those exceptions are not caught from within this package so that you can handle them directly. These are usually thrown if Graph returns an error or there was an issue communicating with Graph. - A
LaravelFacebookSdkException
will be thrown if there was an error adding extensibility or if there was a problem validating data on an Eloquent model. - In uncommon scenarios you might have a
\Facebook\FacebookSDKException
thrown at you. This is an exception that the base Facebook PHP SDK v4 throws. Most of these are caught & rethrown under the\SammyK\FacebookQueryBuilder\FacebookQueryBuilderException
, but some of them might sneak through.
To get the tests to pass, you'll need to run phpunit
from within the root of your Laravel installation and point it to the LaravelFacebookSdk installation in the vendor
directory.
$ cd /path/to/laravel-installation
$ phpunit vendor/sammyk/laravel-facebook-sdk
Please see CONTRIBUTING for details.
This package is maintained by Sammy Kaye Powers. See a full list of contributors.
The MIT License (MIT). Please see License File for more information.