'behaviors' => array(
    'onBeginRequest' => array(
        'class' => 'application.components.RequireLogin'
    )
),

By placing this within the primary array, it applies to the application as a whole, as opposed to a specific component or module. This code associates one class with the onBeginRequest behavior. This is to say that every time a request is made, an instance of the RequireLogin class should be created.

Next, create a file called RequireLogin.php and store it in the protected/components directory. That file needs to define the RequireLogin class, which should be an extension of the Yii CBehavior class, which defines how application behaviors are used:

<?php
class RequireLogin extends CBehavior
{
}
?>

Within that class, only two methods need to be defined. The first is attach(), which will associate an event handler with the application:

public function attach($owner)
{
    $owner->attachEventHandler('onBeginRequest', array($this, 'handleBeginRequest'));
}

This method will receive the application as an argument (this code was found in the Yii forums, too). The attachEventHandler() function attaches to the application an event handler, saying that when the onBeginRequest event occurs, this class’s handleBeginRequest() method should be called.

The handleBeginRequest() method is defined like so:

public function handleBeginRequest($event)
{
    if (Yii::app()->user->isGuest && !in_array($_GET['r'],array('site/login'))) {
        Yii::app()->user->loginRequired();
    }
}

The method takes one argument, which will be the event (not actually used in the method). The purpose of the method is to determine the conditions in which a login must be required of the user. That enforcement is made by calling Yii::app()->user->loginRequired(). For this bare-bones example, the condition checks if the user is a guest, which is to say they aren’t logged in, and that $_GET['r'] does not have a value of site/login. The net effect is that guests can only ever access the login page. If you wanted to allow access to other pages, just add those values to the array:

if (Yii::app()->user->isGuest && !in_array($_GET['r'],array('site/login', 'site/index', 'site/contact'))) {

So that’s one way of implementing a broad login requirement without individually adjusting each Controller. To be clear, you’ll probably need to do that some as well, like to allow for access to specific actions based upon the type of logged-in user. Still, this is a simple and quite effective catchall. The person that shared the original code in my blog had put all this together within the configuration file. It is possible to do that (by creating an executed function) but the syntax is tricky and the code can really muddle up your configuration file. I think it’s best to separate it out, plus you now have a new class (RequireLogin) that you can use in other Yii-based sites.

• Authentication is performed against a database table
• The user’s email address is used instead of their username
• The user’s ID is stored for later reference
• The user’s “role” is stored for later reference

To start, let’s assume there is a database table called User that’s already been modeled and populated. The table has several columns, including at least: id, email, password, and role. The password column stores a SHA1()-encrypted version of the user’s password. The role dictates what the user can do in the site. Possible values are reader, editor, and writer (these are hypothetical values; they could be anything).

Now, by default, Yii will use cookies for authentication. In most situations that’s fine, but if anything of a sensitive nature is being stored, you should use sessions instead. This would apply to both the user’s ID value and their role. If either is available through a cookie, it wouldn’t be hard for the user to edit that cookie’s value in order to become someone else. So, to start, let’s disable the potential for using cookies. To do that, open up the protected/config/main.php configuration file and find this section from under components:

'user'=>array(
    // enable cookie-based authentication
    'allowAutoLogin'=>true,
),

To disable cookie-based authentication, either remove that code entirely, or change allowAutoLogin to false.

Next, let’s turn to the login form, which will require a couple of alterations. Open up protected/views/site/login.php, which is the form. The default form looks like this:

First, we need to remove the hint paragraph, as demo/demo and admin/admin will no longer work. Then we remove the code that displays the “remember me” checkbox. Remember me functionality is only good for cookies, so it’s useless here. Finally, we want to take an email address, not a username, so those two lines must be changed. The complete form file is now:

<?php $this->pageTitle=Yii::app()->name . ' - Login'; ?>

<h1>Login</h1>

<div>
<?php echo CHtml::beginForm(); ?>

<?php echo CHtml::errorSummary($form); ?>

<div>
<?php echo CHtml::activeLabel($form,'email'); ?>
<?php echo CHtml::activeTextField($form,'email') ?>
</div>

<div>
<?php echo CHtml::activeLabel($form,'password'); ?>
<?php echo CHtml::activePasswordField($form,'password') ?>
</div>

<div>
<?php echo CHtml::submitButton('Login'); ?>
</div>

<?php echo CHtml::endForm(); ?>

</div><!-- yiiForm -->

Next, we turn to the LoginForm Model, defined in protected/models/LoginForm.php. This Model is associated with the login form, handling and validating that submitted data. At the top of the Model, the class variables are defined. We need to change $username to $email and remove $rememberMe:

class LoginForm extends CFormModel
{
    public $email;
    public $password;

Next, alter the rules accordingly. Instead of username and password being required, email and password are required. Also, the email value should be in a valid email address format. The application of the authenticate() method to validate the password remains. Here are the updated rules:

public function rules()
{
    return array(
        array('email, password', 'required'),
        array('email', 'email'),
        array('password', 'authenticate'),
    );
}

Next, if you want, change the attributeLabels() method for the email address and remove the label for rememberMe:

public function attributeLabels()
{
    return array('email'=>'Email Address');
}

The final changes to the LoginForm Model are in the authenticate() method. Several references to username must be changed to email. For example, this:

$identity=new UserIdentity($this->username,$this->password);

becomes:

$identity=new UserIdentity($this->email,$this->password);

Then there’s a call to UserIdentity::authenticate(), which is where the actual authentication against the database takes place (see my previous post and I’ll also return to this shortly). After that, there’s an important switch conditional that responds to three possibilities: authenticated, invalid username, and invalid password. The applicable case is signaled by a UserIdentity constant. Do note that the UserIdentity class is an extension of CUserIdentity, so it uses ERROR_USERNAME_INVALID instead of ERROR_EMAIL_INVALID. In the following code I treat username and email address as synonymous, because it’s the easiest solution. A full alteration would require changing the Yii framework’s definition of CBaseUserIdentity (which CUserIdentity extends), which is not a good idea. So here’s the modified switch:

switch($identity->errorCode)
{
    case UserIdentity::ERROR_NONE:
        Yii::app()->user->login($identity);
        break;
    case UserIdentity::ERROR_USERNAME_INVALID:
        $this->addError('email','Email address is incorrect.');
        break;
    default: // UserIdentity::ERROR_PASSWORD_INVALID
        $this->addError('password','Password is incorrect.');
        break;
}

In the first case, with no error present, the user is logged in. I’ve removed references to rememberMe and duration, both of which are present in the Yii-generated code. The second case applies if the email address was not found in the database. Again, the error code is ERROR_USERNAME_INVALID, but it applies just the same. We do want to change the error so that it applies to the email element and has the proper error message. The final case applies if the email address was found but the supplied password was incorrect. Here’s an image for how the login form looks and behaves after these modifications:

Finally, we turn to protected/components/UserIdentity.php, for the final changes. There are a couple of things we need to do in this file. First, we need to perform the authentication against the User Model (and therefore, the database). Second, we need to store the user’s ID and role in the session for later use in the site. For the authentication, we’ll modify the authenticate() method:

public function authenticate()
{
    $user = User::model()->findByAttributes(array('email'=>$this->username));

Now the $user object represents the User record with an email field equal to the submitted email address. You may be wondering why I refer to $this->username here. That’s because the CUserIdentity class’s constructor takes the provided email address and password (from LoginForm) and stores them in $this->username and $this->password. So I need to equate username with email here, which is better than editing the framework itself. You ought to leave a comment about this so that you won’t be confused later when looking at the code.

Next the authenticate() method checks a series of possiblities and assigns constant values to the errorCode variable:

if ($user===null) { // No user found!
    $this->errorCode=self::ERROR_USERNAME_INVALID;
} else if ($user->password !== SHA1($this->password) ) { // Invalid password!
    $this->errorCode=self::ERROR_PASSWORD_INVALID;

In the first conditional, if $user has no value, then no records were found, so the email address was incorrect. In the second conditional, the stored password is compared against the SHA1() version of the submitted password. This assumes the record’s password was stored in a SHA1()-encrypted format. If neither of these conditionals are true, then everything is okay:

} else { // Okay!
    $this->errorCode=self::ERROR_NONE;
    // Store the role in a session:
    $this->setState('role', $user->role);
}

As you can see, a constant representing no error is assigned to the error code. After that, the user’s role value, from the database table, is stored in the session. This is accomplished by invoking the setState() method. Provide it with a name, role, and a value. After you’ve done this, the user’s role will be available through Yii::app()->user->role. You could do the same thing to store the user’s ID in the session, but the built-in authentication already has a getId() method that returns the user’s identifier. By default, the method returns the username value, so you’ll need to override the default behavior to return the ID instead. Start by creating a private variable in UserIdentity:

class UserIdentity extends CUserIdentity
{
    // Need to store the user's ID:
    private $_id;

Then, in the else clause (for successful authentication), assign the user’s ID to the class ID variable:

$this->_id = $user->id;

Finally, after the authenticate() method, override the getId() method by redefining it as:

public function getId()
{
    return $this->_id;
}

Now the user’s ID will be available through Yii::app()->user->id.

And that should be it. You now have an authentication process based upon an email address and password combination, using a database table, that also stores two pieces of information in the session. As always, thanks for reading and let me know if you have any questions or comments. Thanks, Larry!

Edit: Per a request, here’s the database schema, the LoginForm.php Model file, and the components/UserIdentity.php script that I *think* I used for this post:

CREATE TABLE `User` (
 `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
 `email` varchar(80) NOT NULL,
 `pass` char(40) NOT NULL,
 `role` enum('reader','editor','writer') NOT NULL,
 PRIMARY KEY (`id`)
);

LoginForm.php

UserIdentity.php

Most sites use some form of authentication. Maybe users have to login to post questions, to read content, or to administer the site. Whatever the case, a verification of the person is required before they can do whatever. As this is standard behavior, the default application created by the Yii framework has built-in authentication. When you generate a new site using Yii’s command-line tools, three files for managing authentication are created:

• protected/components/UserIdentity.php
• protected/models/LoginForm.php
• protected/views/site/login.php

And there’s also some code added to protected/controllers/SiteController.php that comes into play. The Controller file, gets the action going, of course. The View file is the login form itself. The LoginForm Model file defines the rules and behavior and the UserIdentity file defines a Model that performs the actual authentication.

By default, if you do nothing at all, users will be allowed to log into the site using the username/password combinations of demo/demo or admin/admin. These values are set in the UserIdentity.php script. If all you need to do is allow only a single authenticated user, then you can open UserIdentity.php and change this code:

$users=array(
    // username => password
    'demo'=>'demo',
    'admin'=>'admin',
);

to

$users=array(
    'whateverName'=>'whateverPassword'
);

At that point, you’re done. However, you most likely will perform authentication against a database table, so let’s see how you’d edit these files to make that happen. To start, let’s assume that the table name is Users, that you’ve already generated a Model for it, and that authentication requires an username and a password. As you’ll see, you’ll still only need to edit the UserIdentity.php file to make this possible, but in my next post I’ll walk through more elaborate customizations. Okay, with that in mind, let’s examine the authentication process…

The URL to login will likely be www.example.com/index.php/site/login, as Yii puts login/logout functionality in the Site Controller by default. So when the user clicks on a link to go to the login page, they’ll go through the Site Controller and call the actionLogin() method. That method is defined as:

public function actionLogin()
{
    $form=new LoginForm;
    // collect user input data
    if(isset($_POST['LoginForm']))
    {
        $form->attributes=$_POST['LoginForm'];
        // validate user input and redirect to previous page if valid
        if($form->validate()  && $form->login()) $this->redirect(Yii::app()->user->returnUrl);
    }
    // display the login form
    $this->render('login',array('form'=>$form));
}

First, a new object is created of type LoginForm. That class is defined in the LoginForm.php Model file. If the form has been submitted, the form data is collected and the data is validated. If the data passes the validation, the user will be redirected to whatever URL got them here in the first place. If the form has not been submitted, or if the form data does not pass the validation routine, then the login form is displayed, and it is passed the LoginForm object. The default login form looks like this (note the reference to demo/demo and admin/admin, already discussed):

Now, the call to the validate() method in the above code means that the form data has to pass the validation rules established in the LoginForm class. This is basic Model validation as defined by the rules() method of the Model (also see my post on basic Model edits):

public function rules()
{
    return array(
        // username and password are required
        array('username, password', 'required'),
        // password needs to be authenticated
        array('password', 'authenticate'),
    );
}

As you can see, those rules say that both the username and password are required and that the password has to pass the authenticate() method. This is not a built-in validation routine, but is defined in LoginForm. The LoginForm::authenticate() method starts off like so:

public function authenticate($attribute,$params)
{
    if(!$this->hasErrors())  // we only want to authenticate when no input errors
    {
        $identity=new UserIdentity($this->username,$this->password);
        $identity->authenticate();
        switch($identity->errorCode)

If there are no errors when this method is called (an error would be a lack of a username or password), a UserIdentity object is created, passing that object the submitted username and password. Then the UserIdentity object’s authenticate() method is called. This gets us to protected/components/UserIdentity.php, which defines the class and the method. If you’re having trouble following the process thus far, here it is pictorially:

Note that any errors stops the process from continuing and just re-displays the login form, with the errors reported.

As I already wrote above, the UserIdentity authenticate() method as written compares the submitted values against predefined combinations and returns a message accordingly. If you want to test the submitted values against the database, you’ll need to add some code. Start by fetching the record for the given username:

class UserIdentity extends CUserIdentity
{
    public function authenticate()
    {
        $user = User::model()->findByAttributes(array('username'=>$this->username));

Now the $user object represents the User record with an username field equal to the submitted username. (The CUserIdentity class’s constructor takes the provided username and password and stores them in $this->username and $this->password, just to be clear.) You could, and might be inclined, to attempt to retrieve the record that matches both the username AND the password, but if you were to do that, you wouldn’t be able to provide more meaningful error messages: username doesn’t exist, username does exist but the password doesn’t match, and so forth.

Next the authenticate() method should check a series of possiblities and assigns constant values to the errorCode variable:

if ($user===null) { // No user found!
    $this->errorCode=self::ERROR_USERNAME_INVALID;
} else if ($user->pass !== SHA1($this->password) ) { // Invalid password!
    $this->errorCode=self::ERROR_PASSWORD_INVALID;

In the first conditional, if $user has no value, then no records were found, so the username was incorrect. In the second conditional, the stored password is compared against the SHA1() version of the submitted password. This assumes the record’s password was stored in a SHA1() encrypted format. If neither of these conditionals are true, then everything is okay:

} else { // Okay!
    $this->errorCode=self::ERROR_NONE;
}

Finally, the method returns a boolean value, indicating an error or not:

return !$this->errorCode;

The presence of an error code gets used in the authenticate() method of the LoginForm Model, in response to the authentication attempt (this is a continuation of the LoginForm::authenticate() code shown above):

$identity->authenticate();
switch($identity->errorCode)
{
    case UserIdentity::ERROR_NONE:
        $duration=$this->rememberMe ? 3600*24*30 : 0; // 30 days
        Yii::app()->user->login($identity,$duration);
        break;
    case UserIdentity::ERROR_USERNAME_INVALID:
        $this->addError('username','Username is incorrect.');
        break;
    default: // UserIdentity::ERROR_PASSWORD_INVALID
        $this->addError('password','Password is incorrect.');
        break;
}

So if there was no error, the user is logged in. The duration—the period for which they’ll be logged in—is either 30 days or for just the session, depending upon whether they checked the rememberMe box or not (see the login form image). If either error is present, it’ll be added to the current object, the validation will fail, meaning that the conditional in the actionLogin() method of SiteController.php will be false, and the login form will be rendered again, this time with the error message. The whole process therefore becomes:

That’s an outline of the basic process, using a User Model (based upon a database table), instead of hard-coded values. All of this information can also be found in the Yii documentation, just not written quite like this. To take this information further, and to make it more practical, my next post will show you how to modify all of the Yii-generated code in order to:

• Store the user’s ID so it can be referenced as they peruse the site
• Store the user’s “role”, like reader, editor, and writer, as well.
• Authenticate the user with their email address and password, not their username.

That post will follow in just a couple of days. EDIT: Here it is! As always, thanks for your interest in what I have to say and let me know if you have any questions or comments. Thanks, Larry