Update 4.1 docs to refer to version 5

Author: SammyK

CHANGELOG.md

@@ -1,37 +1,93 @@
 # CHANGELOG
 
-As you may have already noticed, the Facebook SDK v4 does not follow strict [semver](http://semver.org/). The versioning format used for this SDK follows `4.MAJOR.(MINOR|PATCH)`. The `MINOR` and `PATCH` versions are squashed together but there shouldn't be any breaking changes between `MINOR|PATCH` releases.
+Starting with version 5, the Facebook PHP SDK follows [SemVer](http://semver.org/).
 
 
-## 4.1.x
+## 5.0.x
 
-- 4.1.0 (2015-??-??)
-  - Added batch support
-  - Added `graph.beta.facebook.com` support
-  - Moved exception classes to `Exception\*` directory
-  - Moved response collection objects to `GraphNodes\*` directory
-  - Moved helpers to `Helpers\*` directory
-  - Moved `FacebookRequest` and `FacebookResponse` to `Entities\*` directory
-  - Killed `FacebookSession` in favor of `Facebook\AccessToken`
-  - Added `FacebookClient` service
-  - Renamed `FacebookRequestException` to `FacebookResponseException`
-  - Renamed `FacebookHttpable` to `FacebookHttpClientInterface`
-  - Updated the API for the helpers.
-  - Refactored request/response handling
-  - Added support for "rerequest" authorization
-  - [`AccessToken`] Added serialization support
-  - Added `ext-mbstring` to composer require
-  - Added `Facebook\FacebookApp` entity
-  - Namespaced tests
-  - Grouped functional tests under `functional` group
-  - Added `Facebook\Facebook` super service
-  - Added this CHANGELOG. Hi! :)
+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.0 (2015-??-??)
+  - New features
+    - Added the `Facebook\Facebook` super service for an easier API
+    - Improved "reauthentication" and "rerequest" support
+    - Requests/Responses
+      - Added full batch support
+      - Added full file upload support for videos & photos
+      - Added methods to make pagination easier
+      - Added "deep" pagination support so that Graph edges embedded in a Graph node can be paginated over easily
+      - Beta support at `graph.beta.facebook.com`
+      - Added `getMetaData()` to `GraphList` to obtain all the metadata associated with a list of Graph nodes
+      - Full nested param support
+      - Many improvements to the Graph node subtypes
+    - New injectable interfaces
+      - Added a `PersistentDataInterface` for custom persistent data handling
+      - Added a `PseudoRandomStringGeneratorInterface` for customizable CSPRNG's 
+      - Added a `UrlDetectionInterface` for custom URL-detection logic 
+  - Codebase changes
+    - Moved exception classes to `Exception\*` directory
+    - Moved response collection objects to `GraphNodes\*` directory
+    - Moved helpers to `Helpers\*` directory
+    - Killed `FacebookSession` in favor of the `AccessToken` entity
+    - Added `FacebookClient` service
+    - Renamed `FacebookRequestException` to `FacebookResponseException`
+    - Renamed `FacebookHttpable` to `FacebookHttpClientInterface`
+    - Added `FacebookApp` entity that contains info about the Facebook app
+    - Updated the API for the helpers
+  - Tests
+    - Added namespaces to the tests
+    - Grouped functional tests under `functional` group
+  - Other changes
+    - Made PSR-2 compliant
+    - Adopted SemVer
+    - Completely refactored request/response handling
+    - Refactored the OAuth 2.0 logic
+    - Added `ext-mbstring` to composer require
+    - Added this CHANGELOG. Hi! :)
+
+
+## 4.1-dev
+
+Since the Facebook PHP SDK didn't follow SemVer in version 4.x, the master branch was going to be released as 4.1. However, the SDK switched to SemVer in v5.0. So any references on the internet to version 4.1 can be assumed to be an alias to version `5.0.0`
 
 
 ## 4.0.x
 
+Version 4.0 of the Facebook PHP SDK did not follow [SemVer](http://semver.org/). The versioning format used was as follows: `4.MAJOR.(MINOR|PATCH)`. The `MINOR` and `PATCH` versions were squashed together.
+
+- 4.0.23 (2015-04-03)
+  - Added support for new JSON response types in Graph v2.3 when requesting access tokens
+- 4.0.22 (2015-04-02)
+  - Fixed issues related to multidimensional params
+  - **Bumped default fallback Graph version to `v2.3`**
+- 4.0.21 (2015-03-31)
+  - Added a `FacebookPermissions` class to reference all the Facebook permissions
+- 4.0.20 (2015-03-02)
+  - Fixed a bug introduced in `4.0.19` related to CSRF comparisons
+- 4.0.19 (2015-03-02)
+  - Added stricter CSRF comparison checks to `SignedRequest` and `FacebookRedirectLoginHelper`
+- 4.0.18 (2015-02-24)
+  - [`FacebookHttpable`] Reverted a breaking change from `4.0.17` that changed the method signatures
+- 4.0.17 (2015-02-19)
+  - [`FacebookRedirectLoginHelper`] Added multiple auth types to `getLoginUrl()`
+  - [`GraphUser`] Added `getTimezone()`
+  - [`FacebookCurl`] Additional fix for `curl_init()` handling
+  - Added support for https://graph-video.facebook.com when path ends with `/videos`
+- 4.0.16 (2015-02-03)
+  - [`FacebookRedirectLoginHelper`] Added "reauthenticate" functionality to `getLoginUrl()`
+  - [`FacebookCurl`] Fixed `curl_init()` issue
+- 4.0.15 (2015-01-06)
+  - [`FacebookRedirectLoginHelper`] Added guard against accidental exposure of app secret via the logout link
+- 4.0.14 (2014-12-29)
+  - [`GraphUser`] Added `getGender()`
+  - [`FacebookRedirectLoginHelper`] Added CSRF protection for rerequest links
+  - [`GraphAlbum`] Fixed bugs in getter methods
+- 4.0.13 (2014-12-12)
+  - [`FacebookRedirectLoginHelper`] Added `$displayAsPopup` param to `getLoginUrl()`
+  - [`FacebookResponse`] Fixed minor pagination bug
+  - Removed massive cert bundle and replaced with `DigiCertHighAssuranceEVRootCA` for peer verification
 - 4.0.12 (2014-10-30)
-  - Added Graph v2.2 support
+  - **Updated default fallback Graph version to `v2.2`**
   - Fixed potential duplicate `type` param in URL's
   - [`FacebookRedirectLoginHelper`] Added `getReRequestUrl()`
   - [`GraphUser`] Added `getEmail()`

CONTRIBUTING.md

@@ -17,6 +17,8 @@ We accept contributions via Pull Requests on [Github](https://github.com/faceboo
 
 - **Document any change in behaviour** - Make sure the README and the [documentation](https://github.com/facebook/facebook-php-sdk-v4/tree/master/docs) are kept up-to-date.
 
+- **Consider our release cycle** - As of version 5.0.0, we try to follow [SemVer](http://semver.org/). Randomly breaking public APIs is not an option.
+
 - **Create topic branches** - Don't ask us to pull from your master branch.
 
 - **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://img.shields.io/travis/facebook/facebook-php-sdk-v4/master.svg)](https://travis-ci.org/facebook/facebook-php-sdk-v4)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/facebook/facebook-php-sdk-v4/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/facebook/facebook-php-sdk-v4/?branch=master)
-[![Development Version](https://img.shields.io/badge/Development%20Version-4.1.0-orange.svg)](https://packagist.org/packages/facebook/php-sdk-v4)
+[![Development Version](https://img.shields.io/badge/Development%20Version-5.0-orange.svg)](https://packagist.org/packages/facebook/php-sdk-v4)
 
 
 This repository contains the open source PHP SDK that allows you to access the Facebook Platform from your PHP app.
@@ -15,7 +15,7 @@ The Facebook PHP SDK can be installed with [Composer](https://getcomposer.org/).
 ```json
 {
     "require": {
-        "facebook/php-sdk-v4": "~4.1.0"
+        "facebook/php-sdk-v4": "~5.0@dev"
     }
 }
 ```
@@ -31,7 +31,7 @@ Simple GET example of a user's profile.
 $fb = new Facebook\Facebook([
   'app_id' => '{app-id}',
   'app_secret' => '{app-secret}',
-  'default_graph_version' => 'v2.2',
+  'default_graph_version' => 'v2.3',
   //'default_access_token' => '{access-token}', // optional
 ]);
 

docs/sdk_downloads.fbmd

@@ -1,5 +1,5 @@
 <card>
-# Downloads for the Facebook SDK 4.x for PHP
+# Downloads for the Facebook PHP SDK
 
 For full details on what changed between each version release, see the [CHANGELOG](https://github.com/facebook/facebook-php-sdk-v4/blob/master/CHANGELOG.md).
 

docs/sdk_getting_started.fbmd

@@ -7,7 +7,7 @@ Whether you're developing a website with Facebook login, creating a Facebook Can
 <card>
 ## Autoloading & namespaces {#psr-4}
 
-The Facebook PHP SDK v4.x is coded in compliance with [PSR-4](http://www.php-fig.org/psr/psr-4/). This means it relies heavily on namespaces so that class files can be loaded for you automatically.
+The Facebook PHP SDK v5 is coded in compliance with [PSR-4](http://www.php-fig.org/psr/psr-4/). This means it relies heavily on namespaces so that class files can be loaded for you automatically.
 
 It would be advantageous to familiarize yourself with the concepts of [namespacing](http://php.net/manual/en/language.namespaces.rationale.php) and [autoloading](http://php.net/manual/en/function.spl-autoload-register.php) if you are not already acquainted with them.
 </card>
@@ -34,14 +34,14 @@ There are two methods to install the Facebook PHP SDK. The recommended installat
 ~~~
 {
   "require" : {
-    "facebook/php-sdk-v4" : "~4.1.0"
+    "facebook/php-sdk-v4" : "~5.0"
   }
 }
 ~~~
 
 %FB(devsite:markdown-wiki:info-card {
-  content: "The Facebook SDK v4 does not follow [SemVer](http://semver.org/). The versioning format used for the SDK  is `4.MAJOR.(MINOR|PATCH)`. The `MINOR` and `PATCH` versions are squashed together but there shouldn't be any breaking changes between `MINOR|PATCH` releases. That's why it is important to use all three version numbers in composer when using the `~` operator, e.g. `~4.1.0`. This will ensure you don't inadvertently download a version with breaking changes in it.",
-  type: 'warning',
+  content: "The Facebook SDK starting adhering to [SemVer](http://semver.org/) with version 5. Previous to version 5, the SDK did not follow SemVer.",
+  type: 'info',
 })
 
 Then run `composer install` from the command line, and composer will download the latest version of the SDK and put it in the `/vendor/` directory.
@@ -59,8 +59,8 @@ require_once __DIR__ . '/vendor/autoload.php';
 First, download the source code and unzip it wherever you like in your project.
 
 %FB(devsite:markdown-wiki:button {
- text: 'Download the PHP SDK v4.1',
- href: 'https://github.com/facebook/facebook-php-sdk-v4/archive/4.1-dev.zip',
+ text: 'Download the PHP SDK v5.0',
+ href: 'https://github.com/facebook/facebook-php-sdk-v4/archive/5.0-dev.zip',
  size: 'large',
  use: 'special',
 })
@@ -85,21 +85,21 @@ The source code includes myriad files that aren't necessary for use in a product
 
 After downloading the source code with the button above, extract the files in a temporary directory.
 
-Move the folder `src/Facebook` to the root of your website installation or where ever you like to put 3rd-party code. For this example we'll rename the `Facebook` directory to `facebook-sdk-v4.1`.
+Move the folder `src/Facebook` to the root of your website installation or where ever you like to put 3rd-party code. For this example we'll rename the `Facebook` directory to `facebook-sdk-v5`.
 
-The path the the core SDK files should now be located in `/var/html/facebook-sdk-v4.1` and inside will also be the `autolaoder.php` file.
+The path the the core SDK files should now be located in `/var/html/facebook-sdk-v5` and inside will also be the `autolaoder.php` file.
 
 Assuming we have a script called `index.php` in the root of our web project, we need to include the autoloader at the top of our script.
 
 ~~~
-require_once __DIR__ . '/facebook-sdk-v4.1/autoload.php';
+require_once __DIR__ . '/facebook-sdk-v5/autoload.php';
 ~~~
 
 If the autoloader is having trouble detecting the path to the source files, we can define the location of the source code before the `require_once` statement.
 
 ~~~
-define('FACEBOOK_SDK_V4_SRC_DIR', __DIR__ . '/facebook-sdk-v4.1/');
-require_once __DIR__ . '/facebook-sdk-v4.1/autoload.php';
+define('FACEBOOK_SDK_V4_SRC_DIR', __DIR__ . '/facebook-sdk-v5/');
+require_once __DIR__ . '/facebook-sdk-v5/autoload.php';
 ~~~
 </card>
 

docs/sdk_landing_page.fbmd

@@ -1,5 +1,5 @@
 <card>
-# Facebook SDK v4.1 for PHP
+# Facebook SDK v5 for PHP
 
 The Facebook SDK for PHP is a library with powerful features that enable PHP developers to easily integrate Facebook login and make requests to the Graph API. It also plays well with the [Facebook SDK for JavaScript](/docs/reference/javascript/) to give the front-end user the best possible user experience. But it doesn't end there, the Facebook PHP SDK makes it easy to upload photos and videos and send batch requests to the Graph API among other things. And PHP SDK has many extensibility points giving PHP developers full control of how the PHP SDK interacts with their specific hosting environment and web framework.
 

docs/sdk_reference.fbmd

@@ -1,5 +1,5 @@
 <card>
-# Facebook SDK for PHP Reference (v4.1)
+# Facebook SDK for PHP Reference (v5)
 
 Below is the API reference for the Facebook PHP SDK.
 </card>

phpunit.xml.dist

@@ -7,7 +7,7 @@
         stopOnFailure="false"
         bootstrap="tests/bootstrap.php">
     <testsuites>
-        <testsuite name="Facebook PHP SDK v4 Test Suite">
+        <testsuite name="Facebook PHP SDK Test Suite">
             <directory>./tests</directory>
         </testsuite>
     </testsuites>

src/Facebook/Facebook.php

@@ -57,7 +57,7 @@ class Facebook
     /**
      * @const string Version number of the Facebook PHP SDK.
      */
-    const VERSION = '4.1.0-dev';
+    const VERSION = '5.0.0';
 
     /**
      * @const string Default Graph API version for requests.

src/Facebook/autoload.php

@@ -29,7 +29,7 @@
  */
 
 if (version_compare(PHP_VERSION, '5.4.0', '<')) {
-    throw new Exception('The Facebook SDK v4 requires PHP version 5.4 or higher.');
+    throw new Exception('The Facebook SDK requires PHP version 5.4 or higher.');
 }
 
 /**