Day 01: starting up a project
The symfony advent calendar is a set of 24 tutorials, published day-by-day between December 1st and Christmas. That's right, every day including week-ends, a new tutorial will be published. Each tutorial is meant to last less than one hour, and will be the occasion to see the ongoing development of a web 2.0 application, from A to Z. For Christmas time, the resulting application will be put online, and the source code made open source. This application will be usable, interesting, useful, and fun.
Twenty-four times less than one hour equals less than a day, and that's exactly how long we think that a developer needs to learn symfony. Every day, new features will be added to the application, and we'll take advantage of this development to show you how to take advantage of symfony's functionality as well as good practices in symfony web development. Every day, you will realize how fast and efficient it is to develop a web app with symfony, and you will want to know more.
Considering that it wouldn't be enough of a challenge with just that, and also because we are lazy folks, we have no plans for the 21st day - winter time. The feature that the community will require the most will be added to the application that day, without preparation, and we'll make it work. It will be the get-a-symfony-guru-for-a-day day.
The application to be designed could have been a trivial "show-and-tell" application, like a to-do list, a phone book, or a bookstore. But we want to use symfony on an original project, something useful, with numerous features and an important size. The goal is really to prove that symfony can be used in complex situations, to develop professional applications with style and little effort.
We also hope that lots of people will actually use the application, in order to show that a symfony website can support an important load. That's why the application needs to bring an actual service, and to answer an existing need - or to create a new one. The launch of the website will be a live stress test; this also means that we will need you, humble readers, to digg/bookmark/blog the site and talk about it in real life to check how many visits it can support.
The content of the project will be kept secret for another day. We still have much to do today without describing a full-featured web 2.0 application. This should give you some time to argue and launch additional hypothesis. However, we need a name, so let's call it: askeet.
The objective of the day is to display a page of the application in a web browser, and to setup a professional development environment. This includes installation of symfony, creation of an application, web server configuration, and setup of a source version control system.
It should be easy for those who already followed the previous tutorials, and not very hard for others. And everyone should learn something new.
We'll assume that you use a Unix-like system with Apache, MySQL and PHP 5 installed. If you run a Windows system, don't panic: it will also work fine, you'll just have to type a few commands in the
Unix shell commands can come in handy in a Windows environment. If you would like to use tools like
grep on Windows you can install Cygwin. The official docs are a little sparse, so a good installation guide can be found here. The adventurous may also like to try Microsoft's Windows Services for Unix.
The simplest way to install symfony is to use the PEAR package. However, to be able to use channels - and access the symfony channel - you need to upgrade to PEAR 1.4.0 or greater (unless you run PHP 5.1.0, which includes PEAR 1.4.5):
$ pear upgrade PEAR
if you experience any problem while using PEAR, refer to the Running symfony book chapter.
Now you can add the 'symfony' channel:
$ pear channel-discover pear.symfony-project.com
You are ready to install the latest stable version of symfony together with all its dependencies:
$ pear install symfony/symfony
If a specific version is desired, say 1.0.11, it can be specified as follows:
$ pear upgrade symfony/symfony-1.0.11
Check that symfony is installed by using the command line to check the version (note capital -V):
$ symfony -V
If you are curious about what this new command line tool can do for you, type
symfony -T to list the available options. You might also want to read the Running symfony book chapter to see how to install symfony from a tgz archive or the svn repository. A community contribution also details a non-PEAR installation in the symfony wiki.
In symfony, applications sharing the same data model are regrouped into projects. For the askeet project, we can already disclose the fact that there will be a frontend and a backend: that makes two applications. The project being the shell of the applications, it has to be created first. To do that, all you need is a directory and a
symfony init-project command line:
$ mkdir /home/sfprojects/askeet $ cd /home/sfprojects/askeet $ symfony init-project askeet
Now it is time to create the frontend application with the
symfony init-app command:
$ symfony init-app frontend
Wow, that was fast.
Windows users are advised to run symfony and to setup their new project in a path which contains no spaces. Avoid using the
Documents and Settings directory, including anywhere under
My Documents (or
Documents on Vista).
Now it is time to change your Apache configuration to make the new application accessible. In a professional context, it is better to setup a new application as a virtual host, and that's what will be described here. However, if you prefer to add it as an alias, find how in the web server configuration cookbook chapter.
httpd.conf file of your
Apache/conf/ directory and add at the end:
NameVirtualHost 127.0.0.1:80 <VirtualHost 127.0.0.1:80> ServerName askeet DocumentRoot "/home/sfprojects/askeet/web" DirectoryIndex index.php Alias /sf /usr/local/lib/php/data/symfony/web/sf <Directory "/home/sfprojects/askeet/web"> AllowOverride All </Directory> </VirtualHost>
/sf alias has to point to the symfony folder in your PEAR data directory. To determine it, just type
In Windows, you need to replace the
Alias line with something like:
Alias /sf "C:\php\pear\data\symfony\web\sf"
If the above doesn't work, it may be necessary to specify permissions for the aliased
/sf directory. The following is from a working Windows WAMP installation:
NameVirtualHost 127.0.0.1:80 <VirtualHost 127.0.0.1:80> ServerName askeet DocumentRoot "C:/sfprojects/askeet/web" DirectoryIndex index.php Alias /sf "C:/wamp/php/PEAR/data/symfony/web/sf" <Directory "C:/sfprojects/askeet/web"> AllowOverride All Allow from All </Directory> <Directory "C:/wamp/php/PEAR/data/symfony/web/sf"> AllowOverride All Allow from All </Directory> </VirtualHost>
The domain name
askeet has to be declared locally.
If you run a Linux system, it has to be done in the
/etc/hosts file. If you run Windows XP, this file is located in the
Add in the following line:
you need to have administrator rights to do this.
If you don't want to setup a new host, you should add a
Listen statement to serve your website on another port. This will allow you to use the
Restart Apache, and check that you now have access to the new application:
Symfony can use the
mod_rewrite module to remove the /index.php/ part of the URLs.
If you don't want to use it or if your web server does not provide an equivalent facility, you can remove the
.htaccess file located in the
If your version of Apache is not compiled with
mod_rewrite, check that you have the mod_rewrite DSO installed and the following lines in your
AddModule mod_rewrite.c LoadModule rewrite_module modules/mod_rewrite.so
You will learn more about the smart URLs in the Links and the Routing System chapter.
You should also try to access the application in the development environment. Type in the following URL:
The web debug toolbar should show on the top right corner, including small icons proving that your
Alias sf/ configuration is correct.
If the application works in the development environment (
http://askeet/frontend_dev.php/), but not the production environment (
http://askeet/) then check that
mod_rewrite is configured in
http.conf as described above, and restart Apache. It may also be necessary to run
symfony cc at the command line to clear the symfony cache.
The setup is a little different if you want to run Symfony on an IIS server in a Windows environment. Find how to configure it in the related tutorial.
One of the good principles of lazy folks is not to worry about breaking existing code. Source version control allows us to:
- work fast
- revert to a previous version if a modification is inefficient
- allow more than one person to work on the project
- have access to all the daily versions of the application
We will use Subversion for this purpose. We assume you have already installed a subversion server or have access to a subversion server.
First, create a new repository for the
$ svnadmin create $SVNREP_DIR/askeet $ svn mkdir -m "layout creation" file:///$SVNREP_DIR/askeet/trunk file:///$SVNREP_DIR/askeet/tags file:///$SVNREP_DIR/askeet/branches
For those new to subversion. These two lines create your subversion repository. The second line creates the directory structure of the repository. All the main development code will be versioned in the
tags holds copies of major code releases such as version 1, version 2, etc.
branches is for development code that differs substantially from the main development code. The usual intention is that
branches will eventually be merged back into the
trunk. For example the main
trunk development can continue while an unproven new feature is exhaustively tested and fixed in a
branch. Once completed the
branch code is merged back into the
trunk along with any new changes made since the code branched. SVN provides powerful tools to assist this process.
Next, you have to do the first import, omitting the
log/ temporary files:
$ cd /home/sfprojects/askeet $ rm -rf cache/* $ rm -rf log/* $ svn import -m "initial import" . file:///$SVNREP_DIR/askeet/trunk
For those new to subversion. The fourth line here imports the askeet files and directories into the SVN
trunk repository. The code is now under version control.
Our code is under version control but the code must be checked out to allow SVN to track changes. Backup the original application directory and use a checkout of the SVN version for our working copy:
$ cd /home/sfprojects $ mv askeet askeet.origin $ svn co file:///$SVNREP_DIR/askeet/trunk/ askeet/ $ ls askeet
Once all is OK, delete the original directory we used for import, as its no longer required:
$ rm -rf askeet.origin
For those new to subversion. The
trunk code is now in our working directory
askeet/. This is the code that we will modify and develop. From an SVN perspective it is called our "working copy". SVN tracks changes to this code when it is committed to the repository.
There is one remaining thing to setup. If you commit your working directory to the repository, you may copy some unwanted files, like the ones located in the
log directories of your project. So you need to specify an ignore list to SVN for this project.
$ cd /home/sfprojects/askeet $ svn propedit svn:ignore cache
The default text editor configured for SVN should launch. Add the sub directories of
cache/ that SVN should ignore when committing:
Save and quit. You're done.
Repeat the procedure for the
$ svn propedit svn:ignore log
And enter only:
Now, make sure to set the write permissions on the cache and logs directories back to the appropriate levels so that your web server can write to them again. At the command line:
$ chmod 777 cache $ chmod 777 log
Windows users can use the great TortoiseSVN client to manage their subversion repository. Just remember to never delete directories using the normal Windows Explorer commands. Instead use Alt-Click Tortoise-Delete (or Rename) so that SVN knows what you intended. Otherwise you will be unable to commit and will need to instead revert to the last versioned copy of your code using Tortoise-Update.
If you want to know more about source version control, check the project creation chapter in the symfony book.
The askeet SVN repository is public. You can access it at:
Go ahead, check it out.
Today's code has been committed, you can checkout the
$ svn co http://svn.askeet.com/tags/release_day_1/ askeet/
Well, it's already one hour! We talked a lot, and did nothing new for the symfony early adopters. But just have a look at what will be revealed for our second day of the symfony advent calendar:
- what the application will do
- building the data model and generating the object-relational mapping
- scaffolding a module
Make sure you come back tomorrow!