Jul's Page (Hungarian) » Packages » Blosxom.PHP » Guide

Guide to the Zen of Blogging in PHP

Introduction

Writing blog is simple. Publishing it – that is another case. You can use great web-based methods (like Blogger), or you can use a portal-type method (like Movable Type), or You can stay with obvious methods: just grab a text editor (TextEdit will be sufficient), and type there.

This latter type is Blosxom, which adds a clean way to blogging. It is in Perl, though, and many servers can run it just in CGI mode. I would say that not an elegant method. IMHO PHP is more prevalent in server side scripting in Web (through mod_php), than other scripting languages, and PHP gives a very web-aware environment.

There are other implementations of Blosxom in PHP, but I couldn't feel that every character in them go towards the goal. For this end I wrote Blosxom.PHP. Of course, I just search the Path.

The only thing was in my mind: it should be as familiar as possible to a human being. To write an entry, to write a comment, to browse archives should be as convenient, as possible.

Making the first steps

Getting it

The latest package can be found at Blosxom.PHP page, in tar.gz format. I don't want to give advice how to uncompress that. Stuffit Expander can unpack it, as Winzip, and as tar command line utility, of course.

Now you have a blosxom.php-1.0rc1 directory. Rename it as you like it, and put it to your web space, which can be accessed by web (your URL will be like http://example.com/blog/).

Getting familiar

Parts

Blosxom.PHP has four things: a main system (the smallest working piece), modules (which are extend functionality), flavours (which representate the system), and of course blog data.

The main system are the four PHP files which are in the root directory. Modules are separated to modules dir, flavours are separated to flavs dir. Blog data is held in datadir (see configuration).

Metafiles

Using metafiles is highly recommended. This metafiles system generates a database of your blog entries, with first appearances and titles. Just think about it a bit: in every request (eg. every time someone goes to your web page) you have to scan all of your blog entries, searching for the most recent entries. It is much easier to hold the most important data in a database. Besides, the last comments functionality requires such a database, to successfully write the name of the referenced blog entry.

The only problem with metafiles is to decide when this metafile should be regenerated. Of course, when a new blog entry is published, but you have to say something to Blosxom.PHP to recheck. For this end you can use a force file (if it exists, the next request will regenerate metafile), or you can give a force command (eg. http://example.com/blog/?cmd=force) to force regenerating. More on this is at Commands howto.

Sources system

If you have multiple authors, you can give them credit. Every author has a separate source (short name, an URL for e-mail or web address, a full name, and a blog entries path). This way each author can publish his/her own entries to his/her own path, without disturbing (or even knowing about) the others' blog entries. Every author can generate a new category simply creating a new directory.

Configure

A sample config file is in conf-dist.php, but the software reads it from conf.php: create it by copying conf-dist.php to conf.php.

conf.php just defines a $conf array with the following indexes:

title

This is the name of your blog. It will be in every header.

description

This is the short description of your blog. This will appear in every header too, just in smaller font.

language

Set here your primary language code. It is in RFC1766, but for shorthand: this is a two-letter language code, plus an optional two letter contry code separated by a dash. My personal blog is set to hu-hu, Austrians should use de-at, Brazilians should use pt-br.

charset

This sets the default character set. Old method was using Latin1 (ISO-8859-1) for Western European languages, but there are a lot Unicode-aware web browsers, text editors. UTF-8 (which is a Unicode encoding) is strongly recommended.

html_format

This is a boolean (eg. it can be true or false). If true, it assumed you write your blog entries in xhtml, so please put every paragraph into <p>…</p> tags. Soon to be deprecated.

datadir

This is where you can store data. This directory is have to be written by the web server, and you should not put this directory to a folder which is can be accessed without authorization. Personally, I put this directory to a WebDAV-accessible folder.

category_delimiter

When the category name is pretty-printed, you can specify a text which delimits category names from sub-category names. Default is / (Category/Sub-category).

moddir

This is where your modules are. In the early days every module were next to index.php. Now the module directory is in modules directory, by default.

flavdir

This is the same as moddir, but for flavours.

cssURL

This is an URL where your CSS is. If you have good design skills, you can generate a whole new page experience just using CSS. Just check css Zen garden.

metafile

Whether or not you are using metafiles. If no, say false. If yes, specify a Data Source Name: type:///path, where path is a database file name, which is relative to datadir. type is among of a lot of database formats, but your PHP installation will offer just a subset of them. Check your PHP configuration (see phpinfo()), and search for DBA (#module_dba) section (Supported handlers). You shouldn't use inifile nor cdb. If it doesn't support DBA, Blosxom.PHP's default database handler will take over.

categoriesfile

Use this if you want pretty-printed categories. If no, say false. If yes, specify the file name (you have to write this file: see How To chapter). It can be relative to datadir.

forcefile

Where your force file is kept. See Getting Familiar for more info.

depth

With this number, you can configure how deep is your category path. If you don't want categories, just write 1. If you want sub-categories (eg. Hobby/Skating, Hobby/Music), write 3 (one for datadir, one for main categories (Hobby), and one for sub-categories). If you don't want barriers, write 0.

entries

You can set how many blog entries will be shown in a page.

sources

With this you can add sources of blog entries separated by author. Each source have a single author. This data is an array indexed by author's short name:

array(
	 "rjh" => source descriptor for Random J. Hacker
	,"nji" => source descriptor for Not J. Important
)

Source descriptors are also hashed arrays, but with fixed indexes. Let's see Random J. Hacker's:

array(
	 "author" => "Random J. Hacker"
	,"link" => "mailto:rjh@example.com"
	,"path" => "/Users/rjh/blogentries"
	,"pass" => "s3cr3T"
)

To summarize: Random J. Hacker uses rjh as a handle, he has rjh@example.com e-mail contact address, and his blog entry dir is in /home/rjh/blogentries. He could set path to blogentries, which would pointed to datadir/blogentries. He can log in as “rjh”, with password “s3cr3T”.

modules

This is an array of strings, enumerating used module names. Module names are the file names of them, but you can omit .php extension (eg. Fortune)

How to? Using Blosxom.PHP

How to write?

Writing a blog entry can be very easy: First line is the title, second line is currently unused (it was author short name), and starting from third line will be the body. If you don't use html format, an empty line starts a new paragraph, a bare newline will be real newline. You can use inline HTML tags, too.

Keep in mind that only the first line will be published in RSS, RSS2, and Atom feeds.

How to give access to multiple authors?

Create a source for an author. If you have multiple authors, create multiple sources. Specify the author's short name in source identifier, author's full name, link to author, and the source path as described at “sources”.

Please note that all of these sources have to be read by the web server. It can be sufficient to give www group access to their blog entries directory, and set SGID to that dir.

How to categorize my blog?

If you simply put your blog entries as files into your blog entries directory, you don't have categories. But creating categories are easy: you can create a subdirectory, which will be a category. Of course, you can create a sub-sub directory, to have a sub-category. If you put your blog entries into a sub-directory, it will be apear in that category. Categories can be nested (eg. hobby for your all hobbies, hobby/skating is for your skating experiences).

To restrict category depth you can set “depth” configuration option. If it set to 0 (zero), you have unlimited category depth. If it is 1, you don't have categories, if it is 2, just the main categories are exist, if it is 3, you have one level of sub-categories, and so on.

By default category names are names of those sub-directories. But sometimes it is tiresome to give a long directory name, or you suffer from character set problems, or maybe just want to give a fancy name to your old, boring category. This is easily accomplished with “categoriesfile”. This is a file which lists your subdirectories and their names. Please note that you can specify just one name in a line, not the whole path.

For example you have hobbies (skating, music), you want to write about your study (geography, chemistry), and you have a rant and raves column. A directory structure can be this:

/hobby/skating
/hobby/music
/study/geog
/study/chem
/rants

If you want to give fancy names, you can create a categoriesfile:

/hobby = Hobbies
/hobby/skating = Rollerskating
/hobby/music = Zaka
/study = Studies
/study/geog = Geography
/study/chem = alChemistry
/rants = Rants and Raves

Then you decided to use ‘ › ’ as category separator (see category_delimiter). This way study/chem will be Studies › alChemistry, but study/math will be Studies › math.

How can I publish RSS/Atom syndication?

Out of the box! Blosxom.PHP has RSS1, RSS2, and Atom flavours to syndicate. You just have to specify a flavour:

http://your.address.com/blog/index.php?flav=rss

for RSS1 syndication,

http://your.address.com/blog/index.php?flav=rss2

for RSS2 syndication, and

http://your.address.com/blog/index.php?flav=atom

for Atom syndication.

What are commands? What can I do with them?

Commands don't have GUI, because of the simpleness, and because of security by obscurity. If you put a “Log in” button to your blog, everybody wants to click it. Like in kindergarden. Of course, you can create a custom flavour file, which contains these links. Your mileage may vary.

Commands are simple words, and you can give them with a simple GET variable, like this:

http://your.address.com/blog/index.php?cmd=force

In this example your command is force. Here's the list of available commands:

force: Forces regeneration of meta databases, like metadata, and comments-lastdb.
login: An author can log in to moderate comments.
logout: Log out author
del: Deletes a comment. Only a logged in author can delete comments from his/her blog entries.
move: (not implemented yet) moves a specific blog entry to another category. Only a logged in author can move his/her blog entries to existent categories.

How can I filter my blog entries?

There are a lot of filters you can use: there are author, category, date, entry filters.

Author filters

Author filters can be used to select blog entries from only one author, by his/her short name (see sources in Configure). It is implemented as a GET variable called “author”: http://example.com/index.php?author=author's short name.

Category filters

Just one category can be selected by calling http://example.com/index.php?category=/path/to/category. Before 1.0 final, this filter will be combined with entry filtering.

Date filters

There are three types of date filters: year, month, and day filter. Each filter has a simple date format: year have YYYY, month have YYYYMM, day have YYYYMMDD. Call http://example.com/index.php?date=year, month, or day filter.

Entry filters (also known as permanent links or permalinks)

There are two ways to give a permanent link to your blog entries: PHPosxom-way, and Blosxom way. If you click on ‘#’ or ‘New Comments’ or ‘n Comments’ link from the main list, you get a permalink in Blosxom way.

Blosxom's permalinks are easy:

http://your.address.com/blog/index.php/path/to/entry.txt

In PHPosxom, a much more easy method was implemented:

http://your.address.com/blog/index.php?entry=/path/to/entry.txt

Whilst Blosxom.PHP accepts old PHPosxom permalinks, Blosxom method is favored.

In 1.0 final, I'd like to implement a category filter in Blosxom way, and maybe a date filter too.

Modules

There are 7 modules which are packed with Blosxom.PHP. They extend main systems's functionality, and called by flavours.

ATuring

This is a simple Anti-Turing Test: it checks that you (a comment writer) is not a robot. Its working method is simple: it creates a simple session (not a builtin one, because you don't have access to fine-tune that) into a database, and generates a random number into it. It can display it with GD library in PNG, and it can check whether the number is good.