Merge branch '4.0'

Conflicts:
	README.md
	composer.json

.editorconfig

@@ -0,0 +1,16 @@
+; This file is for unifying the coding style for different editors and IDEs.
+; More information at http://editorconfig.org
+
+root = false
+
+[*]
+indent_style = space
+indent_size = 4
+charset = "utf-8"
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.yml]
+indent_style = space
+indent_size = 2

.travis.yml

@@ -4,13 +4,16 @@ sudo: false
 
 php:
   - 5.4
+  - 5.5
+  - 5.6
+  - 7.0
 
 before_script:
   - composer require --dev cakephp/cakephp-codesniffer:dev-master
   - composer install --prefer-dist --dev
 
 script:
-  - ./vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP ./src ./config
+  - ./vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP --ignore=config/Migrations/* ./src ./config
 
 notifications:
-  email: false
+  email: false

README.md

@@ -10,21 +10,27 @@ social sign on library.
 Requirements
 ------------
 
-* CakePHP 3.0+ (Refer to the `cake2` branch README for CakePHP 2.x)
+* CakePHP 3.1+.
 
 Installation
 ------------
 
 Run:
 
 ```
-composer require admad/cakephp-hybridauth:~3.0
+composer require --prefer-dist admad/cakephp-hybridauth
 ```
 
 Setup
 -----
 
-Load the plugin by adding following to your app's boostrap:
+Load the plugin by running following command in terminal:
+
+```
+bin/cake plugin load ADmad/HybridAuth -b -r
+```
+
+or by manually adding following line to your app's `config/bootstrap.php`:
 
 ```php
 Plugin::load('ADmad/HybridAuth', ['bootstrap' => true, 'routes' => true]);
@@ -33,55 +39,66 @@ Plugin::load('ADmad/HybridAuth', ['bootstrap' => true, 'routes' => true]);
 Configuration
 -------------
 
-Make a config file `config/hybridauth.php`
-Eg.
+Make a config file `config/hybridauth.php`:
 
 ```php
 use Cake\Core\Configure;
 
-$config['HybridAuth'] = [
-    'providers' => [
-        'OpenID' => [
-            'enabled' => true
-        ]
-    ],
-    'debug_mode' => Configure::read('debug'),
-    'debug_file' => LOGS . 'hybridauth.log',
+return [
+    'HybridAuth' => [
+        'providers' => [
+            'Google' => [
+                'enabled' => true,
+                'keys' => [
+                    'id' => '<facebook-application-id>',
+                    'secret' => '<secret-key>'
+                ]
+            ],
+            'Facebook' => [
+                'enabled' => true,
+                'keys' => [
+                    'id' => '<google-client-id>',
+                    'secret' => '<secret-key>'
+                ],
+                'scope' => 'email, user_about_me, user_birthday, user_hometown'
+            ],
+            'Twitter' => [
+                'enabled' => true,
+                'keys' => [
+                    'key' => '<twitter-key>',
+                    'secret' => '<twitter-secret>'
+                ],
+                'includeEmail' => true // Only if your app is whitelisted by Twitter Support
+            ]
+        ],
+        'debug_mode' => Configure::read('debug'),
+        'debug_file' => LOGS . 'hybridauth.log',
+    ]
 ];
 ```
 
 For more information about the hybridauth configuration array check
 http://hybridauth.github.io/hybridauth/userguide/Configuration.html
 
-__Note:__ When specifying `loginRedirect` URL for AuthComponent be sure to add
-`'plugin' => false` (or appropiate plugin name) to the URL array.
-
 Database
 --------
 
-The plugin also expects that your users table used for authentication contains
-fields `provider` and `provider_uid`. The fields are configurable through the
-`HybridAuthAuthenticate` authenticator.
-
-```MySQL
-CREATE TABLE IF NOT EXISTS `users` (
-    `id` int(11) NOT NULL AUTO_INCREMENT,
-    `email` varchar(200) NOT NULL,
-    `password` varchar(200) NOT NULL,
-    `name` varchar(200) NOT NULL,
-    `provider` varchar(100) NOT NULL,
-    `provider_uid` varchar(255) NOT NULL,
-    `created` datetime DEFAULT NULL,
-    `modified` datetime DEFAULT NULL,
-    PRIMARY KEY (`id`)
-) ENGINE=InnoDB  DEFAULT CHARSET=utf8 ;
+The plugin expects that you have a users table with at least `email` field
+and a `social_profiles` table. You can run
+
+```
+bin/cake migrations migrate -p ADmad/HybridAuth
 ```
 
+to generate the `social_profiles` tabel using a migration file provided with
+the plugin.
+
 Usage
 -----
 
 Check the CakePHP manual on how to configure and use the `AuthComponent` with
-required authenticator. You would have something like this in your `AppController`'s `initialize` method.
+required authentication handler. You would have something like this in your
+`AppController`'s `initialize()` method.
 
 ```php
 $this->loadComponent('Auth', [
@@ -92,11 +109,14 @@ $this->loadComponent('Auth', [
 ]);
 ```
 
+__Note:__ When specifying `loginRedirect` URL for AuthComponent be sure to add
+`'plugin' => false` (or appropiate plugin name) to the URL array.
+
 Your controller's login action should be similar to this:
 
 ```php
 public function login() {
-    if ($this->request->is('post')) {
+    if ($this->request->is('post') || $this->request->query('provider')) {
         $user = $this->Auth->identify();
         if ($user) {
             $this->Auth->setUser($user);
@@ -110,23 +130,56 @@ public function login() {
 __Note:__ When your action calls $this->Auth->identify() the method may not return.
 The authenticator may need to redirect to the provider's site to complete the
 identification procedure. It's important not to implement any important business
-logic that depends upon the identify() method returning.
+logic that depends upon the `identify()` method returning.
+
+On your login page you can create links to initiate authentication using required
+providers. Specify the provider name using variable named `provider` in query string.
 
-An eg. element `Template/Element/login.ctp` showing how to setup the login page
-form is provided. Checkout the various
-[examples](http://hybridauth.github.io/hybridauth/userguide/Examples_and_Demos.html)
-in hybridauth documentation to see various ways to setup your login page.
+```php
+echo $this->Html->link(
+    'Login with Google',
+    ['controller' => 'Users', 'action' => 'login', '?' => ['provider' => 'Google']]
+);
+```
 
 Once a user is authenticated through the provider the authenticator gets the user
 profile from the identity provider and using that tries to find the corresponding
-user record in your app's users table. If no user is found and `registrationCallback`
-option is specified the specified method from the `User` model is called. You
-can use the callback to save user record to database.
+user record in your app's users table. If no user is found emits a `HybridAuth.newUser`
+event. You must setup a listener for this event which save new user record to
+your users table and return an entity for the new user. Here's how you can setup
+a method of your `UsersTable` as callback for the event.
+
+```php
+public function initialize(array $config)
+{
+    $this->hasMany('ADmad/HybridAuth.SocialProfiles');
 
-If no callback is specified the profile returned by identity provider itself is
-returned by the authenticator.
+    EventManager::instance()->on('HybridAuth.newUser', [$this, 'createUser']);
+}
+
+public function createUser(Event $event) {
+    // Entity representing record in social_profiles table
+    $profile = $event->data()['profile'];
+
+    $user = $this->newEntity(['email' => $profile->email]);
+    $user = $this->save($user);
+
+    if (!$user) {
+        throw new \RuntimeException('Unable to save new user');
+    }
+
+    return $user;
+}
+```
+
+Twitter & email addresses
+-------------------------
+If you are trying to achieve a 'Sign in using Twitter' functionality, and you require the users *email address*, you need to specifically get your application [white-listed by Twitter Support using this form](https://support.twitter.com/forms/platform) and selecting 'I need access to special permissions'. Then you can use the `'includeEmail' => true` configuration option.
 
 Copyright
 ---------
-
 Copyright 2016 ADmad
+
+License
+-------
+[See LICENSE](LICENSE.txt)

composer.json

@@ -1,22 +1,24 @@
 {
-  "name": "admad/cakephp-hybridauth",
-  "description": "A CakePHP plugin for using the HybridAuth social sign on library",
-  "type": "cakephp-plugin",
-  "keywords": [
-    "cakephp",
-    "hybridauth",
-    "social signon",
-    "multi provider"
-  ],
-  "homepage": "http://github.com/ADmad/CakePHP-HybridAuth",
-  "license": "MIT",
-  "require": {
-    "cakephp/cakephp": "~3.0",
-    "hybridauth/hybridauth": "2.6.*"
-  },
-  "autoload": {
-    "psr-4": {
-      "ADmad\\HybridAuth\\": "src"
+    "name": "admad/cakephp-hybridauth",
+    "description": "A CakePHP plugin for using the HybridAuth social sign on library",
+    "type": "cakephp-plugin",
+    "keywords": [
+        "cakephp",
+        "hybridauth",
+        "social",
+        "social signon",
+        "social authentication",
+        "multi provider"
+    ],
+    "homepage": "http://github.com/ADmad/CakePHP-HybridAuth",
+    "license": "MIT",
+    "require": {
+        "cakephp/cakephp": "~3.1",
+        "hybridauth/hybridauth": "~2.6"
+    },
+    "autoload": {
+        "psr-4": {
+            "ADmad\\HybridAuth\\": "src"
+        }
     }
-  }
 }