The protected/views/modelName/_form.php file defines the form that’s used to both create and update an individual record. In it, checkboxes are created using:

<?php echo $form->checkBox($model,'attribute'); ?>

I can pass an array of options to the checkbox() method in order to tweak how it behaves. In my example, I want to set the values assigned to the Model in both the checked and unchecked states. Here’s how you do that:

<?php echo $form->checkBox($model,'attribute',array('value' => 'Y', 'uncheckValue'=>'N')); ?>

The value option literally creates the value=”Y” code in the checkbox HTML. The uncheckValue option is something that Yii adds that allows you to indicate what the value should be if the box is not checked. It’s a nice addition, saving you from having to add code in the Model to define the value when the box isn’t checked.

So now my Model will receive, and the database will store, either Y or N, depending upon whether the box is checked or not. The next hurdle comes for properly handling updates. An update uses this same form, but the above code alone will not automatically check the box should the database store the value Y for the given attribute. My solution, then, was to convert Y to true and N to false when retrieving the Model item, but only on an update. In the other situations where a Model record might be retrieved and used, the Y/N values are preferable.

In the Controller for this Model, the update action is where I want to start my changes. That method first loads an individual Model using the Controller’s loadModel() method:

public function actionUpdate() {
    $model=$this->loadModel();

After this point, I want to convert all instances of Y/N to true/false, so I invoke a Model method (I’ll define next) to perform that task:

$model->convertToBooleans();

The convertToBooleans() method is defined in the Model. It first defines an array of all attributes that need the conversion:

public function convertToBooleans() {
    $attributes = array('newsletter', 'offers', ...);

This list of strings must exactly match the names of the corresponding Model attributes. From here, there are a couple of ways to proceed. One obvious route is to loop through the array using a foreach. Within the foreach, the ternary operator is used to assign to the Model’s attribute a Boolean based upon its current value:

foreach ($attributes as $attr) {
    $this->$attr = ($this->$attr == 'Y') ? true : false;
}

So that’s all you need to do to make this work. But if you’re like me and you prefer to make your methods as atomic as possible, you could create a separate Model method that performs the specific conversion:

public function convertAttributeToBoolean($attr) {
    $this->$attr = ($this->$attr == 'Y') ? true : false;
}

In this case, the convertToBooleans() method needs to call this other method for each item in the array. The array_map() PHP function can apply a function to every element in an array:

array_map('someFunction', $someArray);

To use an object method, use this syntax:

array_map(array($object, 'methodName'), $someArray);

So the convertToBooleans() method could do this:

array_map(array($this, 'convertAttributeToBoolean'), $attributes);

And that’s what you need to do to make form checkboxes work with non-Boolean database values (MySQL does support storing of Booleans, though). Remember that you first need to update the _form.php script, which will be used for both adding and updating records. Then you only need to convert the Y/N values to Booleans when you go to update a record.

I hope this helps and thanks for reading. Let me know if you have any questions or comments. Thanks, Larry!

'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.

Lerdorf also posted his own thoughts on Facebook’s use of HipHop PHP for faster PHP execution, if you’re looking for something to read.

public function accessRules()
{
    return array(
        array('allow',  // allow all users to perform 'list' and 'show' actions
            'actions'=>array('list','show'),
            'users'=>array('*'),
        ),
        array('allow', // allow authenticated user to perform 'create' and 'update' actions
            'actions'=>array('create','update'),
            'users'=>array('@'),
        ),
        array('allow', // allow admin user to perform 'admin' and 'delete' actions
            'actions'=>array('admin','delete'),
            'users'=>array('admin'),
        ),
        array('deny',  // deny all users
            'users'=>array('*'),
        ),
    );
}

That’s the default setting for a Controller, where anyone can perform list and show actions, meaning that anyone can list all records or show individual records in an associated Model. The next section allows any logged-in user to perform create and update actions. Next, only administrators can perform admin and delete actions. Finally, a global deny for all users is added, to cover any situation that wasn’t explicitly defined. This is just a good security practice. Note that these rules just apply to this Controller; each Controller needs its own rules.

So at the most basic level, your access rules begin by allowing or denying actions to logged-in or non-logged-in users. When you go to create your own rules, start with what anyone can do and end with what no one can do. For example, say you have some user management system that includes the Models User and UserType, corresponding to related tables in the database. The UserType would be a simple two-field object—id and type, where type might be reader, writer, editor, and so forth. Each User then is assigned a single, specific type. I’d be inclined to grant list and show permissions to everyone, as that might be useful for browsing users by type and would be necessary for adding new users. However, I probably wouldn’t allow create, update, admin (which is really a variation on list), or delete permissions on UserType at all, with the thinking that these are static values. The accessRules() would then be:

public function accessRules()
{
    return array(
        array('allow',  // allow all users to perform 'list' and 'show' actions
            'actions'=>array('list','show'),
            'users'=>array('*'),
        ),
        array('deny', // no one can create, update, or delete these:
            'actions'=>array('create','update','admin','delete'),
            'users'=>array('*'),
        ),
        array('deny',  // deny all users anything not specified
            'users'=>array('*'),
        ),
    );
}

As you can see, just to be extra careful, I include a final deny clause still: if actions are added later the default behavior will be denial; only by then changing the rules can that action be executed by anyone.

To take this beyond logged-in vs. non-logged-in users, you need to know that the representation of logged-in users relies upon Yii’s authentication components. In the default rules, the admin user can perform certain actions, where “admin” is the actual name of the user that is logged in, and comes from protected/components/UserIdentity.php.  I write about the authentication process in detail in two posts: the first covering simple authentication, the second covering more evolved authentication. The default Yii application allows for two users, with names of demo and admin, but you’d likely have a more elaborate system in place. If you know only a limited number of users will be admins, you could hardcode their usernames into the rules:

array('allow', // allow harold and maude user to perform 'admin' and 'delete' actions
    'actions'=>array('admin','delete'),
    'users'=>array('harold','maude'),
),

This is still a bit too static, though. Perhaps your users in the database would be registered by user type, or role, and that the permissions would be based upon these roles. In that case, you can add an expression element to the returned array in the access rules:

array('allow',
    'actions'=>array('admin','delete'),
    'users'=>array('@'),
    'expression'=>'PHP code to be evaluated'
),

Two things about this expression. First, you still need to use the users element, and you’ll probably want to still restrict this to logged-in users (most likely). Second, the expression itself should be some PHP code, quoted, that when evaluated gives a Boolean result. If the code in the expression will be true, then permission will be allowed; false, denied. Say you wanted to restrict the publish action to only those with the role of editor:

array('allow',
    'actions'=>array('publish'),
    'users'=>array('@'),
    'expression'=>'isset($user->role) && ($user->role==="editor")'
),

The $user->role value would have to be established when the user logs in, as part of the authentication process. I discuss this exact example in my second post that covers more evolved authentication. And I put the entire expression within quotes (it doesn’t matter whether you use single or double, so long as you don’t create a parse error). With that rule, users that aren’t logged in, or users that are logged in but have non-editor roles, won’t be able to take that action.

A final way in which I’ve enforced authorization in previous Yii projects involves a bit of a hack. I had a site where users with a certain role could create certain types of content. They could also update or delete those types of content, but only if they were the one to create that content in the first place. In other words, say a user creates an event, then their user ID gets associated with that event’s record. The update and delete actions in the EventController should only be executable if the currently-logged-in user’s ID is the same as the ownerId of the event in question. As far as I know, this cannot be addressed in the accessRules() method, because those rules are evaluated prior to the loading of any specific Model. My solution, perhaps a hack but it works, was to add the proper logic within the actions. Here’s a simplified version of how that would look within one of the actions:

public function actionDelete()
{
    $event = $this->loadEvents(); // Fetch the specific event Model.
    // Can only delete the events they created:
    if ($event->ownerId == Yii::app()->user->id) {
        $event->delete();
    } else {
        throw new CHttpException(403,'Invalid request. You are not allowed to delete this event.');
    }
}

As I said, that’s a hack but it works fine for me and is simple enough to follow (also, the actions that display events for editing and deleting get changed to only list those with a matching ownerId). A better solution would likely be to use Yii’s Role-Based Access Control (RBAC). I haven’t personally gone down that path yet as I haven’t had the need; the above knowledge has more than sufficed for the sites I’ve created thus far.

As always, thanks for reading and let me know what comments or questions you may have. Thanks, Larry

• 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()) $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

Next, download the Zend Framework. You’ll want to download the latest full package, even though you’ll only use a bit of it. After the download has completed, expand the ZIP or TAR.GZ file (whichever format you choose to download the framework in). The result will be a folder named ZendFramework-x.y.z. (where x.y.z represent the full version number). Within that folder, go into library/Zend and copy Exception.php to protected/vendors/Zend. This is the file that the Zend Framework uses to report problems, so you’ll want to include it while developing and debugging Zend_Lucene with Yii. Also copy the Search folder to protected/vendors/Zend. You’ll end up with a structure like this:

In terms of the MVC architecture, the Zend Framework provides the Model to be used by this search process, but the Controller and View will still be done using Yii. First, let’s write a new Controller for searching:

class SearchController extends CController
{
    private $_indexFiles = '../runtime/search';
    public function actionIndex() {}
    public function actionCreate() {}
    public function actionSearch() {}
    public function actionUpdate() {}
}

As with all Yii Controllers, this one extends the base CController class. Within this Controller the various methods are defined, corresponding to the actions that’ll be taken in the search process. The index action is the default and is for accessing the search page without performing an actual search (e.g., clicking on a link to go to the search page). The create action will be used to generate the search database: the series of files that Lucene needs to perform its searches. The search action is for handling submission of the search form (i.e., it does the actual searching). Finally, the update action is for updating the Lucene database files when necessary (like when the site content changes). The class also has one private variable that stores the location on the server of Lucene database files. I chose to put them in a search folder found within runtime (protected/runtime/search). This class member is good to have as multiple methods will need this information but I create it as a private variable as it’s not necessary (nor should it be accessed) outside of the class. As a naming convention, some like to use underscores at the front of private class variables.

Within three of the methods (not actionIndex()), the Controller will use Zend_Lucene. In order to do so, this script needs access to the Zend files, so import the contents of the vendors directory at the top of this script, just before the class definition begins:

Yii::import('application.vendors.*');

Then, include the Lucene.php page, found within the Zend Framework Search folder:

require_once('Zend/Search/Lucene.php');

Now this Yii Controller can create objects of type Zend_Search_Lucene, which is defined in that file. The actions will use that object type to perform the searches. To start, the index action just renders the index View:

public function actionIndex()
{
    $this->render('index');
}

Presumably the index View file just shows the search form. The search form, by the way, should have an action attribute of www.example.com/index.php/search/search, so that it calls the search action of the search Controller. The form should contain a text input with the name terms.

The update action would be used by an administrator to update the search database. Perhaps it’d be called automatically after some content is generated or once per hour or day. It would destroy the existing search database and then invoke the actionCreate() method. The Lucene database can’t just be updated for whatever content changed; you need to destroy and recreate it instead. It really wouldn’t matter what View this action renders, depending upon what you want the admin to see. Maybe the View would just show a message indicating that the database has been updated.

The create action is an important one, and is where real knowledge of Lucene comes into play. The shell of it would look like so:

public function actionCreate() {
    $index = new Zend_Search_Lucene($this->_indexFile, true);
    // Add documents to the database.
    $index->commit();
    $this->render('create');
}

First, a Zend_Search_Lucene object is created (again, this is where Yii is making use of a class defined outside of Yii; it’s a sweet thing). The first argument provided when creating the object is the location of the database files. This is represented by the Controller variable, accessible in $this->_indexFile. The second argument indicates that a fresh database should be created. Next up, you add content to the database. This is complicated and well beyond the scope of what I’m writing here. I’ll try to discuss this, in brief, in a separate post, but I’d recommend you read as much as you can online first. In a very minimalistic way, you could add a single HTML page to the search database by doing this:

$url = 'http://www.example.com/index.php/page/show/id/1';
$doc = Zend_Search_Lucene_Document_Html::loadHTMLFile($url);
$index->addDocument($doc);

Finally the database has to be saved, by invoking the commit() method. And then some View is rendered. As this action would also only be likely called by an administrator or cron, it doesn’t matter much what the View contains.

Lastly, there’s the search action. This action would check for search terms, run the search against the database, then send the results on to a View:

public function actionSearch() {
    if (isset($_GET['terms'])) {
        $index = new Zend_Search_Lucene($this->_indexFile);
        $results = $index->find($_GET['terms']);
        $this->render('search', array('results' => $results));
    } else {
        $this->render('index');
    }
}

First the method checks for the presence of search terms in the URL. Then it creates a Zend_Search_Lucene object, which is necessary for both creating and using the search database. This time only the location of the search database is passed when creating the object. The object’s find() method is invoked for performing the search (it can be that simple!). Then the search View is rendered, passing it the results. If no search terms were passed to this page, the index View is rendered instead. As for the search results View, a basic version to get you started might look like this:

<h2>Search Results for "<?php echo CHtml::encode($_GET['terms']); ?>"</h2>
<?php if ($results): ?>
    <?php foreach($results as $result): ?>
        <p><?php echo CHtml::encode($result->title); ?></p>
    <?php endeach; ?>
<?php else: ?>
    <p class="error">No results matched your search terms.</p>
<?php endif; ?>

That’s largely the logic and structure of a search results View. It displays the provided search terms and checks for results. If there were some, each result title is printed. In a real application, you’d likely link the title to a URL or whatever but I don’t want to get too messy here. If you print_r() $result, you’ll see a bunch of information there that you can use.

So that’s the steps you need to take to get started using Zend_Lucene within your Yii application. These steps provide functionality; mastering Lucene is how you make this more professional. I’ll try to write more about defining a Lucene search database in subsequent posts towards that end. If you have any comments, questions, or requests, let me know.

Thanks,

Larry

Once the FCKEditor package is downloaded, you’ll need to expand the ZIP or TAR.GZ file (you can download the package in either format). The resulting folder is called just fckeditor and can be moved, in its entirety to the root of your Web directory. (You don’t actually need all the files in the folder but it’s fine to have them on the server.) Later on I’ll discuss configuring the editor but for now let’s move on to the Yii side of things.

Next, download the FCKEditor integration widget for Yii. Expand the downloaded ZIP file and you’ll end up with another folder called just fckeditor. Move this entire folder to your application’s extensions directory (i.e., protected/extensions).

To use the FCKEditor in a form, you’ll need to edit the _form.php file for the particular View. For example, on one site I edited protected/views/page/_form.php, as the admin created the site’s content through a Page Model. By default the form will have a standard textarea for every TEXT type MySQL column:

<?php echo CHtml::activeTextArea($model,'content',array('rows'=>6, 'cols'=>50)); ?>

To use FCKEditor instead of the textarea, invoke the integration widget by replacing that code with this:

<?php $this->widget('application.extensions.fckeditor.FCKEditorWidget',array(
 'model'     =>  $model,
 'attribute' => 'content',
 'height'    =>  '600px',
 'width'     =>  '100%',
 'fckeditor' =>  dirname(Yii::app()->basePath).'/htdocs/fckeditor/fckeditor.php',
 'fckBasePath' => Yii::app()->baseUrl.'/fckeditor/')
 ); ?>

That code starts by saying a widget should be rendered in this place, specifically the FCKEditorWidget. That widget gets passed an array of values to configure it. To start, pass the Model, which Yii stores in the $model variable by default (in older versions of Yii, you would have seen a specific Model name there instead, like $page). The attribute element is the name of the Model attribute, which will likely also match the field name in the database. Those two values are the most important and must be correct for each form. The height and width are obvious. The next two values point to the location of the FCKEditor on the server. If you moved those files into the root Web directory, still in the fckeditor folder, these lines will work just fine (assuming htdocs is the root Web directory).

So those steps are pretty easy to understand and will get you a working WYSIWYG editor in no time. But you’ll likely need to tweak how the FCKEditor behaves, too, which is much more complicated. For starters, if you want to allow the admin to upload files to the server, like images or videos, you’ll need to enable the file manager. Presumably you’ll be using PHP for this purpose. In that case, open fckeditor/editor/filemanager/connectors/php/config.php in your text editor or IDE. This tool is disabled by default, thanks to this line:

$Config['Enabled'] = false ;

To enable file management, this variable must be assigned a true value. You could do this:

$Config['Enabled'] = true ;

but that’d be terribly insecure, as it’d allow ANYONE to manipulate files on the server (shudder). You could use Apache’s HTTP Authentication to restrict access to the filemanager/connectors/php directory, but then you’d have a separate, secondary login system from your application’s login system. So instead, I tap into the Yii user management system here. Presumably an administrator has to login in order to update the content. If so, then they’ll have a session, by default named PHPSESSID. So you can check for a cookie:

$Config['Enabled'] = isset($_COOKIE['PHPSESSID']) ;

Of course, that would also allow logged-in non-administrative users to use the file manager, too. So another clause needs to be added to this conditional. What that clause is will depend upon your situation but will likely involve something stored in $_SESSION. For example, perhaps your content admin account has a user name of ‘moderator’. If so, then you could use this code to verify that the user should be allowed to use the file manager:

session_start();
$Config['Enabled'] = (isset($_COOKIE['PHPSESSID']) && (in_array('moderator', $_SESSION))) ;

A couple of explanations: First, you have to start the session in this file, as it won’t otherwise be started. Second, Yii stores values in the $_SESSION array using a somewhat more secure technique. Instead of just having name => value, Yii prepends a hash of random characters to the name of each element in $_SESSION. The user’s name, therefore, might be stored in session like so:

$_SESSION['a4d58ee27e5fb1f0827af0550771ea7e__name'] = 'moderator';

Because of this, you can’t just easily check the value of, say, $_SESSION['name'], which is why I use in_array() in the above code.

Also, while you’re editing the config.php file, you may want to change the name of the UserFilesPath:

$Config['UserFilesPath'] = '/something_clever/' ;

This is where the user-uploaded files will be stored. This value will appear in the HTML source when those files are used on a page, so this isn’t a huge security benefit, but it’s an easy step to take. You’ll need to create the corresponding folder, too.

Next thing up, you’ll likely want to configure the FCKEditor as it’ll behave in the Web browser. To do so, you’ll edit the FCKEditor configuration file (fckeditor/fckconfig.js). There are a ton of options there, best described in the FCKEditor manual. For example, you can set the EditorAreaCSS and EditorAreaStyles values so that the FCKEditor window uses the same styling as your whole site. I also normally edit the toolbarsets so that limited options are presented to the end user (thereby keeping them from making a mess of the site).

You can also change some FCKEditor settings on the fly when you invoke the Yii widget. To do so, pass a config element with an array of values when calling the widget:

<?php $this->widget('application.extensions.fckeditor.FCKEditorWidget',array(
'model'     =>  $model,
'attribute' => 'content',
'height'    =>  '600px',
'width'     =>  '100%',
'fckeditor' =>  dirname(Yii::app()->basePath).'/htdocs/fckeditor/fckeditor.php',
'fckBasePath' => Yii::app()->baseUrl.'/fckeditor/'),
'config' => array('EditorAreaCSS'=>Yii::app()->baseUrl.'/css/other.css')
); ?>

You might do this to change the styling of a specific FCKEditor window, as in that code.

Finally, consider that the Views, by default, echo out Model data using the CHtml::encode() method. This is a logical and necessary security feature, as it prevents cross-site scripting attacks (XSS). However, it also makes the FCKEditor-generated HTML completely useless (it’s the equivalent of PHP’s htmlspecialchars() function). A logical work-around is to use PHP’s strip_tags() instead, providing it with the optional second argument of allowable tags:

echo strip_tags($model->content, '<p><a><div><ul><ol><li><span>');

Okay, so there’s that then. I think that’s everything you should know to get going with FCKEditor and Yii. Let me know if you have any questions or would like me to write up any other subject. As always, thanks for reading what I have to say.

Larry

• GUI tools for auto-generating code
• Many types of caches for improved performance
• support for replicated databases (great for demanding sites)
• REST support

I don’t plan on changing frameworks for a while, as I’m quite pleased with Yii, but if you’re looking for a new PHP framework, you may want to consider DooPHP as well.