How to setup Zend Framework with Apache on Windows

Zend Web Framework is one of the most popular PHP frameworks out there to ease the construction of web sites. Though, there are lots of online tutorials on how to set it up using Apache, details are bit sketchy on getting everything to work on Windows machines. I was following several online tutorials, including the official tutorial from the Zend website itself, but kept running into various problems associated with getting Apache and Zend to work properly.

I am sure I am not alone with these issues, and compiled a small guide to show how to get Zend framework working on your windows machine (tested on XP, Vista and Windows 7) using Apache web server.

I’ve broken down the steps into 3 parts:

1. Installing the Zend framework
2. Setting up a simple Zend/PHP project
3. Troubleshooting

Installing the Zend framework

Minimum system requirements for Zend framework includes PHP and a web server (e.g. Apache, IIS etc). There are numerous ways to set up and configure this. In this tutorial, I’m sticking to the simplest solution; which is to install the Zend Server Community Edition (its free) that sets up both PHP and Apache web server for you.

Simply download the installer from this link, and run it (Use the ‘Custom’ installation if you want to change the port number for your services (by default :80) and/or installation path). This tutorial assumes that your port is set to 8080.

For other means of setting up (e.g. installing PHP/Apache separately or installing other components such as MySQL etc) refer to Zend Wiki.

Before progressing any further, test that you have successfully installed Zend Server by pointing your browser to: http://localhost:10081/ZendServer (10081 is the default port no. for ZendServer).

Setting up a simple Zend/PHP project

1. Open a command line window (Start->Run, and then type cmd followed by Enter) and navigate to the directory you want to create a new web project.
2. Type the following to create a new PHP project that uses Zend

zf.sh create project zend-helloworld

Running this command will create your basic site structure, including your initial controllers and views. The tree looks like the following:

For the rest of this tutorial I assume that Zend Server is installed to C:\Zend and your project is at C:\php-projects\zend-helloworld.
3. Copy the Zend framework libraries folder (C:\Zend\ZendServer\share\ZendFramework\library\Zend) to your project’s library folder (C:\php-projects\zend-helloworld\library).

cd C:\php-projects\zend-helloworld\library
cp -r C:\Zend\ZendServer\share\ZendFramework\library\Zend .

4. Configuring Apache
This is the step where most users (like myself) run into problems. This involves creating a virtual host on your apache server for your zend-helloworld web application, and enable rewrites to help Zend framework with redirecting URLs.

1. Enable rewrites on your Apache server:
   • Open the http.conf file for your Apache server (e.g. C:\Zend\Apache2\conf) and add/uncomment the following line if it does not exist:

     LoadModule rewrite_module modules/mod_rewrite.so
     

   • Find the entry within http.conf file, and ensure that ‘AllowOverride‘ and ‘Options‘ values are set to ‘All‘ (by default these are set to None). Keep the other options unchanged.

     AllowOverride All
     Options All 

2. Add the zend-helloworld application as a virtual host
   • Open the http.conf file and add the following at the end:

     <VirtualHost *:8080>
     	DocumentRoot "C:/php-projects/zf-tutorial/public"
     	<Directory "C:/php-projects/zf-tutorial/public">
     		AllowOverride All
     	</Directory>
     </VirtualHost> 

   • Important:
     • Pay attention to the direction of the slashes (they are forward slashes (‘/‘), instead of backslash (‘\‘) commonly found within Windows).
     • The port number (8080) declared in the VirtualHost should match up with the value you specified during installation of Zend framework.
     • The port number (8080) should be bound to Apache. Ensure that the following command is present in the http.conf file:

       Listen  8080

3. Add URL rewrite rules to the .htaccess file found under C:\php-projects\zf-tutorial\public folder. Ensure the content of the file looks as follows:

   RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} -s [OR]
   RewriteCond %{REQUEST_FILENAME} -l [OR]
   RewriteCond %{REQUEST_FILENAME} -d
   RewriteRule ^.*$ - [NC,L]
   RewriteRule ^.*$ /index.php [R=302,L]
   

   This redirects Apache to serve any existing files (-s), symbolic links (-l) or directories (-d) as you specified them, while forwarding all others (e.g. non-existing file or directory) to index.php file found within the same directory level as the .htaccess file (i.e. C:\php-projects\zf-tutorial\public).

   • Important:
     • Ensure that there is a forward slash (“/“) before the index.php. Otherwise, you will get some cryptic browser errors claiming it can’t access the file “/C:/php-projects/zf-tutorial/public/index.php” on the server.
4. Test that everything works
   • Navigate to your project’s public folder and create some dummy files that are not empty (see the attached figure for an example).
     
   • Whenever you type an existing file/folder you should be taken to that file/folder.
     e.g. http://localhost:8080/dist/test.txt, http://localhost:8080/test2.txt and http://localhost:8080/index.php should take you to the respective pages.
   • Typing a non existent file path will take you directly to index.php file
     e.g. http://localhost:8080/zf-helloworld/public, http://localhost:8080/nonexistingfile.txt

After reaching this step, you can get on with actually developing your web applications using Zend. There are plenty of great tutorials out there for it. A couple of my personal favourites are:

• http://www.cs.wcupa.edu/~rkline/Php/zend-intro.html and
• http://akrabat.com/zend-framework-tutorial/

Troubleshooting:

Here are some common problems I encountered during my setup and the solutions I came up with. This is by no means a comprehensive list, and feel free to post your own problems in comments section. I will try my best to answer you or point you in the right direction.

1. Cannot get URL redirection to work
   Fix:
   1. Check your firewall settings to ensure the port is not blocked (or disable the firewall temporarily).
   2. Check that your DocumentRoot and Directory path contains only forward slashes.
   3. Delete the .htaccess file from your project folder.
   4. Add the highlighted lines to the VirtualHost definition you added to the http.conf file, save and restart the Apache server.

      <VirtualHost *:8080>
      	DocumentRoot "C:/php-projects/zf-tutorial/public"
      	RewriteEngine On
      	RewriteRule ^.*$ http://www.google.com
      	<Directory "C:/php-projects/zf-tutorial/public">
      		AllowOverride All
      	</Directory>
      </VirtualHost>

   5. Check that whenever you enter a URL (e.g. http://localhost:80/index.php), it get redirected to www.google.com
   6. If this does not work, that means Apache server is not configured to handle URL redirection. Please refer to Apache mod_rewrite documentation for more detailed instructions: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
2. Get an error saying “you can’t start the Apache server”
   • This is most likely due to a mistake you did while modifying your http.conf file. Roll back to the original and see whether you still get the problem. Restart the server after each incremental change you do to the http.conf to ensure it starts properly.
3. Get an error saying “Forbidden: You don’t have permission to access /C:/Dev/php-projects/zf-tutorial/public/index.php on this server.” when a non-existent file name is typed (e.g. http://localhost:80/zf-helloworld/public)
   Fix:
   • Double check your .htaccess file to ensure that you have a forward slash in front of your index.php file.

     RewriteRule ^.*$ /index.php [R=302,L]

Helpful links

• Apache VirtualHost documentation
• Apache Mod_Rewrite/URL Redirection documentation