The Facebook SDK for PHP is made up of many components. The Facebook\Facebook
service class provides an easy interface for working with all the components of the SDK.
To instantiate a new Facebook\Facebook
service, pass an array of configuration options to the constructor.
$fb = new Facebook\Facebook([ 'app_id' => '{app-id}', 'app_secret' => '{app-secret}', 'default_graph_version' => 'v2.3', // . . . ]);
Usage:
// Send a GET request $response = $fb->get('/me'); // Send a POST request $response = $fb->post('/me/feed', ['message' => 'Foo message']); // Send a DELETE request $response = $fb->delete('/{node-id}');
If you don't provide a default_access_token
in the configuration options, or you wish to use a different access token than the default, you can explicitly pass the access token as an argument to the get()
, post()
, and delete()
methods.
$res = $fb->get('/me', '{access-token}'); $res = $fb->post('/me/feed', ['foo' => 'bar'], '{access-token}'); $res = $fb->delete('/{node-id}', '{access-token}');
Although the Facebook\Facebook
service tries to make the SDK as easy as possible to use, it also makes it easy to customize with configuration options.
Full configuration options list:
$fb = new Facebook\Facebook([ 'app_id' => '{app-id}', 'app_secret' => '{app-secret}', 'default_access_token' => '{access-token}', 'enable_beta_mode' => true, 'default_graph_version' => 'v2.3', 'http_client_handler' => 'guzzle', 'persistent_data_handler' => 'memory', 'url_detection_handler' => new MyUrlDetectionHandler(), 'pseudo_random_string_generator' => new MyPseudoRandomStringGenerator(), ]);
app_id
The ID of your Facebook app (required).
app_secret
The secret of your Facebook app (required).
default_access_token
The default fallback access token to use if one is not explicitly provided. The value can be of type string
or Facebook\AccessToken
. If any other value is provided an InvalidArgumentException
will be thrown. Defaults to null
.
enable_beta_mode
Enable beta mode so that requests are made to the graph.beta.facebook.com
endpoint. Set to boolean true
to enable or false
to disable. Defaults to false
.
default_graph_version
Allows you to overwrite the default Graph version number set in Facebook\Facebook::DEFAULT_GRAPH_VERSION
. Set this as a string as it would appear in the Graph url, e.g. v2.0
. Defaults to the latest version of Graph.
http_client_handler
Allows you to overwrite the default HTTP client.
By default, the SDK will try to use cURL as the HTTP client. If a cURL implementation cannot be found, it will fallback to a stream wrapper HTTP client. You can force either HTTP client implementations by setting this value to curl
or stream
.
If you wish to use Guzzle, you can set this value to guzzle
, but it requires that you install Guzzle with composer.
If you wish to write your own HTTP client, you can code your HTTP client to the [Facebook\HttpClients\FacebookHttpClientInterface](/docs/php/FacebookHttpClientInterface)
and set this value to an instance of your custom client.
$fb = new Facebook([ 'http_client_handler' => new MyCustomHttpClient(), ]);
If any other value is provided an InvalidArgumentException
will be thrown.
persistent_data_handler
Allows you to overwrite the default persistent data store.
By default, the SDK will try to use the native PHP session for the persistent data store. There is also an in-memory persistent data handler which is useful when running your script from the command line for example. You can force either implementation by setting this value to session
or memory
.
If you wish to write your own persistent data handler, you can code your persistent data handler to the [Facebook\PersistentData\PersistentDataInterface](/docs/php/PersistentDataInterface)
and set the value of persistent_data_handler
to an instance of your custom handler.
$fb = new Facebook([ 'persistent_data_handler' => new MyCustomPersistentDataHandler(), ]);
If any other value is provided an InvalidArgumentException
will be thrown.
url_detection_handler
Allows you to overwrite the default URL detection logic.
The SDK will do its best to detect the proper current URL but this can sometimes get tricky if you have a very customized environment. You can write your own URL detection logic that implements the [Facebook\Url\UrlDetectionInterface](/docs/php/UrlDetectionInterface)
and set the value of url_detection_handler
to an instance of your custom URL detector.
$fb = new Facebook([ 'url_detection_handler' => new MyUrlDetectionHandler(), ]);
If any other value is provided an InvalidArgumentException
will be thrown.
pseudo_random_string_generator
Allows you to overwrite the default cryptographically secure pseudo-random string generator.
Generating random strings in PHP is easy but generating cryptographically secure random strings is another matter. By default the SDK will attempt to detect a suitable to cryptographically secure random string generator for you. If a cryptographically secure method cannot be detected, a Facebook\Exceptions\FacebookSDKException
will be thrown.
You can force a specific implementation of the CSPRSG's provided in the SDK by setting pseudo_random_string_generator
to one of the following methods: mcrypt
, openssl
and urandom
.
$fb = new Facebook([ 'pseudo_random_string_generator' => 'openssl', ]);
You can write your own CSPRSG that implements the [Facebook\PseudoRandomString\PseudoRandomStringGeneratorInterface](/docs/php/PseudoRandomStringGeneratorInterface)
and set the value of pseudo_random_string_generator
to an instance of your custom generator.
$fb = new Facebook([ 'pseudo_random_string_generator' => new MyPseudoRandomStringGenerator(), ]);
If any other value is provided an InvalidArgumentException
will be thrown.
The only required configuration options are app_id
and app_secret
. However, the SDK will look to environment variables for the app ID and app secret.
To take advantage of this feature, simply set an environment variable named FACEBOOK_APP_ID
with your Facebook app ID and set an environment variable named FACEBOOK_APP_SECRET
with your Facebook app secret and you will be able to instantiate the Facebook\Facebook
service without setting any configuration in the constructor.
$fb = new Facebook\Facebook();
public FacebookApp getApp()
Returns the instance of Facebook\FacebookApp
for the instantiated service.
public Facebook\FacebookClient getClient()
Returns the instance of Facebook\FacebookClient
for the instantiated service.
public Facebook\Authentication\OAuth2Client getOAuth2Client()
Returns an instance of Facebook\Authentication\OAuth2Client
.
public Facebook\FacebookResponse|Facebook\FacebookBatchResponse|null getLastResponse()
Returns the last response received from the Graph API in the form of a Facebook\FacebookResponse
or Facebook\FacebookBatchResponse
.
public Facebook\Url\UrlDetectionInterface getUrlDetectionHandler()
Returns an instance of Facebook\Url\UrlDetectionInterface
.
public Facebook\Authentication\AccessToken|null getDefaultAccessToken()
Returns the default fallback AccessToken
entity that is being used with every request to Graph. This value can be set with the configuration option default_access_token
or by using setDefaultAccessToken()
.
public setDefaultAccessToken(string|Facebook\AccessToken $accessToken)
Sets the default fallback access token to be use with all requests sent to Graph. The access token must be a string.
$fb->setDefaultAccessToken('{my-access-token}'); // . . . OR . . . $accessToken = new Facebook\Authentication\AccessToken('{my-access-token}'); $fb->setDefaultAccessToken($accessToken->getValue());
This setting will overwrite the value from default_access_token
option if it was passed to the Facebook\Facebook
constructor.
public string getDefaultGraphVersion()
Returns the default version of Graph. If the default_graph_version
configuration option was not set, this will default to Facebook\Facebook::DEFAULT_GRAPH_VERSION
.
public Facebook\FacebookResponse get( string $endpoint, string|AccessToken|null $accessToken, string|null $eTag, string|null $graphVersion )
Sends a GET request to Graph and returns a Facebook\FacebookResponse
.
$endpoint
The url to send to Graph without the version prefix (required).
$fb->get('/me');
$accessToken
The access token (as a string or AccessToken
entity) to use for the request. If none is provided, the SDK will assume the value from the default_access_token
configuration option if it was set.
$eTag
Graph supports eTags. Set this to the eTag from a previous request to get a 304 Not Modified
response if the data has not changed.
$graphVersion
This will overwrite the Graph version that was set in the default_graph_version
configuration option.
public Facebook\FacebookResponse post( string $endpoint, array $params, string|AccessToken|null $accessToken, string|null $eTag, string|null $graphVersion )
Sends a POST request to Graph and returns a Facebook\FacebookResponse
.
The arguments are the same as get()
above with the exception of $params
.
$params
The associative array of params you want to send in the body of the POST request.
$response = $fb->post('/me/feed', ['message' => 'Foo message']);
public Facebook\FacebookResponse delete( string $endpoint, array $params, string|AccessToken|null $accessToken, string|null $eTag, string|null $graphVersion )
Sends a DELETE request to Graph and returns a Facebook\FacebookResponse
.
The arguments are the same as post()
above.
$response = $fb->delete('/{node-id}', ['object' => '1234']);
public Facebook\FacebookRequest request( string $method, string $endpoint, array $params, string|AccessToken|null $accessToken, string|null $eTag, string|null $graphVersion )
Instantiates a new Facebook\FacebookRequest
entity but does not send the request to Graph. This is useful for creating a number of requests to be sent later in a batch request (see sendBatchRequest()
below).
The arguments are the same as post()
above with the exception of $method
.
$method
The HTTP request verb to use for this request. This can be set to any verb that the $graphVersion
of Graph supports, e.g. GET
, POST
, DELETE
, etc.
$request = $fb->request('GET', '/{node-id}');
public Facebook\FacebookResponse sendRequest( string $method, string $endpoint, array $params, string|AccessToken|null $accessToken, string|null $eTag, string|null $graphVersion )
Sends a request to the Graph API.
$response = $fb->sendRequest('GET', '/me', [], '{access-token}', 'eTag', 'v2.2');
public Facebook\FacebookBatchResponse sendBatchRequest( array $requests, string|AccessToken|null $accessToken, string|null $graphVersion )
Sends an array of Facebook\FacebookRequest
entities as a batch request to Graph.
The $accessToken
and $graphVersion
arguments are the same as get()
above.
$requests
An array of Facebook\FacebookRequest
entities. This can be a numeric or associative array but every value of the array has to be an instance of Facebook\FacebookRequest
.
If the requests are sent as an associative array, the key will be used as the name
of the request so that it can be referenced by another request. See more on batch request naming and using JSONPath.
$requests = [ 'me' => $fb->request('GET', '/me'), 'you' => $fb->request('GET', '/1337', [], '{user-b-access-token}'), 'my_post' => $fb->request('POST', '/1337/feed', ['message' => 'Hi!']), ]; $batchResponse = $fb->sendBatchRequest($requests);
public Facebook\Helpers\FacebookRedirectLoginHelper getRedirectLoginHelper()
Returns a Facebook\Helpers\FacebookRedirectLoginHelper
which is used to generate a "Login with Facebook" link and obtain an access token from a redirect.
$helper = $fb->getRedirectLoginHelper();
public Facebook\Helpers\FacebookJavaScriptHelper getJavaScriptHelper()
Returns a Facebook\Helpers\FacebookJavaScriptHelper
which is used to access the signed request stored in the cookie set by the SDK for JavaScript.
$helper = $fb->getJavaScriptHelper();
public Facebook\Helpers\FacebookCanvasHelper getCanvasHelper()
Returns a Facebook\Helpers\FacebookCanvasHelper
which is used to access the signed request that is POST
ed to canvas apps.
$helper = $fb->getCanvasHelper();
public Facebook\Helpers\FacebookPageTabHelper getPageTabHelper()
Returns a Facebook\Helpers\FacebookPageTabHelper
which is used to access the signed request that is POST
ed to canvas apps and provides a number of helper methods useful for apps living in a page tab context.
$helper = $fb->getPageTabHelper();
public Facebook\GraphNodes\GraphEdge|null next(Facebook\GraphNodes\GraphEdge $graphEdge)
Requests and returns the next page of results in a Facebook\GraphNodes\GraphEdge
collection. If the next page returns no results, null
will be returned.
// Iterate over 5 pages max $maxPages = 5; // Get a list of photo nodes from the /photos edge $response = $fb->get('/me/photos?fields=id,source,likes&limit=5'); $photosEdge = $response->getGraphEdge(); if (count($photosEdge) > 0) { $pageCount = 0; do { foreach ($photosEdge as $photo) { var_dump($photo->asArray()); // Deep pagination is supported on child GraphEdge's $likes = $photo['likes']; do { echo '<p>Likes:</p>' . "\n\n"; var_dump($likes->asArray()); } while ($likes = $fb->next($likes)); } $pageCount++; } while ($pageCount < $maxPages && $photosEdge = $fb->next($photosEdge)); }
public Facebook\GraphNodes\GraphEdge|null previous(Facebook\GraphNodes\GraphEdge $graphEdge)
Requests and returns the previous page of results in a Facebook\GraphNodes\GraphEdge
collection. Functions just like next()
above, but in the opposite direction of pagination.
public Facebook\FileUpload\FacebookFile fileToUpload(string $pathToFile)
When a valid path to a local or remote file is provided, fileToUpload()
will returns a FacebookFile
entity that can be used in the params in a POST request to Graph.
// Upload a photo for a user $data = [ 'message' => 'A neat photo upload example. Neat.', 'source' => $fb->fileToUpload('/path/to/photo.jpg'), ]; try { $response = $fb->post('/me/photos', $data); } catch(FacebookSDKException $e) { echo 'Error: ' . $e->getMessage(); exit; } $graphNode = $response->getGraphNode(); echo 'Photo ID: ' . $graphNode['id'];
public Facebook\FileUpload\FacebookVideo videoToUpload(string $pathToVideoFile)
Uploading videos to Graph requires that you send the request to https://graph-video.facebook.com
instead of the normal https://graph.facebook.com
host name. When you use videoToUpload()
to upload a video, the SDK for PHP will automatically point the request to the graph-video.facebook.com
host name for you.
// Upload a video for a user $data = [ 'title' => 'My awesome video', 'description' => 'More info about my awesome video.', 'source' => $fb->videoToUpload('/path/to/video.mp4'), ]; try { $response = $fb->post('/me/videos', $data); } catch(FacebookSDKException $e) { echo 'Error: ' . $e->getMessage(); exit; } $graphNode = $response->getGraphNode(); echo 'Video ID: ' . $graphNode['id'];