I first started using the Yii framework about two and half years ago. I’ve never been much of a framework person, but Yii really felt right to me, quite similar to Ruby on Rails, which I also always liked. Being a writer, after learning to use the framework, I wrote an introductory series on the subject, which has been quite popular. In all modesty, many have suggested it’s the best documentation available. In fact, the creator of Yii liked my series so much that he listed it prominently on the official Yii documentation page (it’s now under tutorials). Some time after writing that series, I started thinking about writing a full book on Yii, because that’s what I do.

When I decided to write a book on Yii, I figured I’d self-publish it, for a couple of reasons. First, even though I have a wonderful relationship with Peachpit Press, I’m not sure they’d want to do a book on Yii, as the market is kind of small. Second, even if Peachpit would publish such a book, I doubt I’d make much money on the project, considering the small market. By comparison, if I self-publish, I can make 4-5 times per book what I’d make if I went through a publisher. The higher per copy amount could be enough to make up for the smaller sales, ending up with a project that’s financially worth my time to do (sorry to be crass about the money, but writing a book is a lot of work and I do have bills to pay!). Fourth, I’ve been intrigued about self-publishing for some time. And, fifth, self-publishing would give me the opportunity to distribute the book in unique formats and channels, such as a chapter at a time.

If I had my act together (which is to say, if my life were other than it is, in about ten ways), I would have been on the ball and published this book a year or more ago. Sadly, that has not been the case. I keep fairly busy work-wise, and I don’t actually have the time (due to personal constraints) to put in 40-hour weeks, so it’s really hard to add new projects, especially on the level of an entire book. Moreover, self-publishing means no guaranteed money, so I’d have to not do paying work while not making money working on the Yii book, which is a tough situation to be in.

All that being said, it is still my intention to write and self-publish a book on Yii. The only question is: when? This is the question I’m getting asked a lot lately. Before I do anything towards a book on Yii, I still have to:

• Finish my Modern JavaScript: Develop and Design book (which I’m weeks late on as is)
• Write one more article in support of my PHP and MySQL for Dynamic Web Sites: Visual QuickPro Guide (4th Edition) [I've written two out of three articles, but I'm weeks late on that, too.]
• Come up with a list of videos to do in support of my Modern JavaScript: Develop and Design book
• Actually do those videos
• Continue doing the Web development and other work I have for my clients

So…yikes. Don’t get my wrong: I’m quite fortunate to be busy, but yikes! I’ll be crying if I haven’t finished all of the above by the end of this year, which means in theory I can begin the Yii book at the beginning of 2012. However, I have the third edition of my PHP 5 Advanced: Visual QuickPro Guide due at the end of April. That does give me four months, but I’d like actually make that deadline for a change (my publisher is wonderfully understanding, but…).

Also, along with writing the Yii book, I’m going to have to come up with a site and an ecommerce system and so forth (I already have the software that can output PDFs, ePubs, and mobis). If I’m being optimistic, perhaps in 2012 I can do two Yii chapters per month, but the PHP 5 Advanced book will need to be my first priority. I also don’t want to start the Yii book, get some people paying for it (in part or in whole), and then have the project drag out. I don’t know. We shall see.

I very much thank everyone for their interest in my writing a book on Yii and I hope to make that happen. If you follow the blog and/or subscribe to my newsletter, you’ll get updates as to how this is progressing, when and if it does actually progress.

So, CodeLobster is an IDE for PHP that runs on Windows. It’s available in both a free and “professional” version, the professional version costing $100 (US). The free version comes with an HTML editor and inspector, a CSS editor, a JavaScript editor, a PHP editor, and a PHP debugger. This all includes the standard features such as code completion, code collapsing, browser preview, project management, FTP, and so forth. The professional version includes all of those features, plus plug-ins for specific tools and frameworks: CakePHP, CodeIgniter, Drupal, jQuery, Joomla, Smarty, Symfony, WordPress, and Yii. In other words, the professional version gives you code completion, contextual help, and so forth for these additional tools that you may also be programming in.

As I said, I haven’t personally used it, but if you’re looking for a PHP/Web Development IDE, it may be worth checking out.

What you’ll want to do to create a cookie is create a new object of type CHttpCookie: Yii’s class for cookies. Here, then, is the syntax for setting a cookie in Yii:

Yii::app()->request->cookies['name'] = new CHttpCookie('name', 'value');

You must use the same name value in both places, replacing it with the actual cookie name. Remember that the cookie’s name, and value, are visible to users in their browsers, so one ought to be prudent about what name you use and be extra mindful of what values are being stored.

Tip: Because the cookie’s name must be used twice in the code, you may want to consider assigning the cookie’s name to a variable that is used in both instances instead.

Once you’ve created a cookie, you can access it (on subsequent pages, because cookies are never immediately available to the page that set them), using Yii::app()->request->cookies['name']->value. You have to use the extra ->value part, because the “cookie” being created is actually an object of type CHttpCookie (and Yii, internally, takes care of actually sending the cookie to the browser and reading the received cookie from the browser).

To test if a cookie exists, just use isset() on Yii::app()->request->cookies['name'], as you would any other variable.

To delete an existing cookie, just unset the element as you would any array element:

unset(Yii::app()->request->cookies['name']);

To delete all existing cookies (for that site), use

Yii::app()->request->cookies->clear();

By default, cookies will be set to expire when the browser window is closed. To change that, you need to modify the properties of the cookie. You can’t do so when you create the CHttpCookie object (i.e., the only arguments to the constructor are the cookie’s name and value), so you must separately create a new object of type CHttpCookie, to be assigned to Yii::app()->request->cookies later:

$cookie = new CHttpCookie('name', 'value');

Then adjust the expire attribute:

$cookie->expire = time() + (60*60*24); // 24 hours

Then add the cookie to the application:

Yii::app()->request->cookies['name'] = $cookie;

You can manipulate other cookie properties using the above syntax: domain, httpOnly, path, and secure. Each of these correspond to the arguments to the setcookie() function. (You can also manipulate the value of the cookie through $cookie->value and the cookie’s name through $cookie->name). For example, if you want to limit a cookie to a specific domain, or subdomain, use domain; to limit it to a specific folder, use path; and to only transmit the cookie over SSL, set secure to true.

You can also improve the security of your cookies by setting Yii’s enableCookieValidation to true, in the Yii configuration file:

return array(
    'components'=>array(
        'request'=>array(
            'enableCookieValidation'=>true,
        ),
    ),
);

Cookie validation prevents cookies from being manipulated in the browser. To accomplish that, Yii stores a hashed representation of the cookie’s value when it gets sent, and then compares the received cookie’s value to ensure they are the same. Obviously there’s extra overhead required to do this, but in some instances, the extra effort is justified by the extra security.

Finally, one good reason to use cookies in a Yii-based site, even if the site is otherwise using sessions, is to prevent Cross-site Request Forgery (CSRF) attacks. A CSRF works like this: malicious site A has some code on it, such as an image tag whose src attribute points to a page on site B that does something meaningful: http://www.example.com/page.php?action=this. When any viewer loads the page on site A, the use of that src attribute has the effect of that user performing a request of the page on site B.

As an example, let’s say that an administrator at your site logs in and does whatever but doesn’t log out. The administrator therefore still has a cookie in her or his browser indicating access to the site (i.e., the user could open the browser and perform admin tasks without logging in again). Now let’s say that the src attribute on malicious site A points to a page on your site that deletes a blog posting. If the administrator with the live cookie loads that page on site A, it will have the same effect as if that administrator went to your site and requested that page directly. This is not good.

To prevent a CSRF attack on your site, first make sure that all significant form submissions use POST instead of GET. You should be using POST for any form that changes server content anyway, but a CSRF POST attack is a bit harder to pull off than a GET attack.

Second, set enableCsrfValidation to true in your configuration file:

return array(
    'components'=>array(
        'request'=>array(
            'enableCsrfValidation'=>true,
        ),
    ),
);

By doing this, Yii will send a cookie with a unique identifier to the user. All forms will then store that same identifier in a hidden input. The form submission will only be handled then if the two identifiers match. With the case of a CSRF attack, the two identifiers will not match because the form’s identifier will not be passed as part of the request (I hope this is clear; if not, let me know). Note that this only works if you’re using CHtml to create your forms (if you manually create the form tags, Yii won’t insert the necessary code for preventing CSRF attacks).

The most important thing to remember about cookies, which I’ve already stated, is that cookies are visible to the user in the browser. And unless you’re using SSL for the cookies, they are also visible to anyone else while being transmitted back and forth between the server and the client (which happens on every page request). So be careful of what gets stored in a cookie! If the data is particularly sensitive, use sessions instead of cookies.

The question I can’t really answer is what advantage Yii has over the X framework. The only other PHP framework I’ve used extensively is the Zend framework. The Zend framework has a lot going for it and is worth anyone’s consideration. To me, its biggest asset is that you can use it piecemeal and independently (I’ve often used components of the Zend Framework in Yii-based and non-framework-based sites), but I just don’t like the Zend Framework as the basis of an entire site. It requires a lot of work, the documentation is overwhelming while still not being that great, and it just doesn’t “fell” right to me.

Anyway, the point of this post is that there’s a nice article at SHELDMANDU from back in January in which the author does a great job of comparing the Yii framework with the Zend framework and Code Igniter (I’ve heard many good things about Code Igniter). Moreover, the author lays out some of his criteria for what he wants in a framework, has reasonable and detailed critiques, and also specifically details why he didn’t consider other frameworks in his comparison. If you’re looking into frameworks, spend five minutes reading that article to help educate yourself as to what considerations you should have in mind during your research.

The first thing to know about using sessions in Yii is that you don’t have to do anything to enable them, which is to say you don’t have to invoke session_start(), as you would in a standard PHP script. This is the behavior with Yii’s autoStart session property set to true, which is the default. Even without using session_start(), you could, of course, make use of the $_SESSION superglobal array, as you would in a standard PHP script, but it’s best when using frameworks to make total use of the framework. The Yii equivalent to $_SESSION is Yii::app()->session:

Yii::app()->session['var'] = 'value';
echo Yii::app()->session['var']; // Prints "value"

And that’s all there is to it. To remove a session variable, apply unset(), as you would to any other variable:

unset(Yii::app()->session['var']);

So…nothing really unexpected there, once you know where to find the session data. The more complex consideration is how to configure sessions for your Yii application. You can do so using the primary configuration file (protected/config/main.php). Within that, you would add a “session” element to the “components” array, wherein you customize how the sessions behave. The key attributes are:

• autoStart, which defaults to true (i.e., always start sessions)
• cookieMode, with acceptable values of none, allow, and only, equating to: don’t use cookies, use cookies if possible, and only use cookies; defaults to allow
• cookieParams, for adjusting the session cookie’s arguments, such as its lifetime, path, domain, and HTTPS-only
• gCProbability, for setting the probability of garbage collection being performance, with a default of 1, as in a 1% chance
• savePath, for setting the directory on the server used as the session directory, with a default of /tmp
• sessionName, for setting the session’s, um, name, which defaults to PHPSESSID
• timeout, for setting after how many seconds a session is considered idle, which defaults to 1440

For all of these, the default values are the same as those that PHP sessions commonly run using, except for autoStart.

If your site will not be using sessions at all, you would want to disable them by adding this code to the “components” section of protected/config/main.php:

'session' => array (
    'autoStart' => false,
),

If you are using sessions, for security purposes, you may want to change the session’s name, always require cookies, and change the save path:

'session' => array (
    'sessionName' => 'Site Access',
    'cookieMode' => 'only',
    'savePath' => '/path/to/new/directory',
),

The save path, in case you’re not familiar with it, is where the session data is stored on the server. By default, this is a temporary directory, globally readable and writable. Every site running on the sever, if there are many (and shared hosting plans can have dozens on a single server), share this same directory. This means that any site on the server can read any other site’s stored session data. For this reason, changing the save path to a directory within your own site can be a security improvement. Alternatively, you can store the session data in a database. To do that, add this code to the “components” section of protected/config/main.php:

'session' => array (
    'class' => 'system.web.CDbHttpSession',
    'connectionID' => 'db',
    'sessionTableName' => 'actual_table_name',
),

If you choose this route, Yii will automatically create the table if it does not exist. You can also perform any of the other session configuration changes in that code block, too.

So…what else? Frequently, for debugging purposes, and sometimes to store it in the database, I like to know the user’s current session ID. That value can be found in Yii::app()->session->sessionID.

Finally, when the user logs out, you may want to formally eradicate the session. To do so, call Yii::app()->session->clear() to remove all of the session variables. Then call Yii::app()->session->destroy() to get rid of the actual data stored on the server.

And that’s what there is to know about using sessions with Yii, at least that’s all the key information. I hope this helps you with your Yii-based applications. As always, thanks for reading and let me know if you have any comments or questions.

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

    $this->render('update',array(
        'model'=>$data
    ));
}

Note: That method would also have code in it for handling the submission of the update form, but I’m trying not to complicate the discussion.

As you can see in that code, the render() method, defined in the CController class, is how a View file is chosen for rendering. The first argument to the method is the View file to be rendered, without its .php extension. The render() method will render the View file within the appropriate layout file. In other words, the View file will be rendered with its context. The above code renders update.php, for the associated Controller, wrapped within the views/layouts/main.php layout file (the default).

The second argument to render() is an array of data that can be sent to the View file. In the above code, the Model instance is being passed along. In update.php, references to the $model variable will refer to the loaded data (note that the View gets its variable names from the indexes used in the array).

The render() method takes an optional third argument, which is a Boolean indicating if the rendered result should be returned to the Controller instead of sent to the Web browser. This would be useful if you wanted to render the page and then send the output in an email or write it to a text file on the server (to act as a cached version).

Sometimes you’ll want to render a View file without incorporating the layout. To do that, invoke renderPartial(). For example, both the update.php and create.php View files, auto-generated by Yii, just provide a context, and then include the form file:

<?php echo $this->renderPartial('_form', array('model'=>$model)); ?>

Since the initial View file will have already be rendered within the layout context, the layout shouldn’t be rendered again. The renderPartial() method will render just the named View file. Its second argument, as with render(), can be used to pass data to the View file. In the above, the Model instance is passed along.

Tip: The renderPartial() method is also used for Ajax calls, where the layout isn’t appropriate.

As mentioned already, the file being rendered comes from the directory associated with the current Controller. For example, when updating an Employee record, the URL is something like www.example.com/index.php/employee/update/id/23. This calls the actionUpdate() method of the EmployeeController class (whose code is partially shown above). That method renders the “update” View, which is to say protected/views/employee/update.php. But there are rare cases where you’ll need to render View files from other subdirectories. For example, you may want to include a search form on a page, with that form found within another View directory. To change the reference point, start the View reference with a double slash, which means to start in the views folder. Then indicate the subdirectory and file, still omitting the extension:

<?php echo $this->renderPartial('//search/_form'); ?>

And that’s all there is to it!

View rendering is one of the most important concepts to grasp in an MVC design. Fortunately, it’s not that hard to follow in Yii. Just remember that if you want your layout file, use render(). If not, use renderPartial(). If you need to pass data to the View file, use the second argument to send along an array, whose indexes will become the names of the variables within the View. Finally, if you need to change the include path, begin with a double slash.

The new Query Builder is an object-oriented way to create custom SQL statements. This isn’t really a new feature (in the sense of allowing you to do something you couldn’t do before) but lets you do something you might commonly do but in a different way. See the above link for a thorough discussion and demonstration.

For some reason, the 1.1.6 release of Yii includes an article on Best MVC Practices. This isn’t really part of the framework itself, but is a useful read for anyone using Yii or other MVC approaches.

Before getting into the code, let’s take a minute to think about the MVC architecture. A form itself is found in the View, as a form is part of the user interface. More specifically, when Yii auto-generates a form as part of CRUD creation, the framework writes the form in a file named _form.php. This file in turn gets included by other View files (any View file in Yii that starts with an underscore is intended to be an include). Also understand that the same _form.php file is intended to be used whether the form is for creating new records or updating existing ones. Naturally, the Controller dictates which primary View file gets rendered.

Forms, though, are associated with specific Models. A contact form may have its own Model, not tied to a database table (in which case the Model extends CFormModel), whereas a form for employees or departments will be based upon a Model that is tied to a database table (in which case the Model extends CActiveRecord, most likely). Whether the Model extends CFormModel or CActiveRecord, the important thing to remember is that the form is tied to a Model. This is significant because it’s the Model that dictates what elements exist, controls validation of the form, and defines the form’s labels (e.g., First Name for the firstName attribute), and so forth.

Tip: There are instances where you might have a form not associated with a Model, but that is rare. The most common such instance would be a search form.

Before getting to the View and its form, let’s be clear as to how the View accesses the specific Model. A Controller may have this code:

public function actionCreate() {

    $model=new Employee;

    /* Code for validation and redirect upon save. */

    // If not saved, render the create View:
    $this->render('create',array(
        'model'=>$model, // Model is passed to create.php View!
    ));
}

The create.php View file will include _form.php, passing along the Model instance in the process:

<?php echo $this->renderPartial('_form', array('model'=>$model)); ?>

So now _form.php has access to the Model instance and can create the form tied to that Model.

Of course, to be fair, you could create an HTML form using raw HTML, without Yii at all. The downside to that approach is it creates no tie-in between the Model’s validation rules, errors, labels, etc., and the form. By creating the form using Yii, labels will be based upon the Model definitions (meaning that changing just the Model changes reference to attributes everywhere), invalid form values can automatically be highlighted, and much, much more. Plus, it’s not hard to use Yii to create a form, once you understand how.

The older Yii method for creating a form was simply a matter of invoking the appropriate CHtml methods: activeLabel(), activeTextField(), activeDropDownList(), and so forth:

<div class="row">
     <?php echo CHtml::activeLabel($model,'username'); ?>
     <?php echo CHtml::activeTextField($model,'username') ?>
</div>

The CHtml::activeLabel() method creates the label. The other methods create other form elements. Each method takes the Model involved as its first argument and the Model’s corresponding attribute as its second, thereby tying the form to the Model.

And here’s another reason to use Yii’s system of creating forms: if the form is being used for an update, the values will automatically be prepopulated/pre-selected/pre-checked based upon the existing Model! As you should know, that alone requires a lot of code and logic.

As of Yii 1.1.1, forms can be created using the CActiveForm widget. Among other benefits, CActiveForm is capable of enabling client-side form validation using Ajax. You always start by invoking beginWidget():

$form = $this->beginWidget('CActiveForm');

(This code goes in the _form.php file.) Now $form is an object of the CActiveForm widget type and it can be used to generate the form itself:

<div>
    <?php echo $form->labelEx($model,'firstName'); ?>
    <?php echo $form->textField($model,'firstName',array('size'=>20,'maxlength'=>20)); ?>
    <?php echo $form->error($model,'firstName'); ?>
</div>

You’ll see that whereas CHtml has the activeTextField() method, CActiveForm has just textField(). The same goes for activeLabel() becoming just labelEx(). You’ll see this pattern—dropping the active part—repeated. Still, the Model is passed as the first argument and the attribute involved as the second.

Returning to the widget itself, you can customize the behavior of the form by passing an array of values when creating it:

<?php $form = $this->beginWidget('CActiveForm', array(
    'id'=>'user-form',
    'enableAjaxValidation'=>true,
    'focus'=>array($model,'firstName'),
)); ?>

Note: I’ll address Ajax form validation in a separate post.

The various CActiveForm properties can be found in the documentation. Commonly you won’t need to customize any properties, but you can change the form’s method and action attributes, or add additional HTML to the opening form tag.

Finally, the form needs a submit button. Unlike the other form elements, this isn’t tied to a Model; it is created with just the CHtml class:

<div>
    <?php echo CHtml::submitButton($model->isNewRecord ? 'Create' : 'Save'); ?>
</div>

The submitButton()‘s argument is the textual label for the button.

Then the form is closed by “ending” the widget:

<?php $this->endWidget(); ?>

So those are the basics for using CActiveForm. Once you’ve taken the above steps, form elements will be prepopulated when updating a record, errors will be clearly indicated upon form submission, and so forth.

The most important information involves creating the form elements. For the most part, doing so is simple and direct, as shown in the above. By associating the Model instance with the form, Yii will do the rest. Sometimes you’ll need to customize the look and behavior of an element. I’ve discussed this in many separate posts, which I’d recommend you read:

• Handling Related Models in Yii Forms
• Handling Checkboxes in Yii with non-Boolean Values
• Configuring FCKEditor for Yii-Driven Sites

And my Basic View Edits post, part of my Learning the Yii Framework series, demonstrates how to use CHtml::listData() to populate a drop down menu. I’ll no doubt post more threads particular to forms in Yii, as its such a critical topic. Potential subjects include: Ajax validation and handling file uploads.

In a separate post, I’ll talk about Form Builder, added to Yii in version 1.1.0. It allows you to create forms in a different way, primarily in the Controller (not unlike using the PEAR HTML_QuickForm class).