The Yii Framework – Larry Ullman This is a copy of the Larry Ullman series ‘Learning the Yii Framework’. See http://www.larryullman.com/2009/06/18/introduction-to-the-yii-framework/. 1. Introduction to the Yii Framework In 2009, I had three decent-size Web sites to develop, so I thought I might try using a PHP framework for the first time, instead of coding everything from scratch. I’ve used Ruby on Rails for Web development before, so I’m comfortable with frameworks and the MVC architecture, but I wanted to educate myself on PHP frameworks. After researching a handful of frameworks, and after an unsatisfying attempt to use Zend Framework, I finally settled on, and really came to appreciate the Yii Framework. At the time, the Yii Framework was still quite new, and there are still bugs to be worked out (for the more advanced stuff), but Yii works so well that it’s very easy to use. In this first of several posts on the Yii Framework, I just discuss setting up and testing Yii. (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.) The first thing you need in order to use the Yii Framework is access to a Web server with PHP installed, of course. But if you’re reading this, I’m going to assume you have access to a PHP-enabled server. Note that the Yii Framework does require PHP 5.1 or above. Fortunately, the framework will test your setup for you! Start by downloading the latest stable version of the Yii Framework. At the time of this writing, that’s 1.0.6 1.1.4. The file you download will be named something like yii-version.release.ext and is only around 2MB. Expand the downloaded file to create a folder of stuff: CHANGELOG, LICENSE, README, and UPGRADE text documents demos folder framework folder requirements folder You should read the README and LICENSE docs, of course, but the folders are most important here. The demos folder contains four Web applications written using Yii: a blog, the game Hangman, a basic “Hello, World!”, and a phone book. The demos are great for seeing working code as you’re trying to write your own. The framework folder is what’s required by any Web site using Yii. The requirements folder is something simple and brilliant… I also assume that you already know what the Web root directory is on your computer or server: this is the folder where your URL points to. In other words, when you go to http://localhost or http://www.example.com in your Web browser, it grabs documents out of the Web root folder. Going with Yii’s conventions, I’ll call this WebRoot. Create a new folder in your WebRoot called yii, and copy the framework and requirements folders there. Then go to yourURL/yii/requirements in your Web browser (for example, http://localhost/yii/requirements). You should see a report as to whether or not your setup meets the minimum requirements. Assuming your setup passed all the requirements, you’re good to go on. Note that you don’t necessarily need every extension: you just really need the Yii Framework requirements, PDO, and the PDO extension for the database you’ll be using. (If you’re not familiar with it, PDO is a database abstraction layer, making your Web sites database-agnostic.) In my next post, I’ll show you how to use the command-line Yii tools to create your first Web application. It’s pretty sweet stuff and is the closest thing to Ruby on Rails that I’ve seen (which I consider to be a very good thing). Subsequent posts will walk you through developing a Yii-based application. Use the series links at the top and bottom of this post to navigate the series. You may also want to read my posts on the MVC architecture. 2. Getting Started with 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. 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.