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.

My solution was to show the list of questions by number and, when the admin clicks on a specific question, they’d see a preview of that question’s prompt (i.e., the HTML) in a separate interface. Now I’ve got three areas in my UI: one for adding or editing the other quiz attributes, one for listing every question, and a third for displaying the particulars of a single question. Given all this, I thought having the admin drag the questions from one area to another would be the best way to associate a question with a quiz. I could have done all this using jQuery (the JavaScript framework Yii uses by default), but that would have taken me days to figure out how to use jQuery in this way. On the other hand, I knew I could develop this using Flex (a framework for creating Flash applications) in no time. I just didn’t know how to get Yii and Flash to play ball. It turns out not to be that hard…

From a client-server perspective, the application required three services:

• The client fetches a list of questions from the server.
• The client fetches a list of quizzes from the server (so that the user can update existing quizzes).
• The client sends to the server a quiz-questions combination to be stored in the database.

To keep things relatively simple, I decided to go with basic HTTPService calls rather than AMF (Action Message Format). AMF is better and preferred in many ways, but it introduces some logistical issues I wasn’t prepared to deal with yet. So the first thing I had to do was create Controller and View code for returning lists of information (the Models were already defined and, as should be the case, were untouched by this new functionality). In my QuestionController file, I created this method:

public function actionXml() {
    $this->renderPartial('xml', array('models'=>Question::model()->findAll()));
}

All this function does is render the xml View, passing to it all of the Question Models. The View itself has to output XML data. For that reason, I use renderPartial() instead of render(), as I just want the individual View file to be rendered without the rest of the layout (i.e., without all the HTML, CSS, and JavaScript). I’ve seen some examples online where people just outputted the XML from within the Controller, but you really shouldn’t do that as it breaks the MVC architecture.

The xml.php View file looks like this:

<?php header("Content-Type: text/xml");
echo '<?xml version="1.0" encoding="utf-8" ?>'; ?>
<questions>
<?php foreach ($models as $model):?>
    <question>
        <id><?php echo $model->id; ?></id>
        <prompt><![CDATA[<?php echo $model->prompt; ?>]]</prompt>
        <answer1><?php echo $model->answer1; ?></answer1>
    </question>
<?php endforeach; ?>
</questions>

The first line sends a Content-Type header to tell the client that the content is XML. Then the XML declaration is printed. Then the opening root tag is created, called questions. Next a foreach loop goes through each received Model. Within the loop I print whatever content needs to be sent to the client. This would be the question’s ID, its prompt, its possibly answers, etc. If the content might include any characters that are problematic in XML, including the ampersand, I would use this syntax, as in the prompt value:

<something><![CDATA[<?php echo $model->something; ?>]]></something>

The CDATA tags prevent text from being parsed as XML, thereby preventing problems with certain characters.

After I wrote this code for both of the services (the XML for the quizzes is quite similar), I tested the services in my Web browser by just going to http://hostname/question/xml and http://hostname/quiz/xml. By using a browser that understands XML, I can see the proper output before attempting to use my Flash client to connect to the service.

For the third service, data will be posted to the Yii-based site. In my QuizController file, I created a new method for this:

public function actionFlash() {
}

What this method really does is the same thing as the auto-generated actionUpdate() and actionCreate() methods, but some of the code will be different based upon how I’m sending data here from the Flash client, so I decided to create a new method instead. All this method needs to do is receive the data, associate it with a Quiz Model, then save the Model and report upon the results. One complication, however, is that when Yii creates a form for a Model, it’ll use names such as Quiz['prompt']. I didn’t know of an easy way to accomplish this when sending the data from Flash, so I just modified how the creation and updating happens. The first thing the method does is confirm that all of the values are received. In this hypothetical example, the values should be a quiz ID, a quiz name, and a list of questions associated with that quiz. So the method starts off with:

if (isset($_POST['id'], $_POST['name'], $_POST['questions'])) {

Next, the method checks if this is a new quiz (the Flash application allows for the creation of new quizzes) or an existing one. A new Model variable or existing Model is created depending upon this:

if ($_POST['id'] == 0) {
    $model=new Quiz;
} else {
    $model=Quiz::model()->findbyPk($_POST['id']);
}

Next, associate the incoming quiz name with the Model:

$model->name = $_POST['name'];

You would do this for any Model attribute that might have changed or be created for the first time. When using just Yii, the equivalent takes place using the Model’s attributes:

$model->attributes=$_POST['Quiz']; // Or whatever Model.

Then you save the Model:

if ($model->save()) {

This line will only work if all of the Model’s rules (i.e., its validations) are passed, so you don’t have to worry about invalid data getting into the system. Still, validation in the Flash client is a good idea, too.

The rest of the method just echo’s out messages based upon what happened:

• The quiz has been created.
• The quiz has been updated.
• The quiz could not be updated because of invalid data.
• And so forth.

There’s a bit more code in it as I the database has a QuizzesQuestions table which acts as an intermediary for the many-to-many relationship between the quizzes and the questions. (If you want to see the whole method, let me know.) This service, when called from the Flash client, will return a plain text message, which is why I just have the method echo out simple messages. Technically this also breaks the MVC architecture, but I didn’t feel like creating a new file that just said The quiz has been created.

At this point I’ve created three Controller methods that send and receive the necessary data. Next up, I created the Flash client using the Flex framework and the Flash Builder IDE. The client interface was pretty basic Flex stuff. I created a DataGrid for displaying the quizzes. When a quiz is selected in the DataGrid, its particulars are displayed and become editable in a form. The form includes a List into which questions can be dropped. The existing questions are displayed in a separate List. When a question is selected in that List, its particulars are displayed in a separate Panel.

When the application first loads, the two XML services are called to populate the quiz DataGrid and the questions List. When the quiz form Button is clicked, the actionFlash() service is invoked, saving or creating the quiz accordingly. (The Flex side of this only took me an afternoon to complete, by the way.)

The most interesting thing about all this was tapping into Yii’s access control rules. The way the entire Web site is written, only logged-in administrators can do things such as create or update quizzes. So how do I ensure that only logged-in administrators can use the Flash application? Tapping into Yii’s authentication from Flash isn’t easy but it turns out not to be necessary. To start, in the QuizController file, I restrict access to the Flash application’s View file to only logged-in administrators. This, though, does not prevent the Flash application from doing anything (in theory, someone could load the Flash application separately, if they knew of its existence). What I do as well is restrict access to the XML and Flash actions (in the appropriate Controller files) to only logged-in administrators. This will also automatically prevent the Flash application, if being run by a non-administrator somehow, from accessing those services. Here’s why this works: the Flash application is running within a Yii-based page, so any request that the Flash application makes is the same as any request the browser itself makes (this is also true for Ajax requests). So Yii-related cookies that are stored in the browser after the user logs in are also passed along as part of the request. Tada! By just using the access control rules in the Controller, the Flash application can only invoke those services if the user is logged in as an administrator. Very simple! The only catch was that when developing the Flex application in Flash Builder, I wouldn’t be running and testing the Flash application as a logged-in administrator, so I had to make the Controller’s actions public during that time.

So there’s that experience, then! I was pleased with how easy this was to pull off (i.e., I was pleased how little thinking I had to do to make this work) and my client was pleased with the result. I hope this helps you in your Flash+Yii projects. Thanks for reading and please let me know if you have any questions or comments.

• SHOW COLUMNS FROM tablename
• SHOW CREATE TABLE tablename

Again, to be clear, any use of, say, an Employees table requires these two commands be run first. If you have the related Employee and Department Models, a join across them requires four queries before any data is retrieved at all! And this is the downside of ActiveRecord: it does a lot of the work for you, but at a cost of performance. The hardest performance hit a Web site has comes from database queries, so minimizing or optimizing those is crucial. You can improve your Yii application’s performance by limiting how often these queries are run. To do so, you’ll need to cache the database schema.

Caching, to be clear, is the process of saving something for later so that it doesn’t need to be regenerated. For example, a dynamic PHP page can be cached as HTML so that the server can just send the static HTML instead of re-executing the PHP (and, most likely, the underlying database queries). Yii supports caching in many ways, from caching specific bits of data to parts of a page to entire pages. One example of data you can cache is the database schema: how the database is defined. By caching that information, Yii won’t have to retrieve it by running two SHOW commands.

Before telling you how to do that, let’s tell Yii to reveal its inner workings to you. First of all, run your application in debugging mode by having these two lines in your index.php bootstrap file:

defined('YII_DEBUG') or define('YII_DEBUG',true);
defined('YII_TRACE_LEVEL') or define('YII_TRACE_LEVEL',3);

Those are written into the file by default but should be commented out or deleted entirely on a live server.

Then, in your protected/config/main.php configuration file, enable the WebLog:

'log'=>array(
    'class'=>'CLogRouter',
    'routes'=>array(
        array(
            'class'=>'CFileLogRoute',
            'levels'=>'error, warning',
        ),
        array(
            'class'=>'CWebLogRoute',
        ),
    ),
),

Now when you access any page in the Web browser, it’ll report a slew of information at the bottom of the screen. This is a log of whatever Yii is doing, from the loading of modules to the execution of database queries. Normally I’d show you an image of this here, but it’d be too revealing for my live sites! In this log, you’ll see the SHOW queries I already mentioned. To stop those from happening (most of the time), you’ll need to first tell Yii to cache the database schema. This is also done in the main.php configuration file, in the section for configuring the “db” component:

'db'=>array(
    'connectionString' => 'mysql:dbname=test',
    'schemaCachingDuration' => 3600,
    'emulatePrepare' => true,
    'username' => 'user',
    'password' => 'pass',
    'charset' => 'utf8',
),

The schemaCachingDuration line needs to be added there. Assign to it a logical value, such as an hour (the value is in seconds, so 60 seconds times 60 minutes equals 3600). That line will enable caching of the database schema but only if Yii has a caching component registered! This is very important: if you follow these steps and don’t see the SHOW commands disappear from the Web trace log, the caching isn’t working.

To enable a cache, register a “cache” component (like “db”, this is also in the “components” section of the main.php configuration file):

'cache' => array (
    'class' => 'CMemCache'
),

The class value indicates which kind of cache you want to use. Options include CMemCache (memcached), CApcCache (APC), and CDbCache (which uses SQLite). A small book could be written about each cache type and how to get the most of them. For me, I went with memcached, which is a tool for storing data in memory. So I added this to my configuration file:

'cache' => array (
    'class' => 'CMemCache',
    'servers'=>array(
        array(
            'host'=>'localhost',
            'port'=>11211,
        ),
    ),
),

Like connecting to a database, I specify a host and a port. To connect to memcached on the same computer, I use “localhost” and 11211 as the port (this is the standard). Once I’ve done this, if I re-run my Yii application, the SHOW queries will disappear (on the second request, because the first has to retrieve the data so that it can be cached).

So if you follow these steps, you can have Yii show you what it’s doing, then make some of that activity go away, but what does this mean in real-world performance? To test that, I turned to ApacheBench, a command-line benchmarking tool. Assuming you have ApacheBench installed on your computer, you can use it with the command (note that you’re testing some other server from your computer):

ab -n # -c # http://www.example.com

The -n flag indicates the number of requests to make. The -c flag indicates the number of concurrent requests to make. This is great because no matter how fast you are with your browser, you can’t single handedly make multiple simultaneous requests of a server. You can also indicate a timelimit, send POST data along with each request, and so forth. As a basic test, I can see the results of my site for 100 requests in groups of 5:

ab -n 100 -c 5 http://www.example.com

You’ll get a bunch of information back, after a few seconds or minutes. You’ll see the number of complete and failed requests, which is nice, but the requests per second (RPS) is the most common benchmark for a site’s performance. In other words, this server can handle X number of requests for this URL per second. The more RPS, the better: it’s that simple.

There are a couple last tips to add, as these things can be confusing. First, memcached is the caching software that needs to be installed and running on the server. Second, PHP must be configured with support for memcache (no “d”), which is PHP’s extension for working with memcached. And, of course, memcached must be running. When I first tried to enable this (using Mac OS X Server), I wasn’t seeing any caching taking place, nor any error messages. So my next step was to use an example from the PHP manual to test PHP-memcache-memcached outside of Yii. That example indicated that PHP wasn’t able to connect to memcached. It turns out the reason was that the server didn’t have memcached installed! Once I installed and started memcached, I got the results I wanted.

Hopefully this will help you improve the performance of your Yii applications, too! Thanks for reading and let me know if you have any questions or comments.

Larry

Many generous readers have provided their ideas and feedback in a forum thread and an earlier blog post. I’ve taken all of those opinions, plus my own thoughts, to come up with this first draft. The content (in terms of what I’m going to write about) is maybe 90% settled and the order of the chapters is about that, too. Many of the specifics, especially when it comes to chapter and section headings will most likely change. Hopefully it should be clear from the table of contents what the intentions are, but just in case…

The book is broken down into four parts. In the first part, which is just two chapters long, I talk about the fundamentals that will apply to any e-commerce project you take on. This starts with planning, choosing a host, development tools, etc. Security as a theory gets its own chapter and security will be hammered in throughout the entire book. But that security chapter covers the bigger picture and some gritty details with respect to choices that have big impacts (such as hosting).

In the second part of the book, I’ll walk through a complete e-commerce project, from HTML and database design to user management to handling payments through PayPal. There are three points to this first example:

1. Understanding the basics in terms of design and the development process
2. Knowing how to perform user management and access control
3. Handling payments with a simple gateway like PayPal

This e-commerce project would be digital/virtual content. The specific example would be a subscription access to the site (like what ConsumerReports.org does) but it could also be PDFs that you sell or licenses for software or whatever. Anything that doesn’t have a limited quantity to be sold or that needs to be shipped. I’ll be using PayPal because it’s far and away the most common payment system, even if not everyone likes it. Google’s payment gateway would be comparable.

In the third part of the book, I’ll cover a second complete e-commerce project. This one will be a lot more complicated, with the focus on:

• Creating a product catalog
• Creating a shopping cart
• A multi-step checkout process, including shipping
• A credit card payment gateway
• Order and catalog administration

This example wouldn’t specifically require user registration and logging in, but you could take the information taught in the second part to enable that feature here. I’ll try to make the thing being sold reasonably diverse (a range of products, not just a single thing).

The fourth part of the book will be add-ons and improvements. This is also the “if I have the space” section, which is to say that I’ll write about as much of this extra stuff as I have the available pages. I’ve organized these chapters in terms of most universally useful, starting with a search engine and then going into marketing. There’s a lot of possible topics in the marketing section, from SEO, to product recommendations and reviews, to analytics. Next up is a chapter on using Ajax to improve the user experience. There should be room for those three chapters in the printed edition of the book.

The final three chapters, in this rough table of contents, are definitely “if there’s space”. If not, I’ll write about them in this blog. Instead of offering entirely new concepts, the last three chapters would be alternative ways to do things you’ve already seen to that point: expanding the depth of the content, not its breadth. First up would be other gateways, as that’s a vital part of the process and there are many good options out there. Next would be a chapter on Object-Oriented Programming (OOP), in which I rewrite some of the book’s code using OOP. Many people really want to see OOP in the book, many absolutely don’t, so as a middle ground my theory is to add an OOP chapter that translates procedural code in an understandable way. The final chapter, which I’ll admit there probably won’t be room for, would present alternative database schemas for other kinds of e-commerce applications.

All that being said, here’s the current rough table of contents. I welcome all comments, questions, and thoughts!

• Introduction

———————

Part 1: Fundamentals

• Chapter 1: Getting Started
  • Identifying Your Business Goals
  • Legal/Business Issues
  • Choosing Web Technologies
  • Getting a Host
  • Development Tools
  • The Development Process
• Chapter 2: Security Fundamentals
  • Hosting Implications
  • Payment Considerations
  • Secure Transactions
  • Protecting Information

———————


Part 2: The Digital Content Example (Rename)

• Chapter 3: Site Structure and Design
  • HTML
  • Server Organization
  • Database Design
• Chapter 4: Handling Payments with PayPal
• Chapter 5: User Management
  • Registration
  • Login
  • Access Control
  • Updating Accounts

———————


Part 3: The Physical Content Example (Rename)

• Chapter 6: Site Structure and Design 2
  • HTML
  • Server Organization
  • Database Design
• Chapter 7: Creating a Catalog
  • Browsing by category
  • Highlighting new products
  • Creating Sales and Discounts
• Chapter 8: Starting Orders
  • Creating a Shopping Cart
  • Shopping Cart Managment
  • Shipping
  • Finalizing Purchases
• Chapter 9: Checking Out
  • Credit Card Payment Gateway
  • Storing Orders
  • Email Status/Receipts
  • Checking Order Status Online
• Chapter 10: Administration
  • Authentication
  • Stock Management
  • Reports/Graphs

———————


Part 4: Extra Touches

• Chapter 11: Building a Search Engine
• Chapter 12: Marketing
  • Search Engine Optimization
  • Adding Ads
  • Product Recommendations
  • Notify when product is available
  • Reviews
  • Newsletters
  • Customer Help
  • Tracking referrers/Analytics
• Chapter 13: Adding Ajax
  • cart management in sidebar
  • comments/reviews
  • ratings
  • purchasing
• Chapter 14: Alternative Gateways
• Chapter 15: Using OOP
• Chapter 16: Alternative Database Schemas

After you’ve downloaded the code and put it on your server, you use it like so:

require('/path/to/EmailAddressValidator.php');
$emailValidator = new EmailAddressValidator();
if ($emailValidator->check_email_address('test@example.org')) {
    // Email address is technically valid.
} else {
    // Email not valid.
}

As a person that wrote a book on PHP 6 quite some time ago, and has looked more and more silly over time, I’m happy to hear this news, even if we don’t yet know what the end result will be. Granted, most of that book uses PHP 5 and PHP 6 (the version that was available when I wrote it) is only required by like 5-10% of the material, but still…lesson learned on my part: especially when it comes to open source software, there’s just no predicting what’s going to happen next. So, for the time being, let’s be happy with the PHP we have and keep an eye on where the development team goes with this. I know I sure will!