Merge branch '5.x'

Author: yguedidi

CHANGELOG.md

@@ -20,6 +20,21 @@ Starting with version 5, the Facebook PHP SDK follows [SemVer](http://semver.org
 
 Version 5 of the Facebook PHP SDK is a complete refactor of version 4. It comes loaded with lots of new features and a friendlier API.
 
+- 5.6.1 (2017-08-16)
+  - Fixed doc block syntax that interfered with Doctrine (#844)
+- 5.6.0 (2017-07-23)
+  - Bump Graph API version to v2.10 (#829)
+- 5.5.0 (2017-04-20)
+  - Added support for batch options (#713)
+  - Bump Graph API version to v2.9.
+- 5.4.4 (2017-01-19)
+  - Added the `application/octet-stream` MIME type for SRT files (#734)
+- 5.4.3 (2016-12-30)
+  - Fixed a bug that would throw a type error in `GraphEdge` in some cases (#715)
+- 5.4.2 (2016-11-15)
+  - Added check for [PHP 7 CSPRNG](http://php.net/manual/en/function.random-bytes.php) first to keep mcrypt deprecation messages from appearing in PHP 7.1 (#692)
+- 5.4.1 (2016-10-18)
+  - Fixed a bug that was not properly parsing response headers when they contained the colon `:` character. (#679)
 - 5.4.0 (2016-10-12)
   - Bump Graph API version to v2.8.
   - Auto-cast `cover` field to `GraphCoverPhoto` and `picture` field to `GraphPicture` in `GraphPage`. (#655)

CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated.

CONTRIBUTING.md

@@ -3,7 +3,16 @@ Contributing
 
 Contributions are **welcome** and will be fully **credited**.
 
-We accept contributions via Pull Requests on [Github](https://github.com/facebook/facebook-php-sdk-v4).
+We accept contributions via Pull Requests on [Github](https://github.com/facebook/php-graph-sdk/pull/new).
+
+The current stable major version is v5. The v6 is under active development.
+
+This means any new feature MUST target v6 (`master` branch).
+
+The v5 (`5.x` branch) is maintained only for bug fixes, node/edge updates or documentation improvements.
+
+## Code of Conduct
+The code of conduct is described in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
 
 
 ## Pull Requests

docs/reference/Facebook.md

@@ -327,6 +327,23 @@ $batchResponse = $fb->sendBatchRequest($requests);
 
 [See a full batch example](../examples/batch_request.md).
 
+## newBatchRequest()
+```php
+public Facebook\FacebookBatchRequest newBatchRequest(
+    string|AccessToken|null $accessToken,
+    string|null $graphVersion
+)
+```
+
+Instantiates an empty `Facebook\FacebookBatchRequest`.
+To populate it use the [`Facebook\FacebookBatchRequest::add()`](FacebookBatchRequest.md#add) method.
+
+The `$accessToken` and `$graphVersion` arguments are the same as `get()` above.
+If any of the requests contained in the batch request does not have either the `$accessToken` or the `$graphVersion` set,
+it fallbacks to the values provided in the instantiation of the batch request.
+
+[See a full batch example](../examples/batch_request.md).
+
 ## getRedirectLoginHelper()
 ```php
 public Facebook\Helper\FacebookRedirectLoginHelper getRedirectLoginHelper()

docs/reference/FacebookBatchRequest.md

@@ -4,7 +4,8 @@ Represents a batch request that will be sent to the Graph API.
 
 ## Facebook\FacebookBatchRequest
 
-You can instantiate a new `FacebookBatchRequest` entity directly by sending the arguments to the constructor.
+You can instantiate a new `FacebookBatchRequest` entity directly by sending the arguments to the constructor or
+by using the [`Facebook\Facebook::newBatchRequest()`](Facebook.md#newBatchRequest) factory method.
 
 ```php
 use Facebook\FacebookBatchRequest;
@@ -61,9 +62,9 @@ Since the `Facebook\FacebookBatchRequest` is extended from the [`Facebook\Facebo
 ### add()
 ```php
 public add(
-  array|Facebook\FacebookBatchRequest $request,
-  string|null $name
-  )
+    array|Facebook\FacebookBatchRequest $request,
+    string|null $name
+)
 ```
 Adds a request to be sent in the batch request. The `$request` can be a single [`Facebook\FacebookRequest`](FacebookRequest.md) or an array of `Facebook\FacebookRequest`'s.
 

docs/reference/GraphNode.md

@@ -26,7 +26,7 @@ $response = $fb->get('/something');
 $graphNode = $response->getGraphNode();
 
 // Get the response typed as a GraphUser
-$user = $response->getGraphUser());
+$user = $response->getGraphUser();
 
 // Get the response typed as a GraphPage
 $page = $response->getGraphPage();
@@ -162,7 +162,7 @@ Returns the `hometown` property for the user as a `Facebook\GraphNode\GraphPage`
 
 ### getSignificantOther()
 ```php
-public Facebook\GraphNode\GraphUser|null getHometown()
+public Facebook\GraphNode\GraphUser|null getSignificantOther()
 ```
 Returns the `significant_other` property for the user as a `Facebook\GraphNode\GraphUser` if present.
 

src/Authentication/OAuth2Client.php

@@ -125,8 +125,8 @@ public function debugToken($accessToken)
      * Generates an authorization URL to begin the process of authenticating a user.
      *
      * @param string $redirectUrl The callback URL to redirect to.
-     * @param array  $scope       An array of permissions to request.
      * @param string $state       The CSPRNG-generated CSRF value.
+     * @param array  $scope       An array of permissions to request.
      * @param array  $params      An array of parameters to generate URL.
      * @param string $separator   The separator to use in http_build_query().
      *

src/Exception/FacebookResponseException.php

@@ -113,7 +113,9 @@ public static function create(FacebookResponse $response)
             // API Throttling
             case 4:
             case 17:
+            case 32:
             case 341:
+            case 613:
                 return new static($response, new FacebookThrottleException($message, $code));
 
             // Duplicate Post

src/Facebook.php

@@ -482,6 +482,27 @@ public function sendBatchRequest(array $requests, $accessToken = null, $graphVer
         return $this->lastResponse = $this->client->sendBatchRequest($batchRequest);
     }
 
+    /**
+     * Instantiates an empty FacebookBatchRequest entity.
+     *
+     * @param  AccessToken|string|null $accessToken  The top-level access token. Requests with no access token
+     *                                               will fallback to this.
+     * @param  string|null             $graphVersion The Graph API version to use.
+     * @return FacebookBatchRequest
+     */
+    public function newBatchRequest($accessToken = null, $graphVersion = null)
+    {
+        $accessToken = $accessToken ?: $this->defaultAccessToken;
+        $graphVersion = $graphVersion ?: $this->defaultGraphVersion;
+
+        return new FacebookBatchRequest(
+            $this->app,
+            [],
+            $accessToken,
+            $graphVersion
+        );
+    }
+
     /**
      * Instantiates a new FacebookRequest entity.
      *

src/FacebookBatchRequest.php

@@ -62,16 +62,17 @@ public function __construct(FacebookApp $app = null, array $requests = [], $acce
     }
 
     /**
-     * A a new request to the array.
+     * Adds a new request to the array.
      *
      * @param FacebookRequest|array $request
-     * @param string|null           $name
+     * @param string|null|array     $options Array of batch request options e.g. 'name', 'omit_response_on_success'.
+     *                                       If a string is given, it is the value of the 'name' option.
      *
      * @return FacebookBatchRequest
      *
      * @throws \InvalidArgumentException
      */
-    public function add($request, $name = null)
+    public function add($request, $options = null)
     {
         if (is_array($request)) {
             foreach ($request as $key => $req) {
@@ -85,17 +86,28 @@ public function add($request, $name = null)
             throw new \InvalidArgumentException('Argument for add() must be of type array or FacebookRequest.');
         }
 
+        if (null === $options) {
+            $options = [];
+        } elseif (!is_array($options)) {
+            $options = ['name' => $options];
+        }
+
         $this->addFallbackDefaults($request);
+
+        // File uploads
+        $attachedFiles = $this->extractFileAttachments($request);
+
+        $name = isset($options['name']) ? $options['name'] : null;
+
+        unset($options['name']);
+
         $requestToAdd = [
             'name' => $name,
             'request' => $request,
+            'options' => $options,
+            'attached_files' => $attachedFiles,
         ];
 
-        // File uploads
-        $attachedFiles = $this->extractFileAttachments($request);
-        if ($attachedFiles) {
-            $requestToAdd['attached_files'] = $attachedFiles;
-        }
         $this->requests[] = $requestToAdd;
 
         return $this;
@@ -189,8 +201,15 @@ public function convertRequestsToJson()
     {
         $requests = [];
         foreach ($this->requests as $request) {
-            $attachedFiles = isset($request['attached_files']) ? $request['attached_files'] : null;
-            $requests[] = $this->requestEntityToBatchArray($request['request'], $request['name'], $attachedFiles);
+            $options = [];
+
+            if (null !== $request['name']) {
+                $options['name'] = $request['name'];
+            }
+
+            $options += $request['options'];
+
+            $requests[] = $this->requestEntityToBatchArray($request['request'], $options, $request['attached_files']);
         }
 
         return json_encode($requests);
@@ -215,14 +234,22 @@ public function validateBatchRequestCount()
     /**
      * Converts a Request entity into an array that is batch-friendly.
      *
-     * @param FacebookRequest $request       The request entity to convert.
-     * @param string|null     $requestName   The name of the request.
-     * @param string|null     $attachedFiles Names of files associated with the request.
+     * @param FacebookRequest   $request       The request entity to convert.
+     * @param string|null|array $options       Array of batch request options e.g. 'name', 'omit_response_on_success'.
+     *                                         If a string is given, it is the value of the 'name' option.
+     * @param string|null       $attachedFiles Names of files associated with the request.
      *
      * @return array
      */
-    public function requestEntityToBatchArray(FacebookRequest $request, $requestName = null, $attachedFiles = null)
+    public function requestEntityToBatchArray(FacebookRequest $request, $options = null, $attachedFiles = null)
     {
+
+        if (null === $options) {
+            $options = [];
+        } elseif (!is_array($options)) {
+            $options = ['name' => $options];
+        }
+
         $compiledHeaders = [];
         $headers = $request->getHeaders();
         foreach ($headers as $name => $value) {
@@ -242,18 +269,12 @@ public function requestEntityToBatchArray(FacebookRequest $request, $requestName
             $batch['body'] = $body;
         }
 
-        if (isset($requestName)) {
-            $batch['name'] = $requestName;
-        }
+        $batch += $options;
 
-        if (isset($attachedFiles)) {
+        if (null !== $attachedFiles) {
             $batch['attached_files'] = $attachedFiles;
         }
 
-        // @TODO Add support for "omit_response_on_success"
-        // @TODO Add support for "depends_on"
-        // @TODO Add support for JSONP with "callback"
-
         return $batch;
     }