In creating my first Yii application, there were a few hurdles and stumbling blocks along the way. One of the first guides/tutorials that a new user to the Yii PHP framework is directed to is the “Creating Your First Yii Application” in the “Definitive Guide to Yii” . This is kind of a companion piece that has extra explanation, plus the first steps I made to start turning the example app into my custom web application.

Stuck in the Quick-Start Guide – Help, I have no command-line access!

Right away in the guide article there is a console command used to run the command line tool yiic. This generates the initial skeleton of a new application. If you’re trying to test out Yii on shared hosting where you do not have command line access, this immediately becomes a stumbling block. I’m not sure why this isn’t using a more user-friendly web-based tool like the model-generator Gii.

So you’re going to want to set up your development environment on your local machine. If you’re running some flavor of Windows, you can set up WAMP, which runs Apache, MySQL, and PHP on your PC. You’ll have a directory such as the default C:wamp that acts like a web server and is accessible through localhost in your browser.

• Download WampServer – Apache, PHP, MySQL on Windows (Free)
• How to Install Yii on WAMP (Yii Wiki)

Ideally you’d want to use a standard workflow where your files move from:

• Development Server – Files on local machine/server
• Staging Server – Private testing server. In my case, this is online as a subdomain that is password protected using .htpasswd
• Live Server – When code is ready on staged, it’s made live

If you’re working directly on a server (a combo development/staging perhaps), then you can run yiic initially on your local machine, and then just upload the files. Or, if you know Yii really well, you can start from scratch and not use yiic at all

Running yiic, First Look and Nicer URLs

My first question after I looked at the example application was, why are the URLs using query strings instead of being SEO and user-friendly? Coming from CodeIgniter, the default segment-based approach made a lot of sense. Enabling this in Yii involves some simple editing on the config file. The code is actually already there, and you just need to uncomment it:

Open up /protected/config/main.php and you will see:

"// uncomment the following to enable URLs in path-format"

See part 2 here for more information: http://www.yiiframework.com/doc/guide/1.1/en/topics.url

Also, the friendly URLs still have the “.php” in them. So, to access Gii in the CRUD part of the quickstart tutorial, you would access:
/testdrive/index.php/gii/
instead of
/testdrive/index.php?r=gii

Hiding the index.php is explained in the above guide link.

Enabling your MySQL Database

For my application, I plan on using a MySQL database, so I uncommented that part of the /protected/config/main.php file. The Yii docs tell me to then run /protected/data/schema.mysql.sql.

For those unfamiliar with using WAMP, you can run the SQL file by left clicking on the WAMP icon in your Windows notification area, and choosing MySQL console. You can execute an SQL script file using the source command. If you try the source command right away you’ll get an error:

error 1046 no database selected
error 1046 no database selected
error 1046 no database selected
*Beep beep beep*

If you look at the SQL file, you’ll see this is because it’s only creating a user table and inserting some rows. We need to create a MySQL database first, using the following commands. Include the semicolon below:

database testdrive;
use testdrive;

Now to use the source command. You can copy and paste into your console window. If you right click at the top of the CMD window, you can choose Edit -> Paste.

source C:wampwwwtestdriveprotecteddataschema.mysql.sql

Now your testing MySQL database is all set up.

• More info about creating the MySQL database on the command line
• MySQL Source Command

Gii Generator – Now you’re speaking my language

This is by far the coolest part of setting up Yii that will save you tons of time, especially in prototyping an application. The Gii web interface generates models based on what fields are in your database. It can then generate the CRUD (create, read, update, delete) controllers and views with form fields.

• Watch a video of Gii in action here (Vimeo)

So before you run Gii, try creating your website’s necessary database tables and fields first. Then run the Gii tool to generate the model and CRUD. I did not have a problem with the guides instructions, so just follow those.

My front, My back, My Directories and my App

The first thing I wanted to do was to separate the backend and frontend portions of the site. The backend was only to be accessibly by administrators, and the front-end by registered users.

• I followed this wiki article about how to organize files for a back-end and front-end

Initially I copied the same controllers and views in both areas. Note that you can keep the same models for the frontend and backend. This is helpful because you are working with the same data. You can always set different validation rules in the model scenarios. If necessary, you can use different models as well. I kept my models under the front-end section, though you may organize it differently.

After separating the two areas of the site, I went ahead and removed controllers and views from the frontend that were not necessary. For controllers that I was keeping and modifying on the frontend, I first went ahead and removed priviledges and functions from the controllers that would only be in the backend (such as delete).

Creating a new Frontend HTML/CSS Layout

My next step was to get rid of the default HTML/CSS and build out part of my home page. The visual part of a Yii site is broken up into.

• Views – The content/data displayed. Data is passed to them from your controller
• Layouts – HTML structure where the view content is placed. Widgets can be used here.
• Themes – Don’t worry about this yet. This is for creating a completely separate look for the site.

I edited the /views/layouts/main.php to have my new HTML structure. I used the HTML5 boilerplate as a starting point, which did not take very long to integrate with the Yii setup for directories and content.

• View an example of my HTML5 Boilerplate main.php template code (txt)

What about column1.php and column2.php in the generated example?

This was a little confusing at first. Basically, column1.php and column2.php are sub-layouts. If you open up column2.php, you will see beginContent and endContent being called within the main layout. In the main layout, the $content variable is echo’d, which contains the view in your controller.

You will find that your controller defines the layout view in a variable:

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

You may also want to make note of the default layout for the frontend and backend. This is defined in ../components/Controller.php

So, for example, at one point I wanted a completely different layout in place of main.php for the home page. I actionIndex I changed the layout variable before using the render method:

$this->layout = 'home';
$this->render('index');

Piece by Piece

I hope these setup tips helping you with setting up your new Yii application. If you haven’t yet, I suggest reading up about “relational rules” in your model. They let you define linked tables and relationships between models using HAS_ONE, HAS_MANY, etc.

As I am developing a user-driven site using Yii, I have been documenting questions that were not so easily answered. In my next blog post I’ll list around 10 issues I came across and how to solve them:

• 10 Yii Framework and MVC “Beginner” Questions & Problems Solved