4.0 dev

README.md

@@ -1,7 +1,7 @@
 Facebook SDK for PHP
 ====================
 
-[![Latest Stable Version](http://img.shields.io/packagist/v/facebook/php-sdk-v4.svg)](https://packagist.org/packages/facebook/php-sdk-v4)
+[![Latest Stable Version](http://img.shields.io/badge/Latest%20Stable-4.0.23-blue.svg)](https://packagist.org/packages/facebook/php-sdk-v4)
 
 
 This repository contains the open source PHP SDK that allows you to access Facebook
@@ -16,6 +16,12 @@ This version of the Facebook SDK for PHP requires PHP 5.4 or greater.
 Minimal example:
 
 ```php
+<?php
+
+// Skip these two lines if you're using Composer
+define('FACEBOOK_SDK_V4_SRC_DIR', '/path/to/facebook-php-sdk-v4/src/Facebook/');
+require __DIR__ . '/path/to/facebook-php-sdk-v4/autoload.php';
+
 use Facebook\FacebookSession;
 use Facebook\FacebookRequest;
 use Facebook\GraphUser;

docs/FacebookCanvasLoginHelper.fbmd

@@ -0,0 +1,37 @@
+<card>
+# FacebookCanvasLoginHelper for the Facebook SDK for PHP
+
+A helper class for getting a FacebookSession in a Canvas app
+</card>
+
+<card>
+## Facebook\FacebookCanvasLoginHelper {#overview}
+
+If your app is loaded through Canvas, Facebook sends a POST request with a signed request.  This helper class will handle processing and validating that information with Facebook, and returns a `FacebookSession`.
+
+Usage:
+
+~~~~
+
+$helper = new FacebookCanvasLoginHelper();
+try {
+  $session = $helper->getSession();
+} catch (FacebookRequestException $ex) {
+	// When Facebook returns an error
+} catch (\Exception $ex) {
+	// When validation fails or other local issues	
+}
+if ($session) {
+  // Logged in.
+}
+
+~~~~
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### getSession {#getsession}
+`getSession()`  
+Processes the POST request from Facebook, if present.  Returns a `FacebookSession` or `null`.
+</card>

docs/FacebookJavaScriptLoginHelper.fbmd

@@ -0,0 +1,39 @@
+<card>
+# FacebookJavaScriptLoginHelper for the Facebook SDK for PHP
+
+A helper class for getting a FacebookSession using the session from the Facebook SDK for JavaScript.
+</card>
+
+<card>
+## Facebook\FacebookJavaScriptLoginHelper {#overview}
+
+If your web app uses the Facebook SDK for JavaScript, you can access that in your PHP code as well.  This helper class will process and validate the cookie data used by the Facebook SDK for JavaScript, returning a `FacebookSession` on success.
+
+Usage:
+
+~~~~
+
+$helper = new FacebookJavaScriptLoginHelper();
+try {
+	$session = $helper->getSession();
+} catch(FacebookRequestException $ex) {
+	// When Facebook returns an error
+} catch(\Exception $ex) {
+	// When validation fails or other local issues
+}
+if ($session) {
+  // Logged in.
+}
+
+~~~~
+
+It's important to note that on first access, or if a session has since expired, these methods will operate on data that is one request-cycle stale.  You will likely want to make an Ajax request when the login state changes in the Facebook SDK for JavaScript.  Information about that here: (FB.event.subscribe)[https://developers.facebook.com/docs/reference/javascript/FB.getLoginStatus/#events]
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### getSession {#getsession}
+`getSession()`  
+Processes the data available from the Facebook SDK for JavaScript, if present.  Returns a `FacebookSession` or `null`.
+</card>

docs/FacebookRedirectLoginHelper.fbmd

@@ -0,0 +1,54 @@
+<card>
+# FacebookRedirectLoginHelper for the Facebook SDK for PHP
+
+A helper class for getting a FacebookSession using the OAuth protocol.
+</card>
+
+<card>
+## Facebook\FacebookRedirectLoginHelper {#overview}
+
+If your web app uses Facebook Login on the back-end, you'll need to redirect your visitors to a URL at Facebook to initiate a login request.  Facebook then redirects the user to your apps callback URL, providing session data.  This helper class will generate the login URL for you, and can process and validate the data from Facebook, returning a `FacebookSession` on success.
+
+This class can be extended, and the `storeState($state)` and `loadState()` methods overridden, to store the state check using another method besides the default `$_SESSION`.
+
+Usage:
+
+~~~~
+
+$helper = new FacebookRedirectLoginHelper($redirect_url, $appId = NULL, $appSecret = NULL);
+echo '<a href="' . $helper->getLoginUrl() . '">Login with Facebook</a>';
+
+~~~~
+
+Then, in your callback page (at the redirect url) when Facebook sends the user back:
+
+~~~~
+
+$helper = new FacebookRedirectLoginHelper($redirect_url);
+try {
+	$session = $helper->getSessionFromRedirect();
+} catch(FacebookRequestException $ex) {
+	// When Facebook returns an error
+} catch(\Exception $ex) {
+	// When validation fails or other local issues
+}
+if ($session) {
+  // Logged in.
+}
+
+~~~~
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### getLoginUrl {#getloginurl}
+`getLoginUrl()`  
+Generates the URL to redirect a web visitor to Facebook to login to your app.
+### getLogoutUrl {#getlogouturl}
+`getLogoutUrl($next_url)`  
+Generates the URL to redirect a web visitor to Facebook to logout, with a url to redirect to after.
+### getSessionFromRedirect {#getsessionfromredirect}
+`getSessionFromRedirect()`  
+Processes the redirect data from Facebook, if present.  Returns a `FacebookSession` or `null`.
+</card>

docs/FacebookRequest.fbmd

@@ -0,0 +1,59 @@
+<card>
+# FacebookRequest for the Facebook SDK for PHP
+
+Represents a request that will be made against the Graph API.
+</card>
+
+<card>
+## Facebook\FacebookRequest {#overview}
+
+Constructor:
+
+~~~~
+$request = new FacebookRequest(  
+  FacebookSession $session,  
+  string $httpMethod,  
+  string $path, 
+  array $params = NULL,
+  string $version = NULL
+);
+~~~~
+
+Usage:
+
+~~~~
+// Make a new request and execute it.
+try {
+  $response = (new FacebookRequest($session, 'GET', '/me'))->execute();
+  $object = $response->getGraphObject();
+  echo $object->getProperty('name');
+} catch (FacebookRequestException $ex) {
+  echo $ex->getMessage();
+} catch (\Exception $ex) {
+  echo $ex->getMessage();
+}
+
+// You can chain methods together and get a strongly typed GraphUser
+$me = (new FacebookRequest(
+  $session, 'GET', '/me'
+))->execute()->getGraphObject(GraphUser::className);
+echo $me->getName();
+~~~~
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### execute {#execute}
+`execute()`  
+Returns a `Facebook\FacebookResponse` from this request, from which a strongly-typed result can be retrieved.  Throws an exception if the request fails.  If the error is returned from Facebook, as opposed to a networking issue, a `Facebook\FacebookRequestException` is thrown.
+### getPath {#getpath}
+`getPath()`  
+Returns a copy of the path for the request, not including the version.
+### getParameters {#getparams}
+`getParameters()`  
+Returns a copy of the parameters array for the request.
+### getSession {#getsession}
+`getSession()`  
+Returns the `Facebook\FacebookSession` object associated with this request.
+</card>

docs/FacebookRequestException.fbmd

@@ -0,0 +1,43 @@
+<card>
+# FacebookRequestException for the Facebook SDK for PHP
+
+Represents an exception thrown by executing a Facebook request.
+</card>
+
+<card>
+## Facebook\FacebookRequestException {#overview}
+
+This base class has several subclasses:
+
+`FacebookAuthorizationException`  
+`FacebookClientException`  
+`FacebookPermissionException`  
+`FacebookServerException`  
+`FacebookThrottleException`  
+`FacebookOtherException`  
+
+Whenever a FacebookRequestException is thrown, it will be one of these types.
+They are derived from the error information here: https://developers.facebook.com/docs/graph-api/using-graph-api/#errors
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+`FacebookRequestException` extends from the base `\Exception` class, so `getCode()` and `getMessage()` are available by default.
+
+### getHttpStatusCode {#gethttpstatus}
+`getHttpStatusCode()`  
+Returns the HTTP status code returned with this exception.
+### getSubErrorCode {#getsuberrorcode}
+`getSubErrorCode()`  
+Returns the numeric sub-error code returned from Facebook.
+### getErrorType {#geterrortype}
+`getErrorType()`  
+Returns the type of error as a string.
+### getResponse {#getresponse}
+`getResponse()`  
+Returns the decoded response used to create the exception.
+### getRawResponse {#getrawresponse}
+`getRawResponse()`  
+Returns the raw response used to create the exception.
+</card>

docs/FacebookResponse.fbmd

@@ -0,0 +1,57 @@
+<card>
+# FacebookResponse for the Facebook SDK for PHP
+
+Represents a response from the Graph API.
+</card>
+
+<card>
+## Facebook\FacebookResponse {#overview}
+
+Usage:
+
+~~~~
+// A FacebookResponse is returned from an executed FacebookRequest
+try {
+  $response = (new FacebookRequest($session, 'GET', '/me'))->execute();
+  // You can get the request back:
+  $request = $response->getRequest();
+  // You can get the response as a GraphObject:
+  $object = $response->getGraphObject();
+  // You can get the response as a subclass of GraphObject:
+  $me = $response->getGraphObject(GraphUser::className());
+  // If this response has multiple pages, you can get a request for the next or previous pages:
+  $nextPageRequest = $response->getRequestForNextPage();
+  $previousPageRequest = $response->getRequestForPreviousPage();
+} catch (FacebookRequestException $ex) {
+  echo $ex->getMessage();
+} catch (\Exception $ex) {
+  echo $ex->getMessage();
+}
+
+// You can also chain the methods together: 
+$me = (new FacebookRequest(
+  $session, 'GET', '/me'
+))->execute()->getGraphObject(GraphUser::className);
+echo $me->getName();
+~~~~
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### getGraphObject {#getgraphobject}
+`getGraphObject(string $type = 'Facebook\GraphObject')`  
+Returns the result as a `GraphObject`.  If specified, a strongly-typed subclass of `GraphObject` is returned.
+### getGraphObjectList {#getgraphobjectlist}
+`getGraphObjectList(string $type = 'Facebook\GraphObject')`  
+Returns an array of `GraphObject` returned by this request.  If specified, a strongly-typed subclass of `GraphObject` is returned.
+### getRequest {#getrequest}
+`getRequest()`  
+Returns the `FacebookRequest` that produced this response.
+### getRequestForNextPage {#getnextpage}
+`getRequestForNextPage()`  
+If the response has paginated data, produces a `FacebookRequest` for the next pge of data.
+### getRequestForPreviousPage {#getpreviouspage}
+`getRequestForPreviousPage()`  
+If the response has paginated data, produces a `FacebookRequest` for the previous page of data.
+</card>

docs/FacebookSession.fbmd

@@ -0,0 +1,71 @@
+<card>
+# FacebookSession for the Facebook SDK for PHP
+
+Represents a Facebook Session, which is used when making requests to the Graph API.
+</card>
+
+<card>
+## Facebook\FacebookSession {#overview}
+
+Usage:
+
+~~~~
+use Facebook\FacebookSession;
+
+FacebookSession::setDefaultApplication('app-id', 'app-secret');
+
+// If you already have a valid access token:
+$session = new FacebookSession('access-token');
+
+// If you're making app-level requests:
+$session = FacebookSession::newAppSession();
+
+// To validate the session:
+try {
+  $session->validate();
+} catch (FacebookRequestException $ex) {
+  // Session not valid, Graph API returned an exception with the reason.
+  echo $ex->getMessage();
+} catch (\Exception $ex) {
+  // Graph API returned info, but it may mismatch the current app or have expired.
+  echo $ex->getMessage();
+}
+~~~~
+</card>
+
+<card>
+## Static Methods {#static-methods}
+
+### setDefaultApplication {#setdefaultapp}
+`setDefaultApplication(string $appId, string $appSecret)`  
+Configures and app ID and secret that will be used by default throughout the SDK (but can be overridden whenever necessary using parameters to other methods.
+### validate {#validate}
+`validate(Facebook\GraphSessionInfo $sessionInfo, string $appId = NULL, string $appSecret = NULL)`  
+Ensures that the provided GraphSessionInfo is valid, throwing an exception if not.  It does this by ensuring the app ID in the token info matches the given (or default) app ID, ensuring the token itself is valid, and ensuring that the expiration time has not passed.
+### newAppSession {#newappsession}
+`newAppSession(string $appId = NULL, string $appSecret = NULL)`  
+Returns a `Facebook\FacebookSession` configured with a token for the app which can be used for publishing and for requesting app-level information.
+### newSessionFromSignedRequest {#newsessionfromsr}
+`newSessionFromSignedRequest(string $signedRequest)`  
+Returns a `Facebook\FacebookSession` for the given signed request.
+</card>
+
+<card>
+## Instance Methods {#instance-methods}
+
+### getToken {#gettoken}
+`getToken()`  
+Returns the token string for the session.
+### getSessionInfo {#getsessioninfo}
+`getSessionInfo(string $appId = NULL, string $appSecret = NULL)`  
+Equivalent to calling the /debug_token endpoint of the Graph API to get the details for the access token for this session.  Returns a `Facebook\GraphSessionInfo` object.
+### getLongLivedSession {#getlonglivedsession}
+`getLongLivedSession(string $appId = NULL, string $appSecret = NULL)`  
+Returns a new `Facebook\FacebookSession` resulting from extending a short-lived access token.  This method will make a network request.  If you know you already have a long-lived session, you do not need to call this.  The only time you get a short-lived session as of March 2014 is from the Facebook SDK for JavaScript.  If this session is not short-lived, this method will return `$this`.  A long-lived session is on the order of months.  A short-lived session is on the order of hours.  You can figure out whether a session is short-lived or long-lived by checking the expiration date in the session info, but it's not a precise thing.
+### getExchangeToken {#getexchangetoken}
+`getExchangeToken(string $appId = NULL, string $appSecret = NULL)`  
+Returns an exchange token string which can be sent back to clients and exchanged for a device-linked access token.  You need this when your user did not log in on a particular device, but you want to be able to make Graph API calls from that device as this user.
+### validate {#validatei}
+`validate(string $appId = NULL, string $appSecret = NULL)`  
+Ensures that a session is valid, throwing an exception if not.  It does this by fetching the token info, ensuring the app ID in the token info matches the given (or default) app ID, ensuring the token itself is valid, and ensuring that the expiration time has not passed.
+</card>