Tutorial for installing and configuring the Yii User Management 
Module. 

In this Tutorial we will learn how to use the User
Management Module on a fresh created Yii Web Application. Installation
under an existing application is identical to these instructions.

1.) Generate your Webapp:

$ php yii-1.1.10/framework/yiic webapp testdrive
Create a Web application under '/var/www/testdrive'? [Yes|No] Yes

[...]

Your application has been created successfully under /var/www/testdrive.

2.) The Yii User Management Module needs a Database Connection to work. You 
now have to setup your MySQL Database and insert the connection
URI in your Application configuration, like this:

'db'=>array(
		'connectionString' => 'mysql:host=localhost;dbname=testdrive',
		'emulatePrepare' => true,
		'username' => 'root',
		'password' => '',
		'charset' => 'utf8',
		// prior to yum0.8rc7 tablePrefix is not necessary anymore, but it can not hurt
		'tablePrefix' => '', 	   
		),

$ mysql -u root localhost    
> CREATE DATABASE `testdrive` ;

3.) Extract the Yii User Management Module under the modules/ directory
of your new Web Application. Replace the _0.8 with the latest Version
available.

$ cd testdrive/protected
$ mkdir modules
$ cd modules
$ wget http://www.yiiframework.com/extension/yii-user-management/files/User_Management_Module_0.8.tar.bz2
$ tar xvf User_Management_Module_0.8.tar.bz2

4.) The Yii-user-management module contains submodules that you just extracted
into your application's modules/ directory. The installation script will provide

$ [youreditor] protected/config/main.php

Add these lines:

'modules' => array(
		'user' => array(
			'debug' => true,
			)
		),

The debug option is needed for the installation and should be set to false 
after the installation. 

5.) To let your Web Application use the Authentification Methods of
the User Management Module, we need to overwrite the default 
Authentification Method in the Application Configuration:

 'components'=>array(
 'user'=>array(
      'class' => 'application.modules.user.components.YumWebUser',
      'allowAutoLogin'=>true,
      'loginUrl' => array('//user/user/login'),
      [...]
    ),

 'import'=>array(  
  'application.modules.user.models.*',
	[...]
    
This tells our Web Application that is can access the Model 'User'
even when not in the modules/user environment. This is needed for calling
User::hasRole($role) in your Code to check if the logged in User belongs to the
role. This is explained in the detailed Documentation. It is good to let this 
line occur as the first included Model, so you can extend the User-Model with 
your own in your Application models/ Directory if you like.

6.) Run the User Management Installer in your Web-Browser:

http://localhost/testdrive/index.php/user/install
or
http://localhost/testdrive/index.php?r=user/install

depending on your URL route setup. 

7.) Now the Installer of the User Management Module should appear.
To the right you can set up alternate Table Names used by the
Module. In most cases this is not needed and you can keep this 
Settings. If you do change this, be sure to set up the correct table
Names in your Application Configuration, so the User Module can access
them.

Click 'Install Module'. After clicking it, the install script will
create the database tables needed by the module(s). Then it will show
you the neccesary modifications to be made. Add the Modules you need to your 
Application Configuration as provided by the install script in config/main.php.
You can also remove the Yum modules you don't want to use.


8.) Make sure to set a caching component. Yum relies on it. If you do not
want to cache, add

	'components' => array(
			'cache' => array('class' => 'system.caching.CDummyCache'),

to your config/main.php.

Also see http://www.yiiframework.com/doc/guide/1.1/en/caching.overview about
some general information about caching in yii.

9.) Congratulations, you have installed the User Management Module! Lets
tidy up a little bit:

10.) Login as admin/admin and navigate to index.php?r=user/user/admin.
This is your user management administration panel. Click on "Administrate your Users"
Now you are taken to the default Front-End Login-Screen of the User 
Management Module. Log in with the Username admin and Password admin.

11.) Click on the 'update Icon' (the pencil) of your administrator User.
Change the Password to something more safe than 'admin'. Click Save.

12.) If you already didn't do it, remove the 'debug' => 'true' line from youri
Application Configuration so your new data doesn't get overwritten accidentally
by the installation process.

Configuration of your freshly installed User Management Module:
---------------------------------------------------------------

Language:
---------
The Yii-User Management Module uses the language that is set in
the Application Configuration. For example, you can add a 

'language' => 'de',

in your config/main.php to get German Language strings. At the moment
English, German, French and Polish are supported. 


Quick Login Widget:
-------------------
If you want to display a quick login widget somewhere in your Web Application,
just call in your view file:

<? $this->widget('application.modules.user.components.LoginWidget'); ?>


Password Requirements:
----------------------
You can setup the password Requirements within the 'passwordRequirements' 
option of the Module, for example:

 'user' => array(
        'passwordRequirements' => array(                                        
          'minLen' => 4,
          'maxLen' => 16,
          'maxRepetition' => 2,
          'minDigits' => 3,
          ),

Please see components/CPasswordValidator.php for possible password 
requirement options


User Registration:
------------------
Set the Variable 'enableActivationConfirmation' to false in the module configuration to 
let users register for your application without needing to receive/click an emailed confirmation link.


Role Management:
----------------
You can add up new roles in the Role Manager. To check for access
to this roles, you can use this code Snippet everywhere in your
Yii Application. Most likely it will be used in the ACL Filter of
your Controllers:


if(Yii::app()->user->can('action'))
{
 // user is allowed
}
else
{
 // user is not allowed to do this
}


Please see the file docs/logging.txt for information on how to set up
the logging functions of the Yii User Management module.


Where to go from now on?
------------------------
There are some examples on how to extend from the Yii User Management
Module and how to implement project-specific stuff. See the files in 
the docs/ directory for all this.


FAQ:
----
Q: I get an exception when running the Installer

A: Please make sure to log out from any session. Clear your cookies to make
sure you are not logged in in your Web Application anymore.

Q: I get the error Message: CWebUser does not have a method named "isAdmin":

A: Please make sure that you have the following in your application configuration:

	'components'=>array(
		'user'=>array(
			'class' => 'application.modules.user.components.YumWebUser',


Q: I get the error Message: the table "{{users}}" for active record class "YumUser" cannot be found in the database.

A: Please make sure that you have the following in your application configuration:

		'db'=>array(
			'tablePrefix' => '',
			[...]


Q: Why doesn´ t the yii-user-management have submodules?

A: Submodules are supported by yii, but having a path like 
application.modules.user.modules.role.controllers.YumRoleController
really looks strange, so we decided it is better to keep all modules inside
the root modules/ directory.

Q: I get the following error while installing:
General error: 2014 Cannot execute queries while other unbuffered queries are active

A: thanks to NetDabbler, there is a workaround:

Comment the folowing lines in YumInstallController.php
// $sql = file_get_contents(Yii::getPathOfAlias('application.modules.user.docs') . '/yum_translation.sql');
// $db->createCommand($sql)->execute();

Insert the translation data manually in a cmd window as:
mysql -u yourusername -p testyum < docs/yum_translation.sql


Q: I still got errors ! 

A: Make sure to enable a caching component, at least CDummyCache, in your config/main.php:

'cache'=>array( 'class'=>'system.caching.CDummyCache',	),  

Q: I still got errors !

A: Try to add this in your config/main.php:

'session' => array(
		'sessionName' => 'SiteSession',
		'class' => 'CHttpSession',
		'autoStart' => true,
		),

