Wombat's Directory Structur

The good news is: coding is fun. The bad news is, coding is more fun than writing documentation. The problem is, that nearly every class or any other reausable code renders useless if it is not well documented. Well, I try to keep up.

I first did not know where to start. How to start explaining a sort of complex framework? I'm still not sure, so I just start where you probably start: the directory layout.

Files and Folders

Womat
 \
  + doc
  + etc
  + etc-default
  |          \
  |           + config.xml
  |           + site
  |                \
  |                 + page
  |                 + event
  |
  + htdoc
  |     \
  |      + ajax.php
  |      + css.php
  |      + js.php
  |      + site.php
  |      + file.php
  |      + ...
  |
  + include
  |       \
  |        + WB
  |        + pat
  |        + patEx
  + lib
  |   \
  |    + simpletest
  |    + patI18n
  |    + patTemplate
  |    + ...
  |
  + resource
  |        \
  |         + css
  |         + js
  |
  + template
  |        \
  |         + site.tmpl
  |         + Composite
  |         + Static
  |         + ...
  + test
  |    \
  |     + trial
  |     + unit
  |     + fit
  + var
  |  \
  |   + log
  |   + cache
  |   + tmp
  |   + vfs
  + Makefile
  + wbLoader.php

After you download and unpack (or checked out the source from the repository), you got heaps of files and folders. Don't be scared, there is no magic.

There is a bunch of folders in Wombat's root directory, namely: bin, doc, etc, etc-default, htdoc, include, lib, resource, template, test and var. Further more, there are two files: Makefile wbLoader.php

Traditionally the folder bin contains executable binaries and scripts

In doc you can find some documentation files, very few, to be honest.

As you might know from your local Linux installation, the etc holds all the configuration files. In Wombat all configuration files are in XML format. Also there is asecondary configuration folder named etc-default. Whenever a config file is loaded, Wombat tries to find it in etc, if it is not there, it loads it from etc-default (and throws an exception, if it is not there, too). The major benfit of this behaviour is that you can keep the default configuration next to a specific one without copying all the files. This way your concrete etc directory holds just a few files, which makes it easy to keep track of you changes. Hence it is strongly recommended to keep an empty etc folder in version control, if you use any.

The htdoc folder is the so called DocumentRoot (in Apache-slang) or web root. Actually, is is just a random name.

In the include directory you can find the source code of Wombat. So far, there are three subdirectories: WB, pat and patEx. in WB, you can find all classes with namne prefix "WB" those are the Wombat-classes. In pat you can find "pat*" Classes like patForms, patTemplate, etc. patEx contains extensions for "pat*"-Classes that belong to Wombat.

In the directory lib classes from othere sources are housed. Besides the source code of all the "pat*"-Classes, you can find Simpletest, as well.

The folder resource is populated with additional data, that you might need to display a proper web-page. Here you can find stylesheets (in css) and JavaScript (in js).

The template folder contains all the template files you need to create the HTML of you site. As you might have guesses, those are all patTemplate-Templates with the file name's extension ".tmpl"

in var, there is everything that might change. This where cache and temporay files are stored. This is why var and all it's sub-folders need to be writeable by you web-server. (Or the othere way around: The web-server cannot corrupt essential files because they cannot be modified by the web-server.)

Quite uncommon for a PHP-Project, there is a Makefile. Of course, there is nothing to compile, but make helps you to install Wombat and manage file permissions.

The first real PHP file you'll get in touch with is named wbLoader.php. Again, the file's name doesn't matter. This file is one you need to include in every script. After including wbLoader.php Wombat is set up and the features are ready to use.

Your own Files and Folders

Whenever you want to use the Wombat PHP Framework, think of it as it was a library - include it from the outside. In other words, create your own directory structure that suits your project, put Wombat somewhere nearby, copy wbLoader.php to your projekt folder and mend it that it can find "WB/Class.php"

You are not meant to develop inside the original Wombat folder! You can do almost everything from the outside. You have your own htdoc and configuration folder etc and etc-default (or whatever you name it). You can add custom classes or even override any class from the Wombat framework. Don't work inside the original Wombat folder, this folder is for Wombat developers only!. (This way you can use the same Wombat installation for multiple instances of custom web sites.)

As a user of Wombat, setting up a web-site usually boils down to the following steps:

1. Create a folder for your own project. This directory is called BASEDIR in this document. You usually need an template (which keeps your HTML template files), htdoc (or whatever you name it) folder and a place where you store you config files, etc and etc-default if you stick wtih the default name.
2. Optional folders in your project directory include (for you own extensions), resource (for css and js files),
3. Unpack Wombat somewhere and remember the location. This folder is called SYSTEMDIR.
4. Create wbLoader.php, actually, the name doesn't matter all that is important is that it includes WB/Class.php from the Wombat PHP Framework - in other words from SYSTEMDIR/include/WB/Class.php. Make sure this file is included from all your script (this adds another abscraction layer that helps to maintain your installation). It is probably a good idea to copy wbLoader.php from SYSTEMDIR to BASEDIR.
5. Wombat needs to get rid of log-messages and wants to store cache files etc. Therefore create a var folder in you BASEDIR. Also create the sub-folders tmp, log and cache and make sure that the web-server has write permission to var and all its children.