Physical Layout

The physical layout refers to how zoglair is organized at the file system level, as opposed to how it is seen from the outside world, via its web interface. With the exception of few core/bootstrap files, which are always loaded on start up, zoglair's code base consists entirely of plugin functionality. Every file contains one class (only) that is named after the file's relative path, prefixed with “z”. For example, the file “data/base.php” contains a class named “zDataBase”. Since there is a 1-1 relation between class and file names, zoglair takes advantage of PHP's auto-loading mechanism for making classes available just by using them! No need to preload anything or wonder if it is already loaded.

Here is how a stock zoglair installation is laid out on your disk drive:

The above structure is conceptually divided into the following levels:

1. At zoglair's installation root there are 3 files (.htaccess, index.php, license.txt) and 1 folder (zoglair). These are the absolute minimum (and necessary) items required to be at the root, for the system to be able to function. Everything else is placed under zoglair, so that the root image is as tide as possible.
   This level is collectively marked as Z_ROOT when naming file paths, and as “z” when naming classes.
2. In the next level (inside the parent directory, zoglair) there are no files, just folders. They are called group folders, because each one is a distinct group of plugins that defines a corresponding zoglair architectural layer, such as session handling, cache management, data modeling, etc.
   This level is marked according to the group name, both in paths and class names. The only difference is that, in class names, the group name is capitalized.
3. In the next level (inside group folders) there are both files and folders. Source files (*.php) are collectively called plugins and form the spine of zoglair. Each folder has its own class hierarchy, with a base class found in base.php. For example, the file “dbms/base.php” is the base class of database drivers, and is named “zDbmsBase”.
4. Some plugins are self-contained (they fit entirely in one source file), while others are designed in such a way that they can use external files for added functionality. These (external) files are collectively called extensions because what they do is to extend a plugin. They are saved on their own folder, named after the plugin they extend. For example, “clip/loop.php” is a file/class that is used for running various tasks that may take a long time to complete. It only provides basic functionality used by all loops. The actual functionality is in the form of extensions, found inside the “clip/loop/” subfolder.
5. Finally, some extensions can be further extended, the same way plugins are. These extension-extensions are collectively called includes. One such example is the folder “util/markup/media/” shown above, and this is the maximum depth zoglair can go, regarding its class hierarchy. If you take a look at this folder, you will find a file named “youtube.php”. If you open it, you will read the class “zUtilMarkupMediaYoutube”. As you see, it fully respects zoglair's class naming convention and is in sync with its location.

Summary:

• Plugins live in group folders (shown, above, with a bold typeface)
• Extensions live in plugin subfolders, named after the plugin they extend
• Includes live in extension subfolders, named after the extension in which they are included

Remarks:

• There are 3 group folders which - due to their nature - have special semantics and may deviate from the above:
  » the core group, because it contains zoglair's configuration and bootstrap code
  » the util group, because it contains mostly static utility classes
  » the var  group, because it contains static files (there is no php code there)
• HTML markup (and CSS) is confined in the following areas:
  » the clip group, because that is why it exists
  » the skin group, since it contains the page templates
  » the util/markup classes (limited markup, only)
• The only writable (and user specific) directory is var/domain
• The only place in zoglair where something is output, is a single echo command found in “core/zBootStrap.php” (that's a feature)!