Application Directory Structure

In our last installment we created the directory structure we will be using for the development environment. Which was:

Today we will be adding a directory structure for the actual application itself, which means we will be working in the udid/project/trunk/Udid directory. Just as a refresher the public_html directory is our document root and all our PHP code will be stored outside the root in the ‘Udid’ directory.

There is one thing I want to mention before we really get into it. As a general rule I like to define one class per file, this is not a hard and fast rule I adhere to, but for the most part one file = one class. Given this I will use the terms ‘class’ and ‘file’ almost interchangeable for this post.

OK now that that is out of the way…There are two directories I include in ALL my project and they are:

Documents – this will hold all developer documentation for the project; code documentation, ‘to do’ lists, notes, etc.
UnitTests – This of course will hold all the unit tests for the application code.

So now our Udid directory looks like:
Udid | |-> Documents |-> UnitTests

Now it is time to make some design decision about the structure of the application code itself. The directory structure really should be looked upon as an organizational task, i.e. What is the best way to organize the files we will be creating? The organization needs to make sense to you or your team of developers. One way to test yourself when you are deciding on a structure is to attempt to explain it to someone (if no one is available then write it down). If you find yourself going back over parts of the structure or having trouble finding the words to truly explain everything, then it is probably time to go back and try to reorganize. (I guess this post will be a good test for me, huh?)

So here goes…

One of my pet peeves about many PHP applications is that the PHP, HTML, and CSS are completely muddled together. I have to admit the PHP community in general has been getting better at the separation of presentation and business logic, but in many personal project that I’ve seen this is still an issue. For this project we will be using a template system where we define actual HTML templates. Since we will need a place to hold these template files I create the directory ‘Templates’ beneath ‘Udid’.

I also know there will be generic classes we need to define which are not a part of any one section of the application, but are used by multiple aspects of the application such as database classes, iterators, an ‘emailer’ etc. These classes are also not limited to this one application, but can be used over and over again in project after project. I often think of these classes as books in a library, available to everyone. Consequently I will call the directory which holds these classes the ‘Library’.

Finally we will need a place to store all the core components of our application and I’ve decided to call this storage area the: ‘Core’. Honestly I’m not crazy about this name, in the past I’ve used; Engine, Backend, etc. but I don’t really like them either so for this project we are calling it ‘Core’.

We have now added three other directories and the current structure looks like this:

We have one last directory to address and the base application structure will be complete. That directory is the ‘Core’. We cannot just start creating files in the ‘Core’ without some sort of organization or we’ll end up with an application core which consists of a long list of files with no organization except for maybe some naming conventions. Since this is where the majority of our development time will be spent, we need to define some parameters about where files should exist.

For this project we will be using the Model View Controller (MVC) design pattern. This is an organizational pattern to help separate different parts of the application code. As with all design patterns there is a lot programming theory associated with it and there is no way I can fully explain it here. If you are not familiar with this design pattern I urge you to search the net for more information. For our purposes the basic idea of each section is:

Model – Contains application data and business logic. Objects which represent the data, and the processes to change that data.
View – Extracts data from the model and shapes it for presentation.
Controller – Receives requests and directs it for proper processing. Basically interpreting the request for the Model and View.

Since we will be using this pattern I have decided to create one directory for each section below ‘Core’. These will hold the files associated to each section. Now some may argue that the ‘Templates’ directory should be located below ‘View’, but I disagree. I want a place for templates that can easily be found, and is not located within the application code itself. I use this reasoning because I want other people who may not be PHP programmers to be able to find the templates and alter the display of the application.

There is one final directory I would like to include and that is a directory to hold phpDocumentor. We will use this to generate documentation for the code. This directory will be stored beneath the top ‘udid’ directory.

We have finally completed the development and application structure: