Albert Fama » Project: Udid

Application Directory Structure

Albert Fama — Sun, 20 Jul 2008 05:50:35 +0000

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:

We can now import this directory structure to SVN and export our working copy.

Thanks for reading. Until next time…

Development Environment Setup

Albert Fama — Sat, 12 Jul 2008 18:29:52 +0000

Before we get into the directory structure we will be using for this project, I wanted to let you know I have decided on a project name. The basic idea for the application I’m building is to create a hierarchical storage system, hence the name:

UDID – User Designed/Defined Information Directory
(Of course it is an acronym, you expected something else?)

There is a legitimate reason for naming the project before even setting up the development area. The project will be stored under the ‘Udid’ directory, and all of the class names will reflect the position of the file within the project’s directory structure. I will explain more about this when we get into writing classes and actually coding, but if you would like more information about this type of setup you can read about the Zend Framework naming conventions for classes.

OK now we have a name and it’s time to setup the directory structure. First we create the ‘udid’ directory and beneath that we create a ‘project’ directory; such as:
udid |-> project
The ‘project’ directory will hold all the files directly associated to the project. The reason I have created this directory and did not just store the project code within ‘udid’, is because we will be using some third party applications to help with development and I do not want that third party code to actually be associated to the project code. For example we will be using Simple Test for unit testing. We will be placing Simple Test within ‘udid’, but not within ‘project’. So now we have:
udid |-> project |-> simpletest
As you know we will be using SVN to store the code, so we are going to be using what I learned as the traditional setup for a SVN project, not because it is the traditional way, but because I’ve used it before and it has worked well for me. This structure is:
project |-> branches |-> tags |-> trunk
These three directories have very specific purposes:

branches: Experimental development branches. Branches are used when you decide to make some dramatic changes to the code base, but your not really sure how it is going to work out, so you do not want to code within the ‘trunk’ but you may want to merge the code within the trunk at a later time.
tags: This directory is used to store the project at certain milestones, i.e. version releases.
trunk: Main development thread

At some point a long time ago I got into the habit of creating a subdomain for each new project I work on, this I find convenient because the subdomain’s document root is its own and is not cluttered with other directories, files, etc. As an added bonus the document root can be anywhere on the system. Consequently the directories below ‘trunk’ look like this:
trunk |-> public_html |-> Udid
Obviously ‘public_html’ is the document root, and ‘Udid’ will store all the back-end PHP code. Notice the PHP code will be stored outside the document root (where a browser is unable to access it directly). I prefer to setup my projects this way as an added security measure. For more information about the security aspects of this; check out Chris Shiflett’s article: Security Corner: Secure Design (be sure to read the comments).

For now ‘public_html’ will remain empty and ‘Udid’ will hold the directory structure for the application. So this will be the development directory structure we’ll be using…
udid | |-> project | |-> branches | |-> tags | |-> trunk | |-> public_html | |-> Udid | |-> simpletest
Please note, I have still not imported the project into SVN, you can actually do the import as soon as you have the first directory created, but I like to wait until I have the basic structure of the application set, which brings us to the topic of the next post. What is the directory structure of the application itself; or what directories will be created below Udid: ‘udid->project->trunk->Udid’?

I will post this structure in the next few days, and import the project into SVN, so we can finally get down to some code! Thanks for reading.

Starting a New Project

Albert Fama — Fri, 04 Jul 2008 18:18:17 +0000

Greetings once again; I am currently in the design phase of a new project. I thought it could prove to be an interesting set of blog entries if I loosely documented the progress here at Obnexus. I will try to relate all experiences as the project is created.

Even if we try to account for all aspects in the design phase, I know there will be situations where decisions made early on will have negative effects later down the road. I will document everything as it happens, because I find that I learn more from mistakes, and hopefully you will to.

I will mainly be working on this project solo, which means I will not only be dealing with PHP and MySQL, but also HTML, CSS, JavaScript, etc. Since I believe many developers work alone I hope that this will interest most readers.

I personally like to start a project with a name, simply because it gives the project an identity, but… In this case I cannot decide on an appropriate name so I am going to skip this step for the moment and move onto some actual code design, one of the most important and exciting steps.

First let’s set down some general guidelines:

Version Control: Subversion (SVN)
PHP Version: The project will be written in PHP5 and will not support PHP4. Let’s face it PHP4 is dead and if your server is still running 4 you NEED to upgrade.
MySQL Version: I will be using MySQL 5, again if your not on 5, what are you waiting for?
HTTP Server Platform: Apache
Browser Support: Firefox, Internet Explorer, AOL Browser, Netscape, Opera, Safari. This is just a list off the top of my head, basically we are going to attempt to support as many browsers as possible.

Again these are just general guidelines; eventually the project will be able to support multiple database servers, different HTTP server platforms, etc. Initially these are our targets for support; no reason to bog the development process down with attempting to support everything under the sun, but… Since we want the project to be as flexible as possible, we will need to account for this NOW in our framework design.

OK, now that we have our guidelines; the next step will be to start coding right? Wrong, next we will decide on a directory structure, and create the SVN repository to hold our project.

I hope you are as excited as I am to get this thing underway, please check back soon.