Getting Started with the Yii Framework

October 31, 2009 — 144 Comments
The Yii Book If you like my writing on the Yii framework, you'll love "The Yii Book"!
This entry is part 2 of 8 in the series Learning the Yii Framework

Many, many moons ago I wrote a post introducing the Yii framework. It’s a framework for creating Web applications using PHP 5 (or greater) that I’ve really liked since I originally started with it. Ruby on Rails was the first Web development framework I personally used (back in 2005) and Zend was the first PHP framework. I love the former, and Yii is quite like it in many ways, but I never really took to Zend. In that first post, I discussed just downloading and testing Yii; here I’ll walk through creating the beginnings of a Web application.

(Note: In October 2010, I’ve updated this entire series to reflect changes in Yii since this series was written, and to take into account feedback provided through the comments. Some outdated material will be crossed out, but left in to reflect how things have changed since the series was begun in June 2009.)

For the specific example, I’ll use an employees-departments Web application, with a list of departments and a list of employees, each employee being in only one department. This is a classic go-to example, as it’s easy to understand, practical, uses more than one database table, and is extensible in many ways. To start, though, you’ll use the command-line Yii tools to create the application’s frame. If you’ll be putting the site on a server that you do not have command-line access to, then you should install a complete Web server (Apache, PHP, MySQL, etc.) on your computer, run through these steps, then upload the finished project once you’ve completed it. If you don’t already have a Web server on your computer, I’d recommend using XAMPP (for Windows) or MAMP (for Mac), both of which are free and extremely easy to use.

The first thing you’ll need to do is make sure you have the latest version of the Yii framework. My first post discusses how to get it. Then you’ll want to put the framework folder in a logical location on the server. You don’t need to put it within the Web directory (arguably, you shouldn’t) but nearby, like in the directory below makes the most sense. For example, on my setup, the htdocs folder is the Web root, which is to say that http://www.example.com points there.

My directory structure.

My directory structure.

Tip: If you’re going to be using Yii for multiple sites on the same server, place the framework folder in a logical directory relative to every site. That way, when you update the framework, you’ll only need to replace the files in one place.

Next, you’ll need to get yourself into a command-line environment, like a DOS window/console on Windows or the Terminal application on Mac OS X (and some versions of Linux). Then move yourself into the framework directory. On my server, this means executing this line:

cd /Users/larryullman/Sites/YiiBlogSite/framework

You’ll need to change the particulars to match your setup.

The next step is to tell the yiic application, found in the framework folder, to create a new site. The syntax is

yiic webapp path/to/directory

But before you even begin to use this command, let me explain it a bit, as it’s very important and can be complicated. The yiic file is an executable that runs using the computer’s command-line PHP and that really just invokes the yiic.php script. You may be able to call it using just yiic or using ./yiic (i.e., run the yiic command found in the current directory). Or you can more explicitly call either script using php yiic or php yiic.php. Or you may need to indicate the PHP executable to be used: C:\php\php.exe yiic. You should try the variations on this command, as applicable to your computer, just to make sure you can invoke yiic, prior to trying to create the Web application.

Besides properly executing the yiic script, another gotcha can arise if you have more than one version of PHP installed on your computer. To confirm the version being used, run php -v (again, you may need to provide the full path to the PHP executable). On Mac OS X and Unix, you can use which php to reveal the PHP executable being used by the command php. These steps can help solve confusing problems. For example, on my Mac, I use MAMP Pro for PHP and MySQL Web development, but when I execute PHP through the command-line, I’ll actually be invoking the PHP installed with the operating system. This can be a problem, as the different versions of PHP may or may not meet the Yii requirements outlined in my first post. I know when I first tried this, the command-line PHP (installed with the OS) did not support the required PDO extension, even though the Web version of PHP (in MAMP Pro) did. My solution was to explicitly name my MAMP PHP executable when running yiic: /Applications/MAMP/bin/php5.3/bin/php yiic.

Once you know you’ve figured out the proper syntax for invoking yiic, you follow that by webapp, which is the command for “create a new Web application”. Follow this with the path to the Web application itself. Given the directory structure already indicated (in the above figure), the command would be just

./yiic webapp ../htdocs

or

php yiic webapp ../htdocs

Or whatever variation on that you need to use.

You’ll be prompted to confirm that you want create a Web application in the given directory. Enter Y (or Yes) and press Return. After lots of lines of responses, you should see a message saying that the application has successfully been created. To confirm this, load the site in your browser (by going through a URL, of course):

The Basic Yii Application

The Auto-Generated, Basic Yii Application

As for functionality, the generated application already includes:

  • a home page with further instructions
  • a contact form, complete with CAPTCHA
  • a login form
  • the ability to greet a logged-in user by name
  • logout functionality

It’s a very nice start to an application, especially considering you haven’t written a line of code yet. Do note that the contact form will only work once you’ve edited the configuration to provide your email address. For the login, you can use either (username/password): demo/demo or admin/admin. Lastly, the exact look of the application may differ from one version of the Yii framework to another.

In terms of files on the server, within the application directory (htdocs, for me), you’ll find:

  • assets
  • css
  • images
  • index-test.php
  • index.php
  • protected
  • themes

The assets folder will be used by the Yii framework primarily for jQuery (the JavaScript framework) integration. The css and images folders are obvious. The entire site will also be run through one of the two index files (more on this in the next post). The protected folder is actually the most important one: you’ll edit code found in that folder to change the look and behavior of the site. And themes allows you to create variations on the site’s template, just like themes in a WordPress blog.

Tip: The assets folder must be writable by the Web server or else odd errors will occur. This shouldn’t be a problem unless you transfer a Yii site from one server to another and the permissions aren’t correct after the move.

So that’s the start of a Yii-based Web application. For every site you create using Yii, you’ll likely go through these steps. In the next post, I’ll start demonstrating how you can configure the application, and alter it for an employees-departments example.

As always, thanks for your interest in what I have to say and please let me know if you have any questions or comments.

Larry

If you enjoyed this post, then please consider following me using your favorite social media, the RSS feed, and/or by subscribing to my newsletter. Or go crazy, and buy one or more of my books . Thanks!

144 responses to Getting Started with the Yii Framework

  1. I have got everything works perfectly on my Ubuntu 12.04, a little configure for the url to work is needed. Thanks a bunch.

  2. when i am trying to invoke the command yiic its showing an error php.exe is not recognized as internal or external command

    • Hi soumen,
      you do not specify which OS are you using. I assume windows?

    • Go to your System Properties and include the path where you installed you xammp eg C:\xammp\php by doin so the php.exe error will be solved: to create the frame for your application just open your command prompt and change directory to framework folder where yiic.bat is in it and type eg:
      yiic webapp C:\xampp\htdocs\Yiiapp i.e the folder Yiiapp will b created which z the framework of your application… Hope this will help you out… Yii is the best..

    • invoke php.exe in your local path. ( C:\wamp\bin\php\php5.3.0\php.exe )

      cd yii\framework

      c:\wamp\www\yii\framework>C:\wamp\bin\php\php5.3.0\php.exe yiic webapp ../htdocs

      This work for me!

    • your yii folder may not be properly placed on any web accessible location
      (for eg., wamp/www)

  3. Your tutorial is the best i have seen around with respect to frameworks… Keep up the good work

  4. I must say Larry, I was a little intimidated by the framework at first, but reading your tutorials are a huge blessing!! Easy to understand and clearly explained.

  5. Hi
    I don’t understand the part where you said out framework folder in a logical location on the server and the part about webroot. What does it means? What must i do? Can you please guide me along. Thanks

  6. I am using Windows XP and Xampp. I kept getting an error message when entering yiic webapp path/to/directory. Here is the solution that worked for me.
    Add php.exe’s location to your system path.
    Go to Start > Control Panel > System > Advanced > Environment Variables > System Variables > Path > Edit > Variable value.
    At the very end of the Variable value string add a semicolon followed by your path to php. In my case it is ;C:\xampp\php\
    Save, then go back to the DOS prompt and if you want to call your new folder yiitestapp enter
    yiic webapp ../htdocs/yiitestapp

    • Thanks for sharing that, Steve.

    • Hello steve, you can also make the yiic webapp command work by making the following changes in the yiic.bat file inside the framework folder.

      change the below line from,
      if “%PHP_COMMAND%”==”” set php.exe
      to,
      if “%PHP_COMMAND%”==”” set PHP_COMMAND = C:\xampp\php\php.exe

      • Thanks for the suggestion. There are two downsides to that solution, though. First, whenever you upgrade the Yii framework, you’ll lose that change. Second, you won’t be able to use the command line PHP in other situations. Better to add PHP to your path, in my opinion.

        • Oh gosh, larry thanks for that. I am actually a command prompt guy. Thanks for that tip. Better i should set the PHP path.

    • Thanks so much for the info, Steve. I was getting a php error message, and your instructions helped tremendously!

  7. originalbirchy March 2, 2013 at 10:34 pm

    If you get an Internal Server Error when trying to load the index.php file after creating the webapp, check the owner/group of the index.php file. Mine were 0:0 (nobody), but I changed them to 503:501, like all the files that I code php directly, and the error disappeared. I used FileZilla to check the files and since I don’t own the server (rent from a webhost), but *do* have root access (it’s a dedicated server to me), I used puTTy to use the “chown” command (which is also how I ran the yiic command. eg “chown 503:501 index.php” and “chown 503:501 index-test.php”

  8. I’m using wamp on win7

    to get it working I used
    after going to g:\wamp\www\test\yii\framework

    I used g:\wamp\bin\php\php5.3.10\php.exe yiic webapp g:\wamp\www\test\yii\prash

    And it looked like g:\wamp\www\test\yii\framework>g:\wamp\bin\php\php5.3.10\php.exe yiic webapp g:\wamp\www\test\yii\prash

  9. how to change theme in Yii

  10. I don’t know how its done on linux, but on windows, you will have to type command: ‘path=C:/php/php.exe’ without quotes assuming your php is installed at this location.

  11. thanks man.. i’ve been trying to figure out YII and this was it.. thanks…

  12. Merci, ça marche à merveille

  13. i just needed the command line code to config yii, will you plz provide the all the code.. i even cannot go to application, how to reach up to htdocs and yii floder that i have created? Waiting for positive response..(mac os x 10.8.4)

  14. Hey great tutorial. I just want to suggest something that maybe helpful when programming locally but then want to transfer to a real server. Instead of running your webapp as a subfolder (E.g http://localhost/myapp) you can make it cool by running it as if it would run on the real server E.g. http://myapp (You need the http://).

    The way you do this is my making two changes. I will tell you how it is done on the Mac but I know its the same concept on Windows:

    After you run your yii webapp /htdocs/myappfolder you can make two changes #1) to /etc/hosts (Windows has an equivalent file) and #2) to the httpd-vhosts.conf virtual hosts file of Apache MAMP or XAMPP or WAMP. (In IIS simply add the directory).

    Step #1) Open up the file /etc/hosts and add the following line at the end

    127.0.0.1 myapp (or you can add myapp after localhost e.g. 127.0.0.1 localhost myapp)

    and save it. You may be asked for the admin password.

    Step #2) Open up the virtual hosts file. In MAMP it is /Applications/MAMP/conf/Apache/extra/httpd-vhosts.conf.

    Add the following lines at the end (It should be after anything else. Not inside).

    DocumentRoot “/Applications/MAMP/htdocs/myappfolder”
    ServerName myapp

    Step #3) Save and restart Apache or IIS.

    Step #4) Test in your browser by typing http://myapp or http://myapp/index.php

    Of course you can add as many virtual hosts as you like in this manner.

  15. New kid on the block August 21, 2013 at 5:51 pm

    I am getting a problem with Xampp on win 7. When trying to run the yiic command i keep getting the message

    php.exe is not a valid Win32 application.

  16. its a clear and wonderfull tuto :) , i was able to install yii easily
    thanks a lot .

  17. I am very interested in the MVC capabilities of this framework and it’s potential to simplify a complex development process. I need to develop a fairly complex members area for an existing site based on a pre-existing data structure. However, it will need to be developed in a Windows environment and deployed to a Linux/Apache server running a Teamsite CMS. I was really hoping to leverage the auto-generated model classes in addition to wiring up the views and controllers and then squeezing them into the CMS where necessary. Based on this, will Yii work for me or am I barking up the wrong tree? I really don’t need a heavy framework layer nor will I likely be able to install anything on these staging/production servers. Thanks in advance.

  18. really helpful thanks larry

  19. great post for beginners, it`s good to read and easy to understand! thx a lot

  20. I’m just starting to learn Yii. This is a helpful tutorial and I’ll continue reading your blogs step by step until I finish your employees-department tutorial.
    Thanks a lot dear friend.

  21. I’ve never used a framework before – I’m a total beginner in this. glad to have found a tutorial that helped me install yii on my localhost, without assuming I’m already a seasoned developer. Took some trial and error but I’ve got my first application ready to go. Looking forward to learning more!

    Winning formula was:

    (go to framework folder)
    cd /wamp/framework

    (invoke php)
    path=c:\wamp\bin\php\php5.3.13

    (setup testsite)
    yiic webapp c:\wamp\www\yiitest

    This worked for me, but feel free to suggest alternatives that I could have used that may have been easier!

Trackbacks and Pingbacks:

  1. Tweets that mention Getting Started with the Yii Framework – Larry Ullman -- Topsy.com - February 21, 2011

    [...] This post was mentioned on Twitter by R. Mullen, Legal Data Services. Legal Data Services said: WIsh I'd found this yesterday, but it's enough I can appreciate it today: #Yii tutorial by Larry Ullman. http://ht.ly/40Aa0 [...]

  2. Guida introduttiva ad Yii Framework | Programmando Facile - February 9, 2012

    [...] Fonte: Larry Ullman [...]

  3. Yii and many to many relationships « epilectric.net - April 6, 2012

    [...] get started with, especially for framework beginners like me, but when you get it up and running (starting here for example) things soon start to make sense and it really helps getting standard functionality [...]

  4. Learning the Yii Framework 2 / 8 | 웁스교교주의 이야기 - July 15, 2013

    [...] Yii 프레임워크 배우기 시리즈의 8 편 중 두번째 문서입니다.  원본 글은 http://www.larryullman.com/2009/10/31/getting-started-with-the-yii-framework/ 에서 보실 수 [...]

Comments are great, but I'd strongly prefer any requests for assistance get made in the support forums. Thanks!