- Installation
- User Module Setup
- User Component Setup
- Database Connection Setup
- Create User Database
- Setup Mailer Component
- Setup Social Component
- Setup Profile
- Using the module
- Usage with Yii 2 Advanced Template
The preferred way to install this extension is through composer.
Either run
$ php composer.phar require communityii/yii2-user "@dev"
or add
"communityii/yii2-user": "@dev"
to the require section of your composer.json file.
Run $ php composer.phar update from your console to get the latest version of the module packages.
Setup the module in your configuration file as shown below. The module depends on and uses the yii2-grid module, so you must also setup the gridview module also as shown below. You can set this within common/config/main.php if using with Yii 2 advanced app or within config/web.php for Yii 2 basic app. There are various settings available for configuring your user module. Read through the documentation to understand and set these carefully for your application.
'modules' => [
'user' => [
'class' => 'comyii\user\Module',
'installAccessCode' => '<YOUR_ACCESS_CODE>',
// setup your module preferences
// refer all module settings in the docs
'registrationSettings' => [
'autoActivate' => false
],
'socialSettings' => [
'enabled' => true
],
'profileSettings' => [
'enabled' => true,
'baseUrl' => 'http://localhost/kvdemo/uploads'
]
],
'gridview' => [
'class' => 'kartik\grid\Module',
]
],
// your other modulesSetup the user component in your configuration file for the yii2-user module. You can set this within common/config/main.php if using with Yii 2 advanced app or within config/web.php for Yii 2 basic app.
'components' => [
// user authentication component
'user' => [
'class' => 'comyii\user\components\User',
// other component settings
],
// your other components
],Configure the database connection component db in your configuration file to reflect the right tablePrefix as needed for your environment.
'components' => [
// database connection component
'db' => [
'class' => 'yii\db\Connection',
// your table prefix
'tablePrefix' => 'tbl_',
// your connection settings
'dsn' => 'mysql:host=localhost;dbname=[DB_NAME]',
'username' => '[SCHEMA_USERNAME]',
'password' => '[SCHEMA_PASSWORD]',
'charset' => 'utf8',
],
// your other components
],Run the database migrations from your command console to setup the database schema for the module.
$ php yii migrate/up --migrationPath=@vendor/communityii/yii2-user/migrations
The module uses yii2-swiftmailer extension to generate emails to the users for various actions. You would need to configure the mailer component as shown below. For example, the configuration file would be common\config\main-local.php if you are using the Yii 2 advanced app. Note any viewPath set within this component will be ignored by the yii2-user module. Instead, the setting within comyii\user\Module::notificationSettings['viewPath'] will be considered for parsing the mailer templates within this module.
'components' => [
'mailer' => [
'class' => 'yii\swiftmailer\Mailer',
'viewPath' => '@common/mail',
// send all mails to a file by default. You have to set
// 'useFileTransport' to false and configure a transport
// for the mailer to send real emails.
'useFileTransport' => true,
/*
'transport' => [
'class' => 'Swift_SmtpTransport',
'host' => 'smtp.gmail.com',
'username' => '<[email protected]>',
'password' => '<your-password>',
'port' => '587',
'encryption' => 'tls',
],
*/
],
]Optional Setup.
If you wish to enable users to authenticate via social connections (e.g. Facebook, Twitter etc.) - then you need to setup the auth client component. The module uses the yii2-authclient extension for social authentication. You would need to configure the authClientCollection component in your Yii configuration file (append the following to the components section and configure your necessary clients).
'authClientCollection' => [
'class' => 'yii\authclient\Collection',
'clients' => [
'google' => [
'class' => 'yii\authclient\clients\GoogleOpenId'
],
'facebook' => [
'class' => 'yii\authclient\clients\Facebook',
'clientId' => 'facebook_client_id',
'clientSecret' => 'facebook_client_secret',
],
// etc.
],
]In addition, you must setup the Module::socialSettings property to control the social authentication configuration for this module. For example, you can modify and set the socialSettings to what you need within user module settings.
'modules' => [
'user' => [
'socialSettings' => [
// whether social authentication is enabled
'enabled' => true,
// whether social client choices will be displayed on login, register and profile
'widgetEnabled' => true,
// the widget class to use to render the social client choices
'widgetSocialClass' => 'comyii\user\widgets\SocialConnects',
// the widget settings
'widgetSocial' => []
],
],
],
// your other modulesOptional Setup.
The profile settings for the module can be enabled and configured via the Module::profileSettings['enabled'] property, which is true by default. In order to begin using the module for profile avatar upload, carry out the following steps.
Create a folder on your application where profile avatar images will be stored. Then configure your Module::profileSettings['basePath'] to point to this folder. This by default is set to @webroot/uploads, so you can directly create an uploads folder on your web root and proceed.
Identify a web accessible URL for the folder above and set Module::profileSettings['baseUrl'] to point to this. It is recommended to set the absolute URL here, so that the images are accessible across both frontend and backend apps (if using with Yii 2 advanced application template).
Setup a default avatar image file to be displayed when no user profile picture is found. Copy an image file avatar.png or any filename you wish to the above uploads path. Configure Module::profileSettings['defaultAvatar'] to this filename. For example, all the steps above would look like this in the configuration file.
// module settings in Yii config file
// @common/config/main.php
'modules' => [
'user' => [
'profileSettings' => [
'enabled' => true
'basePath' => '@webroot/uploads',
'baseUrl' => 'http://localhost/app/uploads', // absolute URL
'defaultAvatar' => 'avatar.png', // a file in above location
]
]
]Login to the url pertaining to the user module path (e.g. http://localhost/app/user) and you should be automatically guided with an installation wizard. The steps to create a superuser are self-explanatory. Finish the superuser setup to proceed using the module. If you have prettyUrl enabled in your urlManager, the Module will automatically set some user friendly URL to access, which you can modify via Module::urlRules and Module::urlPrefix.
The following default links will be available for use if your app root is available at http://localhost/app. You may wish to alter your application menus to point to these.
| Link | URL |
|---|---|
| User Login | http://localhost/app/user/login |
| User Logout | http://localhost/app/user/logout |
| User Register | http://localhost/app/user/register |
| User Password Change | http://localhost/app/user/password |
| User Password Recovery | http://localhost/app/user/recovery |
| User Password Reset | http://localhost/app/user/reset/KEY |
| User Activate | http://localhost/app/user/activate/KEY |
| User Email Change | http://localhost/app/user/newemail/KEY |
| User Social Auth | http://localhost/app/user/auth/CLIENT |
| User Profile | http://localhost/app/user/profile |
| User Profile Update | http://localhost/app/user/profile/update |
| User Profile Admin Mode | http://localhost/app/user/profile/ID |
| Admin Users List | http://localhost/app/user/admin |
| Admin User View | http://localhost/app/user/ID |
| Admin User Create | http://localhost/app/user/create |
| Admin User Update | http://localhost/app/user/update/ID |
You can configure the module to work easily with the Yii 2 Advanced Application Template and have different sessions for frontend and backend of the Yii 2 advanced app. For this you may carry out the following steps:
Create the following folders in your Yii 2 advanced app.
frontend/runtime/sessionsbackend/runtime/sessions
Add the following configuration for cookies and sessions to your frontend app within frontend/config/main-local.php.
'components' => [
'request' => [
// !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
'cookieValidationKey' => 'UNIQUE_KEY_FRONTEND',
],
// unique identity cookie configuration for frontend
'user' => [
'identityCookie' => [
'name' => '_frontendUser', // unique for frontend
'path' => '/' // set it to correct path for frontend app.
]
],
// unique session configuration for frontend
'session' => [
'name' => '_frontendSessionId', // unique for frontend
'savePath' => __DIR__ . '/../runtime/sessions' // set it to correct path for frontend app.
]
],Add the following configuration for cookies and sessions to your backend app within backend/config/main-local.php. Note you can optionally configure a different URL manager in backend to get access to frontend URL routes (for example urlManagerFE as shown below).
'components' => [
'request' => [
// !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
'cookieValidationKey' => 'UNIQUE_KEY_BACKEND',
// unique CSRF cookie parameter for backend
'csrfParam' => '_backendCsrf',
],
// unique identity cookie parameter for backend
'user' => [
'identityCookie' => [
'name' => '_backendCookie', // unique for backend
'path' => '/backend', // set it to correct path for backend app
]
],
// unique identity session parameter for backend
'session' => [
'name' => '_backendSessionId',
'savePath' => __DIR__ . '/../runtime/sessions',
],
// url manager to access frontend
'urlManagerFE' => [
'class' => 'yii\web\urlManager',
'baseUrl' => '/advanced',
'enablePrettyUrl' => true,
'showScriptName' => false,
]
]