With the first release candidate of Zend Framework 2 about to be released, more and more developers are trying to get a first look at the framework. Since the installation routine and the starting point has changed quite a bit compared to version 1 of the framework, a lot of users – especially those windows based – have some troubles of getting started.
Update: While this tutorial still is very useful for the xampp folks I strongly suggest to take a look at my blogpost about “Setting up a development environment on Windows” which uses PHPs internal webserver. Much easier to handle!
In this tutorial i will cover the very low basics that you need to get a ZF2 site running on your localhost.
Installing Xampp for Windows
The very first step is to install xampp on your system. Most people have done this quite some time ago. However, you should know that for Zend Framework 2 you will require at least PHP version 5.3.3.
- Go to apachefriends.org and download xampp (personally i choose the installer)
- Install xampp to a different directory than C:\Program Files (I choose C:\xampp as an example throughout this post)
- Start the xampp controll panel, the apache webserver and check in your browser if http://localhost is working
Access the PHP executable
Later, when using the composer.phar to install the framework, we will be required to access the php executable. When using the xampp installer this should have been done already. Check if the executable is accessible by doing the following
- Start the Windows Command Line Interface (CLI) (Start Menu > Type cmd > Hit enter > The cli should pop up)
- Type php -v and hit enter
- You should get information about your current PHP Version. As noted previously it should be at least PHP 5.3.3
Command php not found
If you have installed your webserver manually, you may receive the following error message when trying to run the php -v command:
´php´ is not recognized as an internal or external command,
operable program or batch file.
If this happens it means Windows is unable to locate the php executable. In this case we simply need to add the executables folder to our environment.
- Right-click on Computer inside your start-menu and click Properties
- Click Advanced system settings inside the left panel. A new window System Properties (Tab: Advanced) should pop up
- Click Environment Variables. A new window will pop up once again.
- In the lower of the two boxes search for the variable Path and double-click it
- Leave everything as is and just EXTEND the variable by ;C:\xampp\php (of course adjust your xampp directory)
- Hit ok, ok, ok, start a new CLI (!) and once again check what php -v returns. It should work now.
The next thing in line to do is installing git on your system. GIT and Windows can be a tricky thing if you want to do extended stuff, but for the basics we just need to get access to the git command for our CLI. There are several options out there what to install, be it a GUI or just some CLI stuff. Just to name a few:
Personally for the few things i do with git, i run with msysGit. Just download the installer from Google Code run, the installer and put it on any directory you like.
After installing go to the directory and run either git-cmd.bat or msys.bat. Both will start a new CLI and you’ll be able to run the git command. Try by running git –version and you should get the wanted information. In case of an error check the installation manual, but there shouldn’t really be any.
If you don’t want to run git-cmd.bat each time you may as well add the msysGit\bin folder to your PATH environment variable. This is done the same way we just added php to our environment variables above. After that the git command will be available in all your system CLIs.
Now that we have the system requirements for a zend framework application in place, the best way to start off is by downloading / cloning the ZendSkeletonApplication. For this we will use Git. It can be done without, but for future works it is highly recommended for every developer to slowly start using git and getting familiar with it (that’s on my todo-list, too).
You find the ZendSkeletonApplication on Github. With all the instructions needed, i will cover them again though.
- Start a Git compatible CLI
- Move to the directory you want to have the Zend application inside. Example: C:\xampp\htdocs. You move be using the cli command cd (change dir).
- Run the following git command:
git clone git://github.com/zendframework/ZendSkeletonApplication.git
You can leave the <OptionalFolderName> blank obviously. If you do leave it blank the folder for your project will be named ZendSkeletonApplication. For most use-cases however you would want some kind of real name. So if you want your project to be named weblog, you’d run the following command:
git clone git://github.com/zendframework/ZendSkeletonApplication.git weblog
Troubleshooting connection to git
One of the most common problems with git failing to pull the sources is those of blocked ports and proxy-servers. The error message containing fatal:unable to connect to github.com implies that the default port for using git is blocked. The things to do here is to simply use different protocols to grab the git sources! Go with one of the following commands and try again:
git clone https://github.com/zendframework/ZendSkeletonApplication.git weblog
git clone firstname.lastname@example.org/zendframework/ZendSkeletonApplication.git weblog
Working behind a proxy server
When working behind a proxy server, most commonly at work spaces, can result to some errors, too. The only thing required here is to set the system variable HTTP_PROXY to the proxy address of your use. Open the CLI and run the following command:
At some weird environments (ie my work place) you’ll be required to use it with the http-protocoll assignment. Don’t ask me why, it might fix things for you, too, though.
Missing write permissions on disk
Another uncommon problem on windows system is missing write permissions when pulling stuff from git. This is easily handled by simply running your CLI with administrator privileges.
Downloading Zend Framework
To conclude our little journey we will download the Zend Framework 2 itself. The recommended way to do so is by using the power of composer.phar. This file is located at your base directory of your ZendSkeletonApplication.
Be sure to run the following commands at a git compatible CLI and from the directory of your ZendSkeletonApplicatoin
php composer.phar self-update
php composer.phar install
This will take quite a while as the whole framework gets downloaded. Composer.phar basically is a container that does a couple of git commands for you. With this you will be able to download other optional dependencies (i.e.: Doctrine 2) very easily, too. More about this later though.
Configuring apache virtual host
The next step to get our ZendSkeletonApplication running is by configuring our apache vhost configuration. This is done by modifying the following file:
Add the following lines to the file, while ensuring you have the first line in there!
Allow from all
That’s it, restart your apache webserver and you’re good.
With aboves configuration we no longer have access to http://localhost. To be able to access the localhost we need to add another virtualhost named localhost.
Configuring Windows Hosts
The absolutely last thing is to modify the windows hosts file, so that whenever we access our virtual host via http://projectname.loc windows redirects this request to our webserver and not to the www. Open the following file:
Add this line
127.0.0.1 www.projectname.loc projectname.loc
All set and done
With all this done, you should be ready to have the ZendSkeletonApplication running. Try to access projectname.loc from within your browser and hopefulle you will see the SkeletonApplication. If not, leave me a comment as apparently my little tutorial needs to get better!
I hope you enjoyed this, there is more to come!