facebook/facebook-php-sdk-v4 — pull request #169 by SammyK (2014-07-25 19:20:32+00:00)
Title: [4.1] Simple request response refactor

Phew! OK, let's see everyone can agree on this setup. :) This isn't 100% 4.1 feature packed but we can use it as a good starting point if everything is OK.

# Setup

To make a request to Graph, you need to instantiate a new `FacebookApp` to hold your app config. You'll also need a `FacebookClient` to send request entities to Graph.

```php
use Facebook\Entities\FacebookApp;
use Facebook\FacebookClient;

$facebookApp = new FacebookApp('{app-id}', '{app-secret}');
$facebookClient = new FacebookClient(/* $httpClientHandler, $enableBeta */);
```

# Simple GET Request

```php
use Facebook\Entities\FacebookRequest;

$request = new FacebookRequest($facebookApp, '{access-token}', 'GET', '/me'/*, $params, $eTag, $graphVersion */);
$facebookResponse = $facebookClient->sendRequest($request);

$userProfile = $facebookResponse->getGraphObject();
```

# Simple POST Request

```php
use Facebook\Entities\FacebookRequest;

$request = new FacebookRequest($facebookApp, '{access-token}', 'POST', '/me/feed', ['message'=>'Foo message!']/*, $eTag, $graphVersion */);
$facebookResponse = $facebookClient->sendRequest($request);

$data = $facebookResponse->getDecodedBody();

$id = $data['id'];
```

# Simple DELETE Request

```php
use Facebook\Entities\FacebookRequest;

$request = new FacebookRequest($facebookApp, '{access-token}', 'DELETE', '/{some-id}'/*, $params, $eTag, $graphVersion */);
$facebookResponse = $facebookClient->sendRequest($request);

$data = $facebookResponse->getDecodedBody();

$wasSuccessful = $data['was_successful'];
```

# Batch Request Setup

```php
use Facebook\Entities\FacebookBatchRequest;

$batchRequest = new FacebookBatchRequest(/* $facebookApp, '{access-token}', [$requests], $graphVersion */);
```

# Three ways to add requests to batch request

## Via constructor

```php
use Facebook\Entities\FacebookBatchRequest;
use Facebook\Entities\FacebookRequest;

// If $facebookApp and $accessToken on a `FacebookRequest` are null, it will fallback to the parent `FacebookBatchRequest` app & token.
$requests = [
new FacebookRequest(null, null, 'GET', '/me'),
new FacebookRequest($facebookApp, '{access-token}', 'POST', '/me/feed', ['foo'=>'bar']),
];
$batchRequest = new FacebookBatchRequest($facebookApp, '{access-token}', $requests);
```

## Via `add()` as an array

```php
use Facebook\Entities\FacebookRequest;

// Numeric array:
$requests = [
new FacebookRequest(null, null, 'GET', '/me'),
new FacebookRequest($facebookApp, '{access-token}', 'POST', '/me/feed', ['foo'=>'bar']),
];
$batchRequest->add($requests);

// ... OR ...

// Associative array:
// The key of the array will be used to assign a name to the request.
$requests = [
'named-request-one' => new FacebookRequest(null, null, 'GET', '/me'),
'named-request-two' => new FacebookRequest($facebookApp, '{access-token}', 'POST', '/me/feed', ['foo'=>'bar']),
];
$batchRequest->add($requests);
```

## Via `add()` as a `FacebookRequest`

```php
$batchRequest->add(new FacebookRequest(null, null, 'GET', '/me'));
$batchRequest->add(new FacebookRequest($facebookApp, {access-token}, 'GET', '/me'), 'my-reqest-name');
```

# Getting a response from batch request

```php
$facebookBatchResponse = $facebookClient->sendBatchRequest($batchRequest);

foreach ($facebookBatchResponse as $response) {
if (!$response->isError()) {
// $response is a `FacebookResponse` entity
} else {
$e = $response->getThrownException();
echo $e->getMessage();
}
}
```

# Helpers

You also pass along the `FacebookApp` and `FacebookClient` into the helpers like so:

```php
$app = new FacebookApp('123', 'foo_app_secret');
$helper = new FacebookRedirectLoginHelper($app);
```

# AccessToken

The `AccessToken` entity requires `FacebookApp` and `FacebookClient` for requests that call Graph. For example:

```php
$accessTokenFromCode = AccessToken::getAccessTokenFromCode('foo_code', $app, $client);
```

I think this could be done better for the future. I'd like to simplify the `AccessToken` entity to only hold data about the access token. And any calls to graph could be done with a `FacebookAccessTokenHelper`. What do you guys think?

# Simplified `FacebookHttpClientInterface`

I also simplified the `FacebookHttpClientInterface` so that the request headers could be sent as an argument in the `send()` method.

# Integration Tests Labled

The tests that actually touch Graph are labeled "integration". So you can run the test suite with:

```bash
$ phpunit --exclude-group integration
```

And it won't touch the live version of Graph. So now we can incorporate Travis CI without any issues! :)

# TODO

For the next few PR's:

- Factories to make `FacebookRequest`'s and `FacebookBatchRequest`'s
- Collections on `GrahObject`
- Adding `GraphList` with pagination