Documentation of PHPBlosxom
Contents
PHPBlosxom is a clone of PyBlosxom written in PHP. It has the intention to be as compatible with PyBlosxom as possible, but to add some extra features and capabilities as well. In contrast to PyBlosxom, PHPBlosxom will ship with an administrator interface, which enables authors to write blogentries using a comfortable webbased editor. Of course it will still be possible to edit the blogentries using your favourite editor.
Index.php
This is the main engine of PHPBlosxom, all core functions are included in this file.
The configuration of PHPBlosxom is stored in the file config.php, which should be located in the same directory as the index.php file.
There are several callbackfunctions defined in this file, which can be used by the modules to perform some processing before or after some action. The callbackfunctions are:
- txtfile: Invoked when the list of weblogitems which are going to be displayed is assembled.
- rawEntry: Invoked when the rawdata of the weblogitems is read from the file. This callback is performed before the entries are processed by the main engine.
- processedEntry: Invoked when the data of the weblogitems is processed and resides in $validArray
- flavourLoaded: Invoked when the flavour is loaded.
- storyTemplate: Invoked for every displayed blogentry while it is rendered.
The information of the several modules is stored in the array Febduleinfo. Errors (which should be displayed to the users?) are stored in the array called $errors. The variable $dontrender specifies that the program does not render any textfiles.
After the most important arrays are initialized, the modules are loaded by the function autoLoadModules
Then, the server variable $_SERVER['PATH_INFO'] is processed in order to allow the use of nice urls. This part of the program sets the global variable $PATH_INFO and extract the required flavour (if it is given) which is stored in the global variable $flavour. When the contains ?flav= then the variable $flavour is set to the given value.
Now it is decided what we have to display. First the program checks if a single file is provided. If that is not the case, it is checked if the url provide a date which should be displayed. A regular expression is used for this check (why is the variable $PATH_INFO not used here?). If it is neither a single file or a date, the program assumed a directory is specified. When there is no file to be displayed, the program displays a 404-error (which can be argued). A nice message which tells the visitor there are no items which matches the requies is maybe more userfriendly.
If there are items to display, the program start rendering these items. First, it creates an array which consists of a timestamp and a filename. This array is sorted by the timestamp (ascending I presume). Then this array is cut down to a number of items defined in $config['numberOfItems'] using array_slice. Now is defined which files will be displayed, the program actually begins fetchin the contents of these files. This is stored in the array $validArray. Now the callback rawEntry is executed.
After that, the flavour which is used to display the data is loaded from disk (if this is enabled in config.php). PHPosxom flavour-style support is planned (according to the comments of the former maintainer), but I actually don't know what this means and I have the impression that the PHPosxom development is stalled for quite a long time, so I don't think support for this is a very high-priority task. I think we are better off supporting PyBlosxom and Blosxom flavours and stuff than to support a dead-project.
After the loading of the flavour, the callback function FlavourLoaded is called.
Now, the template replacement is done, using the function doGeneralTemplateReplaces. This function is implemented using several calls of str_replace, which maybe can replaced with a simple parser in order to speed things up (it is now probably O(number_of_template_vars * n), while it could be O(n) I think). Replacement is only done for $head and $foot. The header is hardcoded, but uses (optionally I presume, because flavour-support is not mandatory) content-type.* for the specified type. This enables users to use for example a .rss-flavour for .rss-feeds.
head.* is now send to the client-browser.
Now the individual blogentries are rendered. For each entry the callback 'StoryTemplate' is invoked.
Template Variables
In the files foot.* and head.* the following template variables are implemented:
- $blog_title - Title of blog
- $blog_description - Description of blog
- $blog_language - Language of blog
- $base_url - Base url of blog
- $url - Same as $base_url
- $path_info - Contents of $PATH_INFO variable, which is the appended directories after $base_url
- $flavour - Used flavour
- $version - Versionnumber of used PHPBlosxom
In the foot.*-template also the following variable is implemented:
- $exec_time - The amount of time the server spend rendering this page.
For the file content.* the following template variables are implemented:
- $fn - Relative filename of the blogentry (used for creating a permalink for example).
- $path - The path to the file of the current blogentry (this is essentially the category of the blogentry)
- 14:01tle - The title of the blogentry
- $body - The actual content of the blogentry
- docs/documentation - The path and filename of the current blogentry (also used for permalink creation)
- 14:01 - The time of the blogentry
- 2005 - The year part of the date of the blogentry
- Feb - The name of the month of the date of the blogentry
- Feb_num - The monthnumber of the date of the blogentry
- 21 - The daynumber of the date of the blogentry
- 14 - The hour of the blogentry
- 01 - The minute of the blogentry
Variables
$validArray contains the weblogentries which are displayed.
$validArray[nr]['timestamp'] - timestamp
$validArray[nr]['title'] - title
$validArray[nr]['entry'] - content of entry
$validArray[nr]['category'] - category of entry (directory names)
$validArray[nr]['relfilename'] - Relative filename of the file containing the current entry
$validArray[nr]['filename'] - Absolute filename of the file containging the current entry
$validArray[nr]['rawEntry'] - Raw contents of the file which containts the weblogentry
Functions
- autoLoadModules - Loads all modules in the directory $config['modulesdir']
- scanForDirs - Scans the $config['data'] directory for directories and store them in an array.
- scanDirForTxtFiles - Scans a given directory for textfiles.
- sortByTimestamp - Comparisation function used in combination with the function usort provided by PHP for sorting arrays.
- doGeneralTemplateReplaces - Replaces templatevariables in a given file.
