Site Structure

When a site is expected to grow past a few pages or functions, it's necessary to consider the way in which all the files will be laid out, and the data accessed. Since (as previously noted at http://www.phase.org/byjid/2640), Apache allows us considerable flexibility in mapping URLs to filenames, we effectively have two linked sets of decisions to make.

In making the decisions, we have various considerations to take into account:

Firstly, some file considerations:

1) The files need to be laid out in a logical fashion, so that new developers, and previous developers coming back to the site, can easily find the code they need to work on.

2) The code should be modular in layout, so that separate modules can be plugged in or copied out for use in other sites, and to facilitate division of the code into sub-projects for simultaneous development.

3) Code re-use should be maximised - core functions will need to be kept in a central library, and functions within modules made available to all files within that module.

4) Most modules will have two interfaces - a display interface and an administrative interface.

Similarly there are considerations in the way users view the resulting pages:

5) We want to be able to display features of different modules within one page, and so setting URLs for output pages that include the module name won't always be an ideal solution.

6) On the flipside, many pages will be closely linked to one module, and so the option for modular paths is still useful. For example, if we have a 'journal' module (the only module already in place on this site), we might want to find pages at /journal/byday and /journal/byjid. If we have multiple journals, we might want /journal/name/byday and so on. These are non-trivial decisions and will vary between different sites. To update this journal, we could use a path of /journal/update, a form that works well for many modules.

7) So far we have designed some highly structured paths for some dynamic modules, which suits us because we know what the structure of these modules will be. If, conversely, we have user-designed areas (eg, content produced via a CMS), we cannot pre-emptively plan paths - we will most likely need to generate paths with page numbers (eg /page/1234). We can modify these same pages with the /update "switch", eg /pages/1234/update.

To gather together and expand on what we've said so far:

We're looking at a URL structure of /module/options - with at least one "default" option of "update".
We do not have .php, or any file extension, visible within our paths.
We will require one "special" page at the web root (URL: /) that provides our site's default page.
We need to ensure that our files do not clash with unrelated URLs.

For this project, we will use rather a loose binding between URL and file structure. In fact we're hardly going to put any files within the web tree.

This isn't the way most people would write their personal website, but we're after rather a different sort of site here - we're building up code that could be used in professional and commercial applications. (As an aside, I should probably point out that we're not hiding the directory structure or .php extension because we're ashamed of it, or because it's in any way unsuited to commercial-grade use, but because this information is of no real use to the user).

The directory structure we will use is as follows (shown from the root directory of our project):

/backend : most of our code will live in this directory, to keep it out of the web tree. Each module will live in a subdirectory of this folder, as well as special folders for /user (the user management code) and /core (the code library)
/frontend : this is where the webserver root will point to. It will contain a /index.php file as a default page, and a set of symlinks, which match the names of the modules, and point to /backend/module/index.php

It should be noted that this isn't the only, or indeed the optimal, way to write such a project. However the more optimal techniques can wait for a later entry - we're not trying to do everything at once in this project, even if we might do so if it were "for real". By necessity the incremental nature of this journal will mean we don't always take "intuitive leaps" to get straight to the ideal solution, instead taking smaller steps that are easier to document and follow. (It is for this reason that the structure of posts so far has been very simple - essentially plain text).

One final note in this design stage - we've already defined a couple of URLs that don't fit into the design - /byjid and /byday. For backward compatibility we'll leave these operational and symlink them to the new locations.

Having designed the directory layout, and moved our existing files into place, we are almost ready to start using CVS to control the project. In the next entry - before we start coding in anger - we'll set up a development environment to support this.

(Update: OK, so not in the "next" entry. But we'll tackle it as a priority before we end up writing a vast amount of code. And we'll probably use Subversion in preference to CVS.)
Posted by parsingphase, 2004-05-09 16:12

Anonymous user

Login

Blog

Contact

I'm currently available for contract work in London as a Senior PHP Developer. Contact me for a CV, rates, or a chat.

Twitter @parsingphase
Email richard@phase.org
Github parsingphase
LinkedIn Richard George
Flickr parsingphase