To be clear, layouts are a type of View file. Specifically, whereas other View files get placed within a directory for the corresponding Controller (i.e., the SiteController pulls from views/site), layout files go within views/layouts. But while the other View files are associated with individual Controllers (and therefore, individual pages), layouts are communal, shared by all the pages. Simply put, a layout file is the parent wrapper for the entire site’s templating system. I’ll explain…

The Premise of Templates

When you begin creating dynamic Web sites using PHP, you’ll quickly recognize that many parts of an HTML page will be repeated throughout the site. For example, the opening and closing HTML and BODY tags. Even the site you’re looking at now has repeating elements: the header, the navigation, the footer, etc. To create a template system, you would pull all of those common elements out and put them into one (or more) separate files. Then each specific page can include these files around the page-specific content:

include('header.html');
// Add page-specific content.
include('footer.html'); 

This is the approach I would use on non-framework-based sites. It’s easy to generate and maintain. If you need to change the header for the entire site, you only need to edit the one file.

Templates in Yii

When using a framework, you’ll probably end up with a “bootstrap” approach, where all of the pages are accessed through one file. In the case of Yii, that bootstrap file is index.php. Part of its job is to manufacture the necessary HTML for the requested resource. Whereas the non-framework approach pulls the template files into the page-specific file, Yii pulls all the files from includes and assembles them together. Of these files, the layout files constitute all the common elements; everything that’s not page-specific. If you look at a Yii-generated site, you’ll see that views/layouts/main.php begins with the DOCTYPE and opening HTML tag, then has the HTML HEAD and all its jazz, then starts the BODY, and finally has the footer material and the closing tags. In the middle of the body of the code, you’ll see this line:

<!--?php echo $content; ?-->

This is a magic line as it pulls in the page-specific content. If the site you’re looking at now used Yii, the value of $content would be all the HTML that makes up this post you’re reading. For a Yii example, when the user is looking at site/login, the SiteController‘s actionLogin() method will be called. That method will render the views/site/login.php View page, pulling that file’s contents into the main layout file at that echo $content location. That’s what’s going on behind the scenes.

So here, then, is the first key concept: if you want to change the general look of your Web site, edit the layout file (views/layouts/main.php). If you were to take your HTML mockup for your site, drop in the echo $content; line at the right place, and save it as views/layout/main.php, you will have created a custom look for your Web app. That is the basic principle and it’s essentially that simple.

To take layouts a step further, many sites will use variations on a theme. For example, the first Yii-based site I created used one header for the home page and another header for other pages, with all the remaining common elements being consistent. Or, I worked on an e-commerce project where one category of products used layout A and another category used layout B. If you have this need, there are a couple of ways of going about it.

Creating a Second Layout

The first and most obvious route is to create a second layout file. In the example where the site’s home page used a variation on the template, I created views/layouts/home.php. It was based upon main.php, with the necessary edits. To dynamically switch layouts, I changed the value assigned to the layout property within the proper Controller method:

// protected/controllers/SiteController.php
public function actionIndex() {
    $this->layout = 'home';

And that’s all there is to it. When views/site/index.php would be rendered, it’d use the views/layouts/home.php template.

Although this approach is easy to understand and implement, it has a downside: a LOT of HTML is being repeated between the two layout files. If I needed to change the navigation, I had to edit both files in the same way. This leads us to option B.

Hijacking the Content

More recent versions of Yii will automatically create three layout files when you create a new Web app:

• views/layouts/column1.php
• views/layouts/column2.php
• views/layouts/main.php

Although all three are layout files, you don’t have three different template files. The main.php file still creates the DOCTYPE and HTML and HEAD and so forth. The column1.php and column2.php files simply create variations on how the page-specific content gets rendered. These files do so by hijacking the layout process. For example, here is the entirety of column1.php:

<!--?php $this--->beginContent('//layouts/main'); ?></pre>
<div id="content"></div>
<pre>
<!-- content -->
<!--?php $this--->endContent(); ?>

Again, you have the magic echo $content line there, but all column1.php does is wrap the page-specific content in a DIV.

The column2.php file starts off the same, but adds another DIV (which includes some widgets) before $this->endContent():

<!--?php $this--->beginContent('//layouts/main'); ?></pre>
<div class="span-19">
<div id="content"></div>
<!-- content --></div>
<div class="span-5 last">
<div id="sidebar"><!--?php  $this--->beginWidget('zii.widgets.CPortlet', array(
 'title'=>'Operations',
 ));
 $this->widget('zii.widgets.CMenu', array(
 'items'=>$this->menu,
 'htmlOptions'=>array('class'=>'operations'),
 ));
 $this->endWidget();
 ?></div>
<!-- sidebar --></div>
<pre>
<!--?php $this--->endContent(); ?>

The trick here is the call to beginContent(). Remember how the layout file echoes the page-specific content in the correct place? Well, this call to beginContent() says that we’re about to start rendering the content. The method is provided with the primary layout file to use as the parent (i.e., the layout that encapsulates this content). All that’s happened here is that the content has been hijacked and replaced with slightly modified content. So the content in views/site/login.php gets pulled into column.php, where it’s wrapped within other content, and the combination of that content gets passed to main.php.

There are two tricks to this: first, beginContent() must point to //layouts/main.php. (The // just says to start in the Views directory.) Second, the layout that the Controller thinks it’s using is column1.php, not main.php. I personally think this approach is a bit complicated, particularly for the Yii newbie (yiibie?), but it is useful in situations where the content around the page-specific content needs to be adjusted dynamically.

If you were to open components/Controller.php, you would see this line:

public $layout='//layouts/column1';

That one line says that all Controllers (which inherit from Controller) will use column1.php as its layout. If you were to change this one line to column2, then all Controllers would use that as the default layout. If you were to change this one line to main, then all Controllers would use main.php as the default layout, without the intermediary column layouts.

Again, this is a bit more convoluted than is healthy for newbies, but layouts are just wrappers to page-specific content, whether you use a single layout or intermediary layouts such as column1 and column2. If you’d like a visual representation, there’s a useful image provided among the comments in this article.

Quick Guide

To summarize what’s been covered here…

To change the entire look for the entire site, edit layouts/main.php, but be sure to use the echo $content line where appropriate.

To change the default layout for every Controller, edit this line in components/Controller.php:

public $layout='//layouts/column1';

To change the default layout for every View in an individual Controller, add this line to that Controller’s definition:

class SiteController extends Controller {
public $layout = 'column2';

To change the layout used for a single action, add this line to the corresponding action:

// protected/controllers/SiteController.php
public function actionIndex() {
    $this->layout = 'home';

And remember that column1.php and column2.php just hijack the page-specific content before it gets passed on to the main.php layout file.

I hope this post has been helpful and let me know if you have any questions or problems with layouts in Yii. (And by the way, if you like this post, I’m going to be writing a book on Yii later this summer. Subscribe to my newsletter or follow me on Twitter to stay tuned!)

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 “feel” 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.