CakeDC Users migration to CakePHP 3.x, featuring

* Social login
* User management
* Roles and SimpleRbac rules

Initial migration version by Alejandro Ibarra, Yelitza Parra and Jorge González. Peer code review by Chris Burke and Jad Bitar.

Big thanks to:

* CakeDC, of course, http://cakedc.com
* https://github.com/uzyn/cakephp-opauth Plugin ideas used for our Opauth integration

CONTRIBUTING.md

@@ -1,4 +1,4 @@
 Contributing
 ============
 
-This repository follows the [CakeDC Plugin Standard](http://cakedc.com/plugins). If you'd like to contribute new features, enhancements or bug fixes to the plugin, please read our [Contribution Guidelines](http://cakedc.com/plugins) for detailed instructions.
+This repository follows the [CakeDC Plugin Standard](http://cakedc.com/plugin-standard). If you'd like to contribute new features, enhancements or bug fixes to the plugin, please read our [Contribution Guidelines](http://cakedc.com/contribution-guidelines) for detailed instructions.

Docs/Documentation/Configuration.md

@@ -0,0 +1,149 @@
+Configuration
+=============
+
+Overriding the default configuration
+-------------------------
+
+For easier configuration, you can specify an array of config files to override the default plugin keys this way:
+
+config/bootstrap.php
+```
+Configure::write('Users.config', ['users']);
+Plugin::load('Users', ['routes' => true, 'bootstrap' => true]);
+```
+
+Then in your config/users.php
+```
+return [
+    'Opauth.Strategy.Facebook.app_id' => 'YOUR APP ID',
+    'Opauth.Strategy.Facebook.app_secret' => 'YOUR APP SECRET',
+    //etc
+];
+```
+
+Configuration for social login
+---------------------
+
+Create the facebook/twitter applications you want to use and setup the configuration like this:
+
+config/bootstrap.php
+```
+Configure::write('Opauth.Strategy.Facebook.app_id', 'YOUR APP ID');
+Configure::write('Opauth.Strategy.Facebook.app_secret', 'YOUR APP SECRET');
+
+Configure::write('Opauth.Strategy.Twitter.key', 'YOUR APP KEY');
+Configure::write('Opauth.Strategy.Twitter.secret', 'YOUR APP SECRET');
+```
+
+Or use the config override option when loading the plugin (see above)
+
+Configuration options
+---------------------
+
+The plugin is configured via the Configure class. Check the `vendor/cakedc/users/config/users.php`
+for a complete list of all the configuration keys.
+
+Loading the UsersAuthComponent and using the right configuration values will setup the Users plugin, 
+the AuthComponent and the Opauth component for your application.
+
+If you prefer to setup AuthComponent by yourself, you'll need to load AuthComponent before UsersAuthComponent
+and set 
+```
+Configure::write('Users.auth', false);
+```
+
+
+
+
+Interesting UsersAuthComponent options and defaults
+
+NOTE: SOME keys were hidden in this doc page, please refer to `vendor/cakedc/users/config/users.php` for the complete list
+
+```
+    'Users' => [
+        //Table used to manage users
+        'table' => 'Users.Users',
+        //configure Auth component
+        'auth' => true,
+        'Email' => [
+            //determines if the user should include email
+            'required' => true,
+            //determines if registration workflow includes email validation
+            'validate' => true,
+        ],
+        'Registration' => [
+            //determines if the register is enabled
+            'active' => true,
+        ],
+        'Tos' => [
+            //determines if the user should include tos accepted
+            'required' => true,
+        ],
+        'Social' => [
+            //enable social login
+            'login' => true,
+        ],
+        //Avatar placeholder
+        'Avatar' => ['placeholder' => 'Users.avatar_placeholder.png'],
+        'RememberMe' => [
+            //configure Remember Me component
+            'active' => true,
+        ],
+    ],
+//default configuration used to auto-load the Auth Component, override to change the way Auth works
+    'Auth' => [
+        'authenticate' => [
+            'all' => [
+                'scope' => ['active' => 1]
+            ],
+            'Users.RememberMe',
+            'Form',
+        ],
+        'authorize' => [
+            'Users.Superuser',
+            'Users.SimpleRbac',
+        ],
+    ],
+];
+
+```
+
+Default Authenticate and Authorize Objects used
+------------------------
+
+Using the UsersAuthComponent default initialization, the component will load the following objects into AuthComponent:
+* Authenticate
+  * 'Form'
+  * 'Social' check [SocialAuthenticate](SocialAuthenticate.md) for configuration options
+  * 'RememberMe' check [SocialAuthenticate](RememberMeAuthenticate.md) for configuration options
+* Authorize
+  * 'Users.Superuser' check [SuperuserAuthorize](SuperuserAuthorize.md) for configuration options
+  * 'Users.SimpleRbac' check [SimpleRbacAuthorize](SimpleRbacAuthorize.md) for configuration options
+
+Email Templates
+---------------
+
+To modify the templates as needed copy them to your application
+
+```
+cp -r vendor/cakedc/users/src/Template/Email/* src/Template/Plugin/Users/Email/
+```
+
+Then customize the email templates as you need under the src/Template/Plugin/Users/Email/ directory
+
+Plugin Templates
+---------------
+
+Similar to Email Templates customization, follow the CakePHP conventions to put your new templates under
+src/Template/Plugin/Users/[Controller]/[view].ctp
+
+Check http://book.cakephp.org/3.0/en/plugins.html#overriding-plugin-templates-from-inside-your-application
+
+Flash Messages
+---------------
+
+To modify the flash messages, use the standard PO file provided by the plugin and customize the messages
+Check http://book.cakephp.org/3.0/en/core-libraries/internationalization-and-localization.html#setting-up-translations 
+for more details about how the PO files should be managed in your application.
+
+We've included an updated POT file with all the `Users` domain keys for your customization.

Docs/Documentation/Events.md

@@ -0,0 +1,53 @@
+Events
+======
+
+The events in this plugin follow these conventions <Plugin>.<MVC>.<Name>.<EventName>:
+
+* 'Users.Component.UsersAuth.isAuthorized';
+* 'Users.Component.UsersAuth.beforeLogin';
+* 'Users.Component.UsersAuth.afterLogin';
+* 'Users.Component.UsersAuth.afterCookieLogin'
+* 'Users.Component.UsersAuth.beforeRegister';
+* 'Users.Component.UsersAuth.afterRegister';
+
+The events allow you to inject data into the plugin on the before* plugins and use the data for your 
+own business login in the after* events, for example
+
+```
+    /**
+     * Forced login using a beforeLogin event
+     */
+    public function eventLogin()
+    {
+        $this->eventManager()->on(UsersAuthComponent::EVENT_BEFORE_LOGIN, function () {
+            //the callback function should return the user data array to force login
+            return [
+                'id' => 1337,
+                'username' => 'forceLogin',
+                'email' => 'event@example.com',
+                'active' => true,
+            ];
+        });
+        $this->login();
+        $this->render('login');
+    }
+
+    /**
+     * beforeRegister event
+     */
+    public function eventRegister()
+    {
+        $this->eventManager()->on(UsersAuthComponent::EVENT_BEFORE_REGISTER, function ($event) {
+            //the callback function should return the user data array to force register
+            return $event->data['usersTable']->newEntity([
+                'username' => 'forceEventRegister',
+                'email' => 'eventregister@example.com',
+                'password' => 'password',
+                'active' => true,
+                'tos' => true,
+            ]);
+        });
+        $this->register();
+        $this->render('register');
+    }
+```

Docs/Documentation/Extending-the-Plugin.md

@@ -0,0 +1,147 @@
+Extending the Plugin
+====================
+
+Extending the Model (Table/Entity)
+-------------------
+
+Create a new Table and Entity in your app, matching the table you want to use for storing the 
+users data. Check the initial users migration to know the default columns expected in the table.
+If your column names doesn't match the columns in your current table, you could use the Entity to 
+match the colums using accessors & mutators as described here http://book.cakephp.org/3.0/en/orm/entities.html#accessors-mutators
+
+Example: we are going to use a custom table in our application ```my_users```
+* Create a new Table under src/Model/Table/MyUsersTable.php
+
+```php
+namespace App\Model\Table;
+
+use Users\Model\Table\UsersTable;
+
+/**
+ * Users Model
+ */
+class MyUsersTable extends UsersTable
+{
+}
+
+* Create a new Entity under src/Model/Entity/MyUser.php
+
+```php
+namespace App\Model\Entity;
+
+use Users\Model\Entity\User;
+
+class MyUser extends User
+{
+}
+```
+
+* Pass the new table configuration to Users Plugin Configuration
+
+config/bootstrap.php
+```
+Configure::write('Users.config', ['users']);
+Plugin::load('Users', ['routes' => true, 'bootstrap' => true]);
+```
+
+Then in your config/users.php
+```
+return [
+    'Users.table' => 'MyUsers',
+];
+```
+
+Now the Users Plugin will use MyUsers Table and Entity to register and login user in. Use the
+Entity to match your own columns in case they don't match the default column names:
+
+```sql
+CREATE TABLE IF NOT EXISTS `users` (
+  `id` char(36) NOT NULL,
+  `username` varchar(255) NOT NULL,
+  `email` varchar(255) DEFAULT NULL,
+  `password` varchar(255) NOT NULL,
+  `first_name` varchar(50) DEFAULT NULL,
+  `last_name` varchar(50) DEFAULT NULL,
+  `token` varchar(255) DEFAULT NULL,
+  `token_expires` datetime DEFAULT NULL,
+  `api_token` varchar(255) DEFAULT NULL,
+  `activation_date` datetime DEFAULT NULL,
+  `tos_date` datetime DEFAULT NULL,
+  `active` int(1) NOT NULL DEFAULT '0',
+  `is_superuser` int(1) NOT NULL DEFAULT '0',
+  `role` varchar(255) DEFAULT 'user',
+  `created` datetime NOT NULL,
+  `modified` datetime NOT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+```
+
+Extending the Controller
+-------------------
+
+You want to use one of your controllers to handle all the users features in your app, and keep the
+login/register/etc actions from Users Plugin,
+
+```php
+<?php
+namespace App\Controller;
+
+use App\Controller\AppController;
+use App\Model\Table\MyUsersTable;
+use Cake\Event\Event;
+use Users\Controller\Component\UsersAuthComponent;
+use Users\Controller\Traits\LoginTrait;
+use Users\Controller\Traits\RegisterTrait;
+
+class MyUsersController extends AppController
+{
+    use LoginTrait;
+    use RegisterTrait;
+
+//add your new actions, override, etc here
+}
+```
+
+Note you'll need to **copy the Plugin templates** you need into your project src/Template/MyUsers/[action].ctp
+
+Extending the Features in your controller
+-----------------------------
+
+You could use a new Trait. For example, you want to add an 'impersonate' feature
+
+```php
+<?php
+namespace App\Controller\Traits;
+
+use Cake\Datasource\Exception\RecordNotFoundException;
+use Cake\Network\Exception\NotFoundException;
+
+/**
+ * Impersonate Trait
+ */
+trait ImpersonateTrait
+{
+    /**
+     * Adding a new feature as an example: Impersonate another user
+     *
+     * @param type $userId
+     */
+    public function impersonate($userId)
+    {
+        $user = $this->getUsersTable()->find()
+                ->where(['id' => $userId])
+                ->hydrate(false)
+                ->first();
+        $this->Auth->setUser($user);
+        return $this->redirect('/');
+    }
+}
+
+Updating the Templates
+-------------------
+
+Use the standard CakePHP conventions to override Plugin views using your application views
+http://book.cakephp.org/3.0/en/plugins.html#overriding-plugin-templates-from-inside-your-application
+
+
+