# Facebook service class for the Facebook SDK for PHP
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.
## Facebook\Facebook {#overview}
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.4',
// . . .
]);
~~~~
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}');
~~~~
## Configuration options {#config}
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.4',
'http_client_handler' => 'guzzle',
'persistent_data_handler' => 'memory',
'url_detection_handler' => new MyUrlDetectionHandler(),
'pseudo_random_string_generator' => new MyPseudoRandomStringGenerator(),
]);
~~~~
### `app_id` {#appid}
The ID of your Facebook app (required).
### `app_secret` {#appsecret}
The secret of your Facebook app (required).
### `default_access_token` {#defaulttoken}
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` {#enablebeta}
Enable [beta mode](/docs/support/beta-tier/) so that request are made to the [https://graph.beta.facebook.com](https://graph.beta.facebook.com/) endpoint. Set to boolean `true` to enable or `false` to disable. Defaults to `false`.
### `default_graph_version` {#defaultversion}
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` {#httpclient}
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](http://docs.guzzlephp.org/en/latest/) 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` {#datahandler}
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` {#urlhandler}
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` {#prsg}
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.
## Environment variables fallback {#env-vars}
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();
~~~~
# Instance Methods {#instance-methods}
## getApp() {#get-app}
~~~~
public FacebookApp getApp()
~~~~
Returns the instance of `Facebook\FacebookApp` for the instantiated service.
## getClient() {#get-client}
~~~~
public Facebook\FacebookClient getClient()
~~~~
Returns the instance of [`Facebook\FacebookClient`](/docs/php/FacebookClient) for the instantiated service.
## getOAuth2Client() {#get-oauth2-client}
~~~~
public Facebook\Authentication\OAuth2Client getOAuth2Client()
~~~~
Returns an instance of [`Facebook\Authentication\OAuth2Client`](/docs/php/OAuth2Client).
## getLastResponse() {#get-last-response}
~~~~
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`.
## getUrlDetectionHandler() {#get-url-detection-handler}
~~~~
public Facebook\Url\UrlDetectionInterface getUrlDetectionHandler()
~~~~
Returns an instance of [`Facebook\Url\UrlDetectionInterface`](/docs/php/UrlDetectionInterface).
## getDefaultAccessToken() {#get-default-access-token}
~~~~
public Facebook\Authentication\AccessToken|null getDefaultAccessToken()
~~~~
Returns the default fallback [`AccessToken`](/docs/php/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()`.
## setDefaultAccessToken() {#set-default-access-token}
~~~~
public setDefaultAccessToken(string|Facebook\AccessToken $accessToken)
~~~~
Sets the default fallback access token to be use with all requests sent to Graph. The access token can be a string or an instance of [`AccessToken`](/docs/php/AccessToken).
~~~~
$fb->setDefaultAccessToken('{my-access-token}');
// . . . OR . . .
$accessToken = new Facebook\Authentication\AccessToken('{my-access-token}');
$fb->setDefaultAccessToken($accessToken);
~~~~
This setting will overwrite the value from `default_access_token` option if it was passed to the `Facebook\Facebook` constructor.
## getDefaultGraphVersion() {#get-default-graph-version}
~~~~
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`.
## get() {#get}
~~~~
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](/docs/reference/ads-api/etags-reference/). 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.
## post() {#post}
~~~~
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']);
~~~~
## delete() {#delete}
~~~~
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']);
~~~~
## request() {#request}
~~~~
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}');
~~~~
## sendRequest() {#send-request}
~~~~
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');
~~~~
## sendBatchRequest() {#send-batch-request}
~~~~
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](/docs/graph-api/making-multiple-requests/#operations).
~~~~
$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);
~~~~
[See a full batch example](/docs/php/howto/example_batch_request).
## getRedirectLoginHelper() {#get-redirect-login-helper}
~~~~
public Facebook\Helpers\FacebookRedirectLoginHelper getRedirectLoginHelper()
~~~~
Returns a [`Facebook\Helpers\FacebookRedirectLoginHelper`](/docs/php/FacebookRedirectLoginHelper) which is used to generate a "Login with Facebook" link and obtain an access token from a redirect.
~~~~
$helper = $fb->getRedirectLoginHelper();
~~~~
## getJavaScriptHelper() {#get-javascript-helper}
~~~~
public Facebook\Helpers\FacebookJavaScriptHelper getJavaScriptHelper()
~~~~
Returns a [`Facebook\Helpers\FacebookJavaScriptHelper`](/docs/php/FacebookJavaScriptHelper) which is used to access the signed request stored in the cookie set by the SDK for JavaScript.
~~~~
$helper = $fb->getJavaScriptHelper();
~~~~
## getCanvasHelper() {#get-canvas-helper}
~~~~
public Facebook\Helpers\FacebookCanvasHelper getCanvasHelper()
~~~~
Returns a [`Facebook\Helpers\FacebookCanvasHelper`](/docs/php/FacebookCanvasHelper) which is used to access the signed request that is `POST`ed to canvas apps.
~~~~
$helper = $fb->getCanvasHelper();
~~~~
## getPageTabHelper() {#get-page-tab-helper}
~~~~
public Facebook\Helpers\FacebookPageTabHelper getPageTabHelper()
~~~~
Returns a [`Facebook\Helpers\FacebookPageTabHelper`](/docs/php/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();
~~~~
## next() {#next}
~~~~
public Facebook\GraphNodes\GraphEdge|null next(Facebook\GraphNodes\GraphEdge $graphEdge)
~~~~
Requests and returns the next page of results in a [`Facebook\GraphNodes\GraphEdge`](/docs/php/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 'Likes:
' . "\n\n";
var_dump($likes->asArray());
} while ($likes = $fb->next($likes));
}
$pageCount++;
} while ($pageCount < $maxPages && $photosEdge = $fb->next($photosEdge));
}
~~~~
## previous() {#previous}
~~~~
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.
## fileToUpload() {#file-to-upload}
~~~~
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'];
~~~~
## videoToUpload() {#video-to-upload}
~~~~
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'];
~~~~