Table of contents

Introduction

Poster is a blog engine written in PHP. Unlike most similar applications, Poster doesn't require a database to work, so you can use it with any host that allows users to run PHP scripts; virtually all paid hosts do, as well as most free ones.

You can customize Poster to the limit using its flexible templating system, and integrate it into an existing site.

Despite its small size, Poster has most of the features you could expect from a modern blog engine; you can manage your blog from everywhere using its web interface, which is based on valid XHTML 1.1 and CSS.

Poster is designed to be elegant, fast, easy to use, and it's Free Software (free as in speech), so you can use it without charge and modify it to fit your needs.

Installation

Installing Poster is really simple. First, upload the whole content of the tarball to your site, then make sure the directory you uploaded the files into is writable by PHP (the setup will check this for you; if unsure, chmod it 0777).

Then point your browser to setup/index.php and follow the instructions. If you are upgrading from an older version of Poster, you may need to perform additional actions. See the upgrading section for more details.

When you are finished installing, you should remove the setup/ directory and restore the original permissions of the install directory. Please note removing the setup/ directory and its whole content is really important for security reasons: if you don't remove the installation scripts, everyone will be able to gain full access to your blog and edit/delete all your data.

Permalinks

A blog is structured in a way that the index (the page you see when you point your browser to the blog's URL) changes everytime you write a new post, and old posts disappear soon from the index. Therefore there is the need of a way to link directly to a post, so you can read it everytime you want without going throught the whole blog: this kind of link is called permalink, that is, an URL which is unique to the post and is valid as long as the post is not deleted.

A permalink to a post is an URL similar to http://something/index.php?post=POST_ID, where POST_ID is the post's ID, but there are many other types of permalinks available in Poster – for comments, trackbacks, categories and authors: this type of permalinks will be described in the relative sections.

Anyway, you don't have to care too much about this stuff, since permalinks are automatically generated by Poster and can be inserted in your template using tags (see template).

Users

Poster can handle different users on a single blog. Each user has a set of permissions to define exactly which actions the user is allowed to perform. If an user has enough permissions to edit other users, he can also change that user's permissions, but nobody can change his own permissions.

The permissions needed to create/edit/delete users and to edit the configuration should be given only to people you trust, or even better, to nobody except you. Each user has a login and a password: the login is used to generate the permalink to that user's posts, and must be a single lower–case word. The name of the user can contain spaces and strange characters, while the link is usually the URL of the user's site or main blog.

The permalink to see all the posts written by an author is in the form http://something/index.php?author=AUTHOR_LOGIN, where AUTHOR_LOGIN is the login of the user.

Categories

You can create different categories to sort your posts. Each category has a short name (which is used in category permalinks and must be a single, lower–case word) and a long name, which can contain also strange characters and be more descriptive. The default category, "General", cannot be deleted.

The permalink to a category is something like http://something/index.php?category=CATEGORY_SHORT_NAME, where CATEGORY_SHORT_NAME is replaced with the category's short name.

Comments

Comments to a post can be done by anyone, given you have enabled comments for that post. If no name is given while posting a comment, the default user "anonymous" is considered the author of the comment. If the comment is posted by a logged user, the form is automatically filled with the user's info.

The "Preserve linebreaks" checkbox is used to keep the comment's formatting: if this box is checked, every line break is converted into a <br /> tag while saving the comment (this option is active in Poster's default template starting since version 1.0.7).

You can use any HTML tag inside a comment, provided it is part of the list of allowed tags.

The permalink to a comment is in the form http://something/index.php?comment=POST_ID#_COMMENT_ID, where POST_ID is the ID of the post the comment refers to, and COMMENT_ID is the ID of the comment itself.

Trackbacks

When you write a post, you can chose if that post should recieve trackbacks or not. You can also send pings to other blogs when you write a post.

There is a form people can use to send pings to the post – this is useful if they are using a blogging application unable to send pings or if the person sending a pingbacks wrote a page on his site rather than a post on his blog (note: this form is commented out in the default template starting from Poster 1.0.7).

A trackback permalink is similar to http://something/index.php?trackback=POST_ID#_TRACKBACK_ID, where POST_ID is the ID of the post the trackback refers to, and TRACKBACK_ID is the ID of the trackback itself.

Template

Poster uses a modular templating system were each part of the blog has his own template file. This allows a great amount of flexibility, and allows you to integrate a Poster blog in an existing site without too much effort.

The markup code contained in the template file is inserted in the correct place after replacing any known tag with the current value of the corresponding variable; tags are essentialy placeholders mapped one–on–one on variables containing pieces of information you can display, and are in the form <$SomeThing$>.

Each template file is a PHP script, so you can insert PHP code inside a template file and that code will be executed on the fly before replacing tags. An example of this is in template/archive.php in the default template, where PHP code is used in order to print the name of the month.

You can edit your blog's appearance using only HTML if you're not a PHP programmer, but people with PHP knowledge will get the best out of Poster's templating system. If you want to learn more about Poster's templating system, you can read the template reference.

Spam filters

Poster features two different spam filters: a blacklist based one, and a CAPTCHA based one. They can both be enabled at the same time, providing extra security.

The blacklist based filter is effective against spam with recurring patterns: for example, you can block the word "viagra" if you get a lot of spam containing that word. The blacklist filter uses Perl regular expressions that are matched case–insensitively against the comment's body. If any of the blacklisted expression matches, the comment is rejected.

The CAPTCHA filter provides a simple yet effective way of blocking spam; the downside is that it breaks compatibility with textual browsers, and is not accessible for the visually impaired. You can customize the colors of the CAPTCHA image to match your template.

Proably the most effective way to block spam is to disable comments and trackbacks for every post except the lastest one. This approach may not be feasible for everyone, but makes the amount of spam almost drop to zero.

Feeds

There is an RSS 2.0 feed placed in feed/rss.php. This feed is dynamically generated when you request it, and can be used to track the blog's updates.

You can see only the updates in a category or from an author, using the same syntax of blog's permalinks.

I would like to provide also an Atom feed, but I miss the needed knowledge about syndacation formats, so any kind of help is really appreciated.

Known bugs

If you create a post enabling the "Preserve linebreaks" option (which is disabled by default), and you later edit it, you'll find that all the linebreaks has been converted into <br /> tags. This means you can't enable the option again, unless you want to manually delete every <br /> tag present in the post's body before saving.

Upgrading

A new setting, $TimeOffset, has been introduced in this release: if you're upgrading from Poster 1.0.11, you can do so easily by replacing the include/, admin/ and feed/ directories, along with the index.php file, and then adding the line $TimeOffset = '+0'; to your config.php file.

Your data will not be touched at all; however, making a backup copy of your data/ directory from time to time is always advised.

Contact me

If you need any kind of help with Poster, if you find a bug, if you have an idea for a good feature you wish was present in Poster, or for any other Poster–related stuff, feel free to mail me: eof@kiyuko.org.