<?php
if (!function_exists('curl_init')) {
throw new Exception('Facebook needs the CURL PHP extension.');
}
if (!function_exists('json_decode')) {
throw new Exception('Facebook needs the JSON PHP extension.');
}
/**
* Thrown when an API call returns an exception.
*
* @author Naitik Shah <naitik@facebook.com>
*/
class FacebookApiException extends Exception
{
/**
* The result from the API server that represents the exception information.
*/
protected $result;
/**
* Make a new API Exception with the given result.
*
* @param Array $result the result from the API server
*/
public function __construct($result) {
$this->result = $result;
$code = isset($result['error_code']) ? $result['error_code'] : 0;
if (isset($result['error_description'])) {
// OAuth 2.0 Draft 10 style
$msg = $result['error_description'];
} else if (isset($result['error']) && is_array($result['error'])) {
// OAuth 2.0 Draft 00 style
$msg = $result['error']['message'];
} else if (isset($result['error_msg'])) {
// Rest server style
$msg = $result['error_msg'];
} else {
$msg = 'Unknown Error. Check getResult()';
}
parent::__construct($msg, $code);
}
/**
* Return the associated result object returned by the API server.
*
* @returns Array the result from the API server
*/
public function getResult() {
return $this->result;
}
/**
* Returns the associated type for the error. This will default to
* 'Exception' when a type is not available.
*
* @return String
*/
public function getType() {
if (isset($this->result['error'])) {
$error = $this->result['error'];
if (is_string($error)) {
// OAuth 2.0 Draft 10 style
return $error;
} else if (is_array($error)) {
// OAuth 2.0 Draft 00 style
if (isset($error['type'])) {
return $error['type'];
}
}
}
return 'Exception';
}
/**
* To make debugging easier.
*
* @returns String the string representation of the error
*/
public function __toString() {
$str = $this->getType() . ': ';
if ($this->code != 0) {
$str .= $this->code . ': ';
}
return $str . $this->message;
}
}
/**
* Provides access to the Facebook Platform.
*
* @author Naitik Shah <naitik@facebook.com>
*/
class Facebook
{
/**
* Version.
*/
const VERSION = '2.1.2';
/**
* Default options for curl.
*/
public static $CURL_OPTS = array(
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_USERAGENT => 'facebook-php-2.0',
);
/**
* List of query parameters that get automatically dropped when rebuilding
* the current URL.
*/
protected static $DROP_QUERY_PARAMS = array(
'session',
'signed_request',
);
/**
* Maps aliases to Facebook domains.
*/
public static $DOMAIN_MAP = array(
'api' => 'https://api.facebook.com/',
'api_read' => 'https://api-read.facebook.com/',
'graph' => 'https://graph.facebook.com/',
'www' => 'https://www.facebook.com/',
);
/**
* The Application ID.
*/
protected $appId;
/**
* The Application API Secret.
*/
protected $apiSecret;
/**
* The active user session, if one is available.
*/
protected $session;
/**
* The data from the signed_request token.
*/
protected $signedRequest;
/**
* Indicates that we already loaded the session as best as we could.
*/
protected $sessionLoaded = false;
/**
* Indicates if Cookie support should be enabled.
*/
protected $cookieSupport = false;
/**
* Base domain for the Cookie.
*/
protected $baseDomain = '';
/**
* Indicates if the CURL based @ syntax for file uploads is enabled.
*/
protected $fileUploadSupport = false;
/**
* Initialize a Facebook Application.
*
* The configuration:
* - appId: the application ID
* - secret: the application secret
* - cookie: (optional) boolean true to enable cookie support
* - domain: (optional) domain for the cookie
* - fileUpload: (optional) boolean indicating if file uploads are enabled
*
* @param Array $config the application configuration
*/
public function __construct($config) {
$this->setAppId($config['appId']);
$this->setApiSecret($config['secret']);
if (isset($config['cookie'])) {
$this->setCookieSupport($config['cookie']);
}
if (isset($config['domain'])) {
$this->setBaseDomain($config['domain']);
}
if (isset($config['fileUpload'])) {
$this->setFileUploadSupport($config['fileUpload']);
}
}
/**
* Set the Application ID.
*
* @param String $appId the Application ID
*/
public function setAppId($appId) {
$this->appId = $appId;
return $this;
}
/**
* Get the Application ID.
*
* @return String the Application ID
*/
public function getAppId() {
return $this->appId;
}
/**
* Set the API Secret.
*
* @param String $appId the API Secret
*/
public function setApiSecret($apiSecret) {
$this->apiSecret = $apiSecret;
return $this;
}
/**
* Get the API Secret.
*
* @return String the API Secret
*/
public function getApiSecret() {
return $this->apiSecret;
}
/**
* Set the Cookie Support status.
*
* @param Boolean $cookieSupport the Cookie Support status
*/
public function setCookieSupport($cookieSupport) {
$this->cookieSupport = $cookieSupport;
return $this;
}
/**
* Get the Cookie Support status.
*
* @return Boolean the Cookie Support status
*/
public function useCookieSupport() {
return $this->cookieSupport;
}
/**
* Set the base domain for the Cookie.
*
* @param String $domain the base domain
*/
public function setBaseDomain($domain) {
$this->baseDomain = $domain;
return $this;
}
/**
* Get the base domain for the Cookie.
*
* @return String the base domain
*/
public function getBaseDomain() {
return $this->baseDomain;
}
/**
* Set the file upload support status.
*
* @param String $domain the base domain
*/
public function setFileUploadSupport($fileUploadSupport) {
$this->fileUploadSupport = $fileUploadSupport;
return $this;
}
/**
* Get the file upload support status.
*
* @return String the base domain
*/
public function useFileUploadSupport() {
return $this->fileUploadSupport;
}
/**
* Get the data from a signed_request token
*
* @return String the base domain
*/
public function getSignedRequest() {
if (!$this->signedRequest) {
if (isset($_REQUEST['signed_request'])) {
$this->signedRequest = $this->parseSignedRequest(
$_REQUEST['signed_request']);
}
}
return $this->signedRequest;
}
/**
* Set the Session.
*
* @param Array $session the session
* @param Boolean $write_cookie indicate if a cookie should be written. this
* value is ignored if cookie support has been disabled.
*/
public function setSession($session=null, $write_cookie=true) {
$session = $this->validateSessionObject($session);
$this->sessionLoaded = true;
$this->session = $session;
if ($write_cookie) {
$this->setCookieFromSession($session);
}
return $this;
}
/**
* Get the session object. This will automatically look for a signed session
* sent via the signed_request, Cookie or Query Parameters if needed.
*
* @return Array the session
*/
public function getSession() {
if (!$this->sessionLoaded) {
$session = null;
$write_cookie = true;
// try loading session from signed_request in $_REQUEST
$signedRequest = $this->getSignedRequest();
if ($signedRequest) {
// sig is good, use the signedRequest
$session = $this->createSessionFromSignedRequest($signedRequest);
}
// try loading session from $_REQUEST
if (!$session && isset($_REQUEST['session'])) {
$session = json_decode(
get_magic_quotes_gpc()
? stripslashes($_REQUEST['session'])
: $_REQUEST['session'],
true
);
$session = $this->validateSessionObject($session);
}
// try loading session from cookie if necessary
if (!$session && $this->useCookieSupport()) {
$cookieName = $this->getSessionCookieName();
if (isset($_COOKIE[$cookieName])) {
$session = array();
parse_str(trim(
get_magic_quotes_gpc()
? stripslashes($_COOKIE[$cookieName])
: $_COOKIE[$cookieName],
'"'
), $session);
$session = $this->validateSessionObject($session);
// write only if we need to delete a invalid session cookie
$write_cookie = empty($session);
}
}
$this->setSession($session, $write_cookie);
}
return $this->session;
}
/**
* Get the UID from the session.
*
* @return String the UID if available
*/
public function getUser() {
$session = $this->getSession();
return $session ? $session['uid'] : null;
}
/**
* Gets a OAuth access token.
*
* @return String the access token
*/
public function getAccessToken() {
$session = $this->getSession();
// either user session signed, or app signed
if ($session) {
return $session['access_token'];
} else {
return $this->getAppId() .'|'. $this->getApiSecret();
}
}
/**
* Get a Login URL for use with redirects. By default, full page redirect is
* assumed. If you are using the generated URL with a window.open() call in
* JavaScript, you can pass in display=popup as part of the $params.
*
* The parameters:
* - next: the url to go to after a successful login
* - cancel_url: the url to go to after the user cancels
* - req_perms: comma separated list of requested extended perms
* - display: can be "page" (default, full page) or "popup"
*
* @param Array $params provide custom parameters
* @return String the URL for the login flow
*/
public function getLoginUrl($params=array()) {
$currentUrl = $this->getCurrentUrl();
return $this->getUrl(
'www',
'login.php',
array_merge(array(
'api_key' => $this->getAppId(),
'cancel_url' => $currentUrl,
'display' => 'page',
'fbconnect' => 1,
'next' => $currentUrl,
'return_session' => 1,
'session_version' => 3,
'v' => '1.0',
), $params)
);
}
/**
* Get a Logout URL suitable for use with redirects.
*
* The parameters:
* - next: the url to go to after a successful logout
*
* @param Array $params provide custom parameters
* @return String the URL for the logout flow
*/
public function getLogoutUrl($params=array()) {
return $this->getUrl(
'www',
'logout.php',
array_merge(array(
'next' => $this->getCurrentUrl(),
'access_token' => $this->getAccessToken(),
), $params)
);
}
/**
* Get a login status URL to fetch the status from facebook.
*
* The parameters:
* - ok_session: the URL to go to if a session is found
* - no_session: the URL to go to if the user is not connected
* - no_user: the URL to go to if the user is not signed into facebook
*
* @param Array $params provide custom parameters
* @return String the URL for the logout flow
*/
public function getLoginStatusUrl($params=array()) {
return $this->getUrl(
'www',
'extern/login_status.php',
array_merge(array(
'api_key' => $this->getAppId(),
'no_session' => $this->getCurrentUrl(),
'no_user' => $this->getCurrentUrl(),
'ok_session' => $this->getCurrentUrl(),
'session_version' => 3,
), $params)
);
}
/**
* Make an API call.
*
* @param Array $params the API call parameters
* @return the decoded response
*/
public function api(/* polymorphic */) {
$args = func_get_args();
if (is_array($args[0])) {
try { return $this->_restserver($args[0]); }
catch (Exception $e) {
self::errorLog("$e");
return 'Request to facebook timed out';
}
} else {
return call_user_func_array(array($this, '_graph'), $args);
}
}
/**
* Invoke the old restserver.php endpoint.
*
* @param Array $params method call object
* @return the decoded response object
* @throws FacebookApiException
*/
protected function _restserver($params) {
// generic application level parameters
$params['api_key'] = $this->getAppId();
$params['format'] = 'json-strings';
$result = json_decode($this->_oauthRequest(
$this->getApiUrl($params['method']),
$params
), true);
// results are returned, errors are thrown
if (is_array($result) && isset($result['error_code'])) {
throw new FacebookApiException($result);
}
return $result;
}
/**
* Invoke the Graph API.
*
* @param String $path the path (required)
* @param String $method the http method (default 'GET')
* @param Array $params the query/post data
* @return the decoded response object
* @throws FacebookApiException
*/
protected function _graph($path, $method='GET', $params=array()) {
if (is_array($method) && empty($params)) {
$params = $method;
$method = 'GET';
}
$params['method'] = $method; // method override as we always do a POST
$result = json_decode($this->_oauthRequest(
$this->getUrl('graph', $path),
$params
), true);
// results are returned, errors are thrown
if (is_array($result) && isset($result['error'])) {
$e = new FacebookApiException($result);
switch ($e->getType()) {
// OAuth 2.0 Draft 00 style
case 'OAuthException':
// OAuth 2.0 Draft 10 style
case 'invalid_token':
$this->setSession(null);
}
throw $e;
}
return $result;
}
/**
* Make a OAuth Request
*
* @param String $path the path (required)
* @param Array $params the query/post data
* @return the decoded response object
* @throws FacebookApiException
*/
protected function _oauthRequest($url, $params) {
if (!isset($params['access_token'])) {
$params['access_token'] = $this->getAccessToken();
}
// json_encode all params values that are not strings
foreach ($params as $key => $value) {
if (!is_string($value)) {
$params[$key] = json_encode($value);
}
}
return $this->makeRequest($url, $params);
}
/**
* Makes an HTTP request. This method can be overriden by subclasses if
* developers want to do fancier things or use something other than curl to
* make the request.
*
* @param String $url the URL to make the request to
* @param Array $params the parameters to use for the POST body
* @param CurlHandler $ch optional initialized curl handle
* @return String the response text
*/
protected function makeRequest($url, $params, $ch=null) {
if (!$ch) {
$ch = curl_init();
}
$opts = self::$CURL_OPTS;
if ($this->useFileUploadSupport()) {
$opts[CURLOPT_POSTFIELDS] = $params;
} else {
$opts[CURLOPT_POSTFIELDS] = http_build_query($params, null, '&');
}
$opts[CURLOPT_URL] = $url;
// disable the 'Expect: 100-continue' behaviour. This causes CURL to wait
// for 2 seconds if the server does not support this header.
if (isset($opts[CURLOPT_HTTPHEADER])) {
$existing_headers = $opts[CURLOPT_HTTPHEADER];
$existing_headers[] = 'Expect:';
$opts[CURLOPT_HTTPHEADER] = $existing_headers;
} else {
$opts[CURLOPT_HTTPHEADER] = array('Expect:');
}
curl_setopt_array($ch, $opts);
$result = curl_exec($ch);
if (curl_errno($ch) == 60) { // CURLE_SSL_CACERT
// self::errorLog('Invalid or no certificate authority found, using bundled information');
curl_setopt($ch, CURLOPT_CAINFO,
dirname(__FILE__) . '/fb_ca_chain_bundle.crt');
$result = curl_exec($ch);
}
if ($result === false) {
$e = new FacebookApiException(array(
'error_code' => curl_errno($ch),
'error' => array(
'message' => curl_error($ch),
'type' => 'CurlException',
),
));
curl_close($ch);
self::errorLog("$e");
return 'Request to facebook timed out';
}
curl_close($ch);
return $result;
}
/**
* The name of the Cookie that contains the session.
*
* @return String the cookie name
*/
protected function getSessionCookieName() {
return 'fbs_' . $this->getAppId();
}
/**
* Set a JS Cookie based on the _passed in_ session. It does not use the
* currently stored session -- you need to explicitly pass it in.
*
* @param Array $session the session to use for setting the cookie
*/
protected function setCookieFromSession($session=null) {
if (!$this->useCookieSupport()) {
return;
}
$cookieName = $this->getSessionCookieName();
$value = 'deleted';
$expires = time() - 3600;
$domain = $this->getBaseDomain();
if ($session) {
$value = '"' . http_build_query($session, null, '&') . '"';
if (isset($session['base_domain'])) {
$domain = $session['base_domain'];
}
$expires = $session['expires'];
}
// prepend dot if a domain is found
if ($domain) {
$domain = '.' . $domain;
}
// if an existing cookie is not set, we dont need to delete it
if ($value == 'deleted' && empty($_COOKIE[$cookieName])) {
return;
}
if (headers_sent()) {
self::errorLog('Could not set cookie. Headers already sent.');
// ignore for code coverage as we will never be able to setcookie in a CLI
// environment
// @codeCoverageIgnoreStart
} else {
setcookie($cookieName, $value, $expires, '/', $domain);
}
// @codeCoverageIgnoreEnd
}
/**
* Validates a session_version=3 style session object.
*
* @param Array $session the session object
* @return Array the session object if it validates, null otherwise
*/
protected function validateSessionObject($session) {
// make sure some essential fields exist
if (is_array($session) &&
isset($session['uid']) &&
isset($session['access_token']) &&
isset($session['sig'])) {
// validate the signature
$session_without_sig = $session;
unset($session_without_sig['sig']);
$expected_sig = self::generateSignature(
$session_without_sig,
$this->getApiSecret()
);
if ($session['sig'] != $expected_sig) {
self::errorLog('Got invalid session signature in cookie.');
$session = null;
}
// check expiry time
} else {
$session = null;
}
return $session;
}
/**
* Returns something that looks like our JS session object from the
* signed token's data
*
* TODO: Nuke this once the login flow uses OAuth2
*
* @param Array the output of getSignedRequest
* @return Array Something that will work as a session
*/
protected function createSessionFromSignedRequest($data) {
if (!isset($data['oauth_token'])) {
return null;
}
$session = array(
'uid' => $data['user_id'],
'access_token' => $data['oauth_token'],
'expires' => $data['expires'],
);
// put a real sig, so that validateSignature works
$session['sig'] = self::generateSignature(
$session,
$this->getApiSecret()
);
return $session;
}
/**
* Parses a signed_request and validates the signature.
* Then saves it in $this->signed_data
*
* @param String A signed token
* @param Boolean Should we remove the parts of the payload that
* are used by the algorithm?
* @return Array the payload inside it or null if the sig is wrong
*/
protected function parseSignedRequest($signed_request) {
list($encoded_sig, $payload) = explode('.', $signed_request, 2);
// decode the data
$sig = self::base64UrlDecode($encoded_sig);
$data = json_decode(self::base64UrlDecode($payload), true);
if (strtoupper($data['algorithm']) !== 'HMAC-SHA256') {
self::errorLog('Unknown algorithm. Expected HMAC-SHA256');
return null;
}
// check sig
$expected_sig = hash_hmac('sha256', $payload,
$this->getApiSecret(), $raw = true);
if ($sig !== $expected_sig) {
self::errorLog('Bad Signed JSON signature!');
return null;
}
return $data;
}
/**
* Build the URL for api given parameters.
*
* @param $method String the method name.
* @return String the URL for the given parameters
*/
protected function getApiUrl($method) {
static $READ_ONLY_CALLS =
array('admin.getallocation' => 1,
'admin.getappproperties' => 1,
'admin.getbannedusers' => 1,
'admin.getlivestreamvialink' => 1,
'admin.getmetrics' => 1,
'admin.getrestrictioninfo' => 1,
'application.getpublicinfo' => 1,
'auth.getapppublickey' => 1,
'auth.getsession' => 1,
'auth.getsignedpublicsessiondata' => 1,
'comments.get' => 1,
'connect.getunconnectedfriendscount' => 1,
'dashboard.getactivity' => 1,
'dashboard.getcount' => 1,
'dashboard.getglobalnews' => 1,
'dashboard.getnews' => 1,
'dashboard.multigetcount' => 1,
'dashboard.multigetnews' => 1,
'data.getcookies' => 1,
'events.get' => 1,
'events.getmembers' => 1,
'fbml.getcustomtags' => 1,
'feed.getappfriendstories' => 1,
'feed.getregisteredtemplatebundlebyid' => 1,
'feed.getregisteredtemplatebundles' => 1,
'fql.multiquery' => 1,
'fql.query' => 1,
'friends.arefriends' => 1,
'friends.get' => 1,
'friends.getappusers' => 1,
'friends.getlists' => 1,
'friends.getmutualfriends' => 1,
'gifts.get' => 1,
'groups.get' => 1,
'groups.getmembers' => 1,
'intl.gettranslations' => 1,
'links.get' => 1,
'notes.get' => 1,
'notifications.get' => 1,
'pages.getinfo' => 1,
'pages.isadmin' => 1,
'pages.isappadded' => 1,
'pages.isfan' => 1,
'permissions.checkavailableapiaccess' => 1,
'permissions.checkgrantedapiaccess' => 1,
'photos.get' => 1,
'photos.getalbums' => 1,
'photos.gettags' => 1,
'profile.getinfo' => 1,
'profile.getinfooptions' => 1,
'stream.get' => 1,
'stream.getcomments' => 1,
'stream.getfilters' => 1,
'users.getinfo' => 1,
'users.getloggedinuser' => 1,
'users.getstandardinfo' => 1,
'users.hasapppermission' => 1,
'users.isappuser' => 1,
'users.isverified' => 1,
'video.getuploadlimits' => 1);
$name = 'api';
if (isset($READ_ONLY_CALLS[strtolower($method)])) {
$name = 'api_read';
}
return self::getUrl($name, 'restserver.php');
}
/**
* Build the URL for given domain alias, path and parameters.
*
* @param $name String the name of the domain
* @param $path String optional path (without a leading slash)
* @param $params Array optional query parameters
* @return String the URL for the given parameters
*/
protected function getUrl($name, $path='', $params=array()) {
$url = self::$DOMAIN_MAP[$name];
if ($path) {
if ($path[0] === '/') {
$path = substr($path, 1);
}
$url .= $path;
}
if ($params) {
$url .= '?' . http_build_query($params, null, '&');
}
return $url;
}
/**
* Returns the Current URL, stripping it of known FB parameters that should
* not persist.
*
* @return String the current URL
*/
protected function getCurrentUrl() {
$protocol = isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on'
? 'https://'
: 'http://';
$currentUrl = $protocol . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'];
$parts = parse_url($currentUrl);
// drop known fb params
$query = '';
if (!empty($parts['query'])) {
$params = array();
parse_str($parts['query'], $params);
foreach(self::$DROP_QUERY_PARAMS as $key) {
unset($params[$key]);
}
if (!empty($params)) {
$query = '?' . http_build_query($params, null, '&');
}
}
// use port if non default
$port =
isset($parts['port']) &&
(($protocol === 'http://' && $parts['port'] !== 80) ||
($protocol === 'https://' && $parts['port'] !== 443))
? ':' . $parts['port'] : '';
// rebuild
return $protocol . $parts['host'] . $port . $parts['path'] . $query;
}
/**
* Generate a signature for the given params and secret.
*
* @param Array $params the parameters to sign
* @param String $secret the secret to sign with
* @return String the generated signature
*/
protected static function generateSignature($params, $secret) {
// work with sorted data
ksort($params);
// generate the base string
$base_string = '';
foreach($params as $key => $value) {
$base_string .= $key . '=' . $value;
}
$base_string .= $secret;
return md5($base_string);
}
/**
* Prints to the error log if you aren't in command line mode.
*
* @param String log message
*/
protected static function errorLog($msg) {
// disable error log if we are running in a CLI environment
// @codeCoverageIgnoreStart
if (php_sapi_name() != 'cli') {
error_log($msg);
}
// uncomment this if you want to see the errors on the page
// print 'error_log: '.$msg."\n";
// @codeCoverageIgnoreEnd
}
/**
* Base64 encoding that doesn't need to be urlencode()ed.
* Exactly the same as base64_encode except it uses
* - instead of +
* _ instead of /
*
* @param String base64UrlEncodeded string
*/
protected static function base64UrlDecode($input) {
return base64_decode(strtr($input, '-_', '+/'));
}
}
