꿈을 꾸는 블루비

One of my commenters, James has provided a working production solution versus my “hacked” solution. See the comments and be sure to visit his site. Thank you James!

---

@ work, Stephen and I were tasked with fulfilling a requirement for the big boss, so we selected an up and coming Rails-like framework called CakePHP. Cake’s really fun and easy to use and like Ubuntu, “everything just works“… until you try hooking it up into IIS with ‘pretty URLs’. It took us a day of testing, hair pulling, more testing, more hair pulling, but finally - we’ve debunked the mystery.

First, let me start off by saying that we read all the wiki documentation, searched google groups, and though we found people doing similar things, we didn’t find any solution that satisifed our needs. We found partial solutions with poorly written wiki tutorials, so that’s why you’re reading a brand-new one.

The setup

Our setup consisted of the Cake framework (cake_1.1.6.3264.zip) running on Win2K w/ IIS5 and PHP5 running as an ISAPI Dll. We created a virtual directory named “tp” that’s currently mapped to the app/webroot directory in our Cake installation directory. From reading all the available tutorials, Cake’s functionality all boils down to passing index.php in the app/webroot directory the following:


?url=/controllerName/action/params

This, my friend, is how all the magic begins. So, from the web, I should always be able to reach the following URL:


http://domain.com/tp/index.php?url=/controllerName/action/params

The get-go

Here are the following results from our tests:

Test 1: Do nothing

Stephen and I both hypothesized that by doing nothing, we’d just manually echo out all linking URL’s, i.e. we wouldn’t use the $html->link helper function. This works, period. However, if we do nothing to the configuration, and we do employ the $html->link helper, $html->link(”/controllerName/action”) writes out the following URL:


http://domain.com/controllerName/action

First off, since we have a virtual directory named “tp”, this obviously won’t work. Second, if I define (’WEBROOT_DIR’, ‘tp’) within app/webroot/index.php and then use $html->link(’/controllerName/action’), I get the following URL instead:


http://domain.com/tp/controllerName/action

Closer, but this still doesn’t work because ISAPI Rewrite isn’t enabled. So… that leaves us wondering, how do we use $html->link without modifying the configuration? In any case, we revert the variable WEBROOT_DIR back to its original setting for our next test.

Test 2: Enable Cake Short URLs

With Cake Short URLs enabled, a user will be able to access particular actions via the following URL:


http://domain.com/tp/index.php/controllerName/action

To enable the short URLs, I followed the wiki tutorial. Basically, this involves uncommenting the BASE_URL environment variable and defining (’SERVER_IIS’, true) in core.php in the app/config directory. Now, when I use the $html->link helper, these configurations enabled inserting /tp/index.php/ into the url and everything works! For example, $html->link(’/controllerName/action’) now prints the following:


http://domain.com/tp/index.php/controllerName/action


(And it works too!)

This solves the problem but still doesn’t give us the ideal solution. After all, who wants that index.php within the URL? Not to mention, enabling this configuration setting made it impossible to access the following (original) URL:


http://domain.com/tp/index.php?url=/controllerName/action/params

Is this the expected behavior? As a side note, I can now access URLS as such:


http://domain.com/tp/index.php?/controllerName/action/params

Notice the ‘?’ without the ‘url=’. Is this expected behavior as well? In any case, on to enable ISAPI Rewrite.

Test 3: Enable ISAPI Rewrite

To enable ISAPI Rewrite, we know we had to disable Cake Short URLs by disabling the BASE_URL variable, but at the same time, we decided to leave the IIS_SERVER variable to true. Next, we decided to follow this tutorial on the Cake wiki. No offense to the author, but this entry is incomplete and leaves no explanation as to how the author came to those Rewrite rules. Also, the tutorial doesn’t explain how to enable the pretty URLs for a site running in a virtual directory.

So, we downloaded the ISAPI Rewrite Dll from http://www.isapirewrite.com/. Note, download the free version, but realize that there are limitations on what it can do. Enable the ISAPI Dll @ the Site level since you need the full version for granularity at the virtual directory level. The httpd.ini file that’s listed in the wiki only works if you’re running Cake from the IIS Site level and not from a virtual directory.

Our configuration

Here’s what we did to enable the ISAPI Rewrite from a virtual directory. Our httpd.ini file looks like the following:

[ISAPI_Rewrite] 

// This rule catches the Short URL settings
RewriteRule (.*?\\.php)(\\?[^/]*)?/([^/]*)/(.*) $1(?2$2&:\\?url=/$3/$4) 

//This rule performs the ISAPI Rewrite rules
RewriteRule ^/VIRTUAL_DIRECTORY_NAME_HERE/(.*)/ /VIRTUAL_DIRECTORY_NAME_HERE/index.php?url=/$1

Note, replace virtual_directory_name_here with the name of your virtual directory. As you can see, RewriteRule ^/VIRTUAL_DIRECTORY_NAME_HERE/(.*)/ /VIRTUAL_DIRECTORY_NAME_HERE/index.php?url=/$1 is taking the following URL:

/virtual_directory/controllerName/action/ and rewriting it to /virtual_directory/index.php?url=/controllerName/action.

This is exactly how we want it!

Wait, as you can see though, the RewriteRule matches URLs that have a slash at the end. We figured that the original wiki poster left the slash so that this rule wouldn’t match any of the files being served out of app/webroot such as the css/img files.

Wait… what implications does this have?

Well, this just means that when you use the $html->link helper, you’ll need to end all your actions with a “/”. For example, if you want to link to /controllerName/action, you must now type $html->link(”/controllerName/action/”). Now, this will match the second RewriteRule and everything will work!

However, there’s just one tiny piece we’re forgetting. If you did try this out on your site, you’ll find that the URLs generated from $html->link still don’t have the virtual directory name in it. You’ll see that the links generated will be http://www.domain.com/controllerName/action/. Well, from our experience in past tests, this means you have to define(’WEBROOT_DIR’, ‘virtual_directory_name’) in the app/webroot/index.php file and voila…

Everything now works!

If you are interested in using CakePHP on an IIS server, you may have experienced a few problems here and there. Mostly, the problems arise when you are trying to integrate Cake with an existing IIS server and PHP infrastructure that is large or complicated.

Regardless, I have accumulated a few tid-bits of knowledge that may save someone an immense amount of head-scratching, so hold on to your hats.

Note: I still think Apache is the preferred server for a lot of reasons, but if you are absolutely locked into IIS, then please read below. If you think you might be moving over to Apache/Linux sometime soon, seriously consider biting the bullet now. It’s sorta like saving for retirement… the more you do early on, the less of a headache it will be later.

Dustin’s Beginner Guide To CakePHP on IIS

I am assuming you have installed PHP properly and have tested your IIS + PHP configuration for correct functionality prior to attempting the Cake install. Installing PHP on IIS is outside of the scope of this tutorial, sorry.

Configuring IIS

I used Windows XP Pro IIS 5.1 for the instructions in this guide. As I roll Cake apps onto different IIS servers and versions of Windows, I’ll be sure to share what I learn in the different environments.

- Make sure that IIS isn’t checking to see if a script exists before executing.

1) Go to your server admin panel, right-click on the web server (ex: Default Web Site) and click on properties.2) Go to the Home Directory tab at the top and click on the Configuration button near the bottom of that page.

3) Find the .php extension listed in the “Application Configuration” page that appears; click on the .php extension and then click the edit button near the bottom of the page.

4) You should be on the “Add/Edit Application Extension Mapping” page: simply uncheck the “Check that file exists” box at the bottom of the page.

5) Click OK, Click OK again, Click OK once more (you should’ve closed all the windows).

6) Now restart IIS (ie: command prompt -> IISReset).

This little process fixes a few problems and was a sort of ‘magic bullet’ for many of my troubles. If you look into how Cake works and what this check box in IIS does, you’ll have a “no duh” moment like I did.

- Double check your security permissions for the Cake folders/files you dropped into your web root. Just remember that something unzipped to the desktop and copied into your Inetpub directory will often have security permissions that will prevent the server from accessing some files properly.

- Remember that the app/temp folder must be writeable by the web server (for caching). That particular problem had me scratching my head once or twice.

Configuring Cake

1) Drop Cake somewhere inside your web root.2) Go to the APP/Config folder within your cake directories. Simply un-remark (’BASE_URL’, env (’SCRIPT_NAME’)) at the top of the core.php config file.

You should now have a working CakePHP application inside an IIS environment. I have assumed that “pretty” URLs aren’t of great concern to you. If you absolutely must have pretty URL’s, consider a good mod-rewrite filter for IIS like Helicon Mod-Rewrite. It’s easy to use and configure, lightweight, and free for most users. If you need it, it can be done.

If you have any hints, tips, problems, or suggestions… please contribute by leaving a comment below. I am certainly not the end-all resource here as my experience is limited to a few versions of IIS (I mostly run Apache anyways).

define ('BASE_URL', env('SCRIPT_NAME'));