PHP Headliner

PHP Headliner - Manual

Overview

Headliner is a PHP component which provides a web-based portal to usenet news. This guide provides detailed configuration instructions. For a fast route to installation, please read the Quick Start guide.

Licence

Headliner is circulated under the GNU General Public Licence (GPL).

Requirements

  • PHP 4.3 or greater
  • MySQL 3.23 or greater
  • Access to an NNTP news server
  • cron job or scheduled task capabilities are recommended

Installation

Extract to server

  • Extract the downloaded PHP Headliner archive into a directory on your webserver
  • Locate the file MyConfig.php and edit the following variables:
    • $this->mysqlServer - The MySQL server that you will use for storing data (usually localhost)
    • $this->mysqlUsername, $this->mysqlPassword - The username and password for this MySQL connection
    • $this->mysqlDb - The database where you have installed the Headliner schema
    • $this->nntpServer - The NNTP server that you will read messages from and post messages to
    • $this->nntpUsername, $this->nntpPassword - The username/password for this news server. If anonymous access is permitted to this news server, leave both of these as empty strings
    • $this->rootURL - the fully-qualifed URL for your PHP Headliner installation (no trailing slash), e.g. http://www.myserver.com/headliner

Scheduled tasks

PHP Headliner needs to be able to periodically load articles from the news server. Also, the cache and read-articles lists need to be purged periodically. The two PHP files in the tasks directory should be executed periodically, this is best done through a cron job, for example: 

# Every five minutes, query the news server
*/5 * * * * /usr/bin/php ???/headliner/tasks/synchronise.php

# Every night purge the caches
0 1 * * * /usr/bin/php ???/headliner/tasks/purge.php

Your must of course replace the '???' above with the installed location of PHP Headliner.

A cron job is a scheduled task that is created by inserting an entry into a crontab. Access to the crontab in order to create cron jobs is a typical feature of most commercial Linux/Unix hoting packages. If you do not have access to this facility, you should ask your service provider whether they can provide it.

If you do not have access to a crontab or other means of scheduling the above scripts, you can edit 'index.php' at the commented lines so that the news server is querried each time the page is loaded. However, this is not an ideal solution as it will make your site run a bit slower.

Configure groups

The next step is to configure the groups which you wish to provide a portal for. Within MyConfig.php edit the $this-groups array to include your desired groups. Take care to read what the 'posting' and 'type' fields are for.

The following code snippet shows how to configure Headliner to provide a portal to two USENET groups (rec.juggling and rec.gardens) and two local (non-USENET) groups: 

$this->groups =	array (
  "1" => array("name" => "rec.juggling",
    "description" => "a readonly USENET forum for juggling and related circus arts",
    "posting" => DISABLED),
  "2" => array("name" => "rec.gardens",
    "description" => "a readonly USENET forum for gardening chat",
    "posting" => DISABLED),
  "3" => array("name" => "local.headliner.test",
    "description" => "a local (non-USENET) forum for test posts",
    "posting" => ANON,
    "type" => LOCAL),
  "4" => array("name" => "local.headliner.help",
    "description" => "a local (non-USENET) forum for help with, or questions about Headliner",
    "posting" => ANON,
    "type" => LOCAL)
);

Construct Schema

Once the groups have been configured, you must run a script whcih will generate the required database schema. Simply execute the file ???/headliner/setup/createschema.php, either through a console, or from your browser.

Test

You should now be able to navigate to your installation directory of Headliner and see the list of groups which you configured. In order to populate these groups perform an initial run of the schedule task headliner/tasks/synchronise.php (if you are using scheduled tasks for this purpose).

Applying templates

It is a relatively straightforward task to configure Headliner so that it blends in with your existing website template. The following files are used by Headliner to render pages: 

index.php
search.php
rightpane.php
leftpane.php

All these files following the same pattern as illustrated in the following example:

<?
	// construct the Headliner GUI class;
	require_once("lib/NewsReaderGUI.php");
	$gui = new NewsReaderGUI();
?>
<html>
<head>
	<title>News Reader</title>
	<link rel="StyleSheet" href="docs.php?f=docs/news.css"  type="text/css">
	<?
		// obtain any javascript required by this page
		$gui->javaScript();
	?>
</head>
<body <? echo $gui->bodyEvents(); ?>>
<?
	// render the page
	$gui->display();	
?>
</body>
</html>

The format of the page can be changed in any way, with extra GUI elements such as menus added. However you must ensure that the NewsReaderGUI is constructed before any of the page is output because NewsReaderGUI initiates the session. Furthermore, you must ensure that calls to $gui->javaScript() etc... are still called in the correct place within the page.

Configuration

All configuration changes to Headliner should be performed by modifying MyConfig.php. This php class inherits the standard configuration from lib/Config.php. You will find all the configuration variables listed within lib/Config.php together with a brief comment of their purpose. If you wish to change any from the default, simply copy them across from lib/Config.php into MyConfig.php and make the desired change. For example the default number of items within the RSS feed is 50, as seen in lib/Config.php:

class Config 
{
  ...
  // the number of articles to include in an RSS feed
  var $rssArticleCount = 50;
  ...
}

If for example you wish to include just 10 items within the RSS feed, override the default within the constructor of MyConfig.php as follows:

class MyConfig extends Config
{
  function MyConfig()
  {
    ...
    $this->rssArticleCount = 10;
    ...
    
    // call the super-class constructor
    $this->Config();
  }
}

Some of the more important configuration changes are detailed below. However a definitive list of configuration changes can be seen by looking at the code for lib/Config.php itself.

Data caching

The construction of thread trees and reference lists can be a time consuming process if Headliner is being used as a portal for busy groups with a lot of traffic. In order to improve performance Headliner has a data cache which stores thread trees and other generated data. This is enabled by setting the persistence type to MYSQL_CACHED within MyConfig.php

$this->persistence = MYSQL_CACHED;

There are a couple of variables that can be sued to tune the cache. The first is cacheMaxUnusedDuration, which specifes the number of days that a piece of data will be held in the cache without it being used. The second is cacheMaxDuration which specifies the number of days that a piece of data will be held in the cache regardless of how often it is used.

If caching is being used it should be ensure that the purge task, tasks/purge.php is executed on a daily basis.

Marking of read articles

By default, all articles read by anonymous or authenticated users are marked as read. The IP address of anonymous users is used to store their read article list. The marking of read articles for anonymous users can be disabled by changing readArticlesAnonymous to false.

The read article 'flags' are stored in the database for a 30 day period as a default. This can be changed by modifying readArticleDuration to the desired number of days.

The purign of the read article 'flags' is performed by the purge task, tasks/purge.php. Therefore it should be ensured that thsi task is executed on a nightly basis in order to prevent the read articles growing to an excessive size.

Authentication

Currently PHP Headliner does not provide a mechanism for user authentication, i.e. it does not store lists of users with passwords or present a login screen. Instead, it is designed to plug in to an existing authentication system. To provide plug in to an existing authentication service you must implement the getCredentials methods within MyConfig providing the username, email and ID of the user as obtained from their session