Saturday, April 10, 2010

Preparing a WAMP stack for Yii development - Part 2 of 2

If you don't have a working WAMP stack yet, you'll need to start with Part 1 of the tutorial. This continuation will walk through the process of installing the Yii Framework on your server and creating your first application.

First you need to download the Yii Framework itself from here: http://www.yiiframework.com/download/. I recommend getting the latest stable version. Once you've got the Yii Framework zip file you'll need to extract its contained files somewhere in close proximity to your Apache server's DocumentRoot directory. I wouldn't recommend leaving the Yii files inside your DocumentRoot, since Apache will never need to serve them up directly, but for the sake of simplicity I will put them there. In a production environment you would want to move them to a location not visible to Apache for security reasons.

Since my DocumentRoot is C:\yiiprojects\testproject I extracted the zip files into C:\yiiprojects\testproject, resulting in everything being placed in a folder at C:\yiiprojects\testproject\yii-1.1.0.r1700. The folder in the zip will be named based on your version, so if you get a different version of Yii it will be named slightly differently. For simplicity I renamed the extracted Yii framework folder from "yii-1.1.0.r1700" to "yii", so it now resides at C:\yiiprojects\testproject\yii. Inside the yii folder there are several folders -- demos, framework, requirements -- as well as the Yii LICENSE and README files among others. As you might have guessed the actual Yii php framework files reside in the framework folder and some demo applications exist in the demos folder.

The C:\yiiprojects\testproject\yii\requirements folder contains a script that will test if your system meets the Yii requirements. Since we've extracted these files inside of our DocumentRoot we can execute the requirement testing script by navigating to: http://localhost/yii/requirements/index.php

You should see something like the following if everything from the previous steps is working correctly:


You'll need to address any failures, but the warnings in the screenshot above are not critical.

Now that we've confirmed the Yii Framework requirements have been met we can create our first application. To do this we open up a command prompt, navigate to C:\yiiprojects\testproject\yii\framework and execute the following commands:

yiic webapp C:\yiiprojects\testproject

It will ask you to confirm whether you wish to create a new application. Type 'Yes' to proceed. It will generate a skeleton application for you in the specified folder.

You can now navigate to http://localhost and you should see a skeleton Yii application.

Next we need to create a database within MySQL for our project. To do this we will return to the command line and log back into MySQL:

mysql -u root -p

After you enter your MySQL root password, you'll need to issue the following command to create a database. I named my database 'myappdb' but you can pick something more appropriate for your application.

CREATE DATABASE myappdb;

Now that we've created our project database we need to configure our Yii application to point to it. To do this we need to edit the main application configuration file, located at C:\yiiprojects\testproject\protected\config\main.php

Here's the relevant section of your application's config/main.php file:

'db'=>array(
  'connectionString' => 'sqlite:protected/data/testdrive.db',
),

By default it is set up for SQLite. We'll need to update this so that it uses our MySQL database. Replace the above 'db' configuration with the following one, replacing the 'dbname' with the database you just created, and 'password' with your root password.

array(

'db'=>array(
    'class'=>'CDbConnection',
    'connectionString'=>'mysql:host=127.0.0.1;dbname=myappdb;port=3306',
    'username'=>'root',
    'password'=>'mysecretpassword',
    'emulatePrepare'=>true,  // needed by some MySQL installations
),

The 'connectionString' value defines your database type, the 'host' points to its location and the 'dbname' is the name of the actual database your application will use.

As you can see, I use '127.0.0.1' instead of 'localhost'. Using 'localhost' is fine in most cases but if that doesn't work for you, try 127.0.0.1 instead. You're not required to specify the port in your 'connectionString' if you use the default of 3306, but I did anyway.

Once you've completed these steps you should be ready to use your MySQL database from within your Yii application. The only thing we're lacking at this point is a table within our database. I'll create a table called 'user' where we can store registered users.

Log back into MySQL from the command line:

mysql -u root -p

After you enter your password, issue the following commands to select the database you created previously and add a new 'user' table to it:

USE myappdb

CREATE TABLE user (user_id int(10) unsigned NOT NULL AUTO_INCREMENT,
  name varchar(200) NOT NULL,
  password varchar(200) NOT NULL,
  PRIMARY KEY (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Now we have a 'user' table in our 'myappdb' database.

We now need to create a Yii Model to represent our user table. Close the MySQL command prompt and open a new command prompt.

Navigate to C:\yiiprojects\testproject\framework and open up the yiic shell:

yiic shell ../../index.php

If you get a PHP error/warning here related to the date() function not having a timezone setting it's because your PHP error settings are not ignoring warnings. We can get around this by opening up our C:\yiiprojects\testproject\index.php file and specifying our timezone at the top. I set mine to 'America/Chicago':

<?php

date_default_timezone_set('America/Chicago');

// change the following paths if necessary
$yii=dirname(__FILE__).'/yii/framework/yii.php';
$config=dirname(__FILE__).'/protected/config/main.php';

// remove the following line when in production mode
defined('YII_DEBUG') or define('YII_DEBUG',true);

require_once($yii);
Yii::createWebApplication($config)->run();

If you try to access the yiic shell again it should work now that we've fixed the warning.

Once we've logged into the yiic shell we can create our User model with the following command:

model User

If successful it should generate three files: models/User.php, fixtures/User.php, and unit/UserTest.php.

The last step is to allow Yii to create some scaffolding for us to generate basic CRUD controllers/views for our new User model:

crud User

This should generate a UserController.php and several views.

To test this we can now navigate to http://localhost/index.php?r=user/create and we will be presented with a form to create a new user.

In most cases we probably don't want to use the CRUD scaffolding, but it can be a good place to start. Take a look at the controller, model and views we just created to get an idea of how the Yii Framework is structured.

This concludes the two part tutorial on setting up a WAMP stack for Yii development. If you haven't yet, make sure you check out the documentation on the Yii site: http://www.yiiframework.com/doc/