PunBB 1.3 extension development

A PunBB extension is a folder containing some files. The folder is named after the extension ID and is placed in the extensions directory within PunBB.

The main file of an extension is the manifest file, manifest.xml. It is to be directly in the extension folder.

The manifest file is a regular XML file that contains information about the extension, such as author name, short description of what it does, and what version of PunBB it requires. It also has information about hooks, and how PunBB should use them.

<?xml version="1.0" encoding="UTF-8"?>
 
<extension engine="1.0">
  <id>example_extension</id>
  <title>Example Extension</title>
  <version>0.1</version>
  <description>This is a short description of the extension.</description>
  <author>John Doe</author>
  <minversion>1.3</minversion>
  <maxtestedon>1.3.4</maxtestedon>
  <dependencies>
    <dependency>another_extension</dependency>
  </dependencies>
  <note type="install">Add notes before the user installs the extension</note>
 
  <hooks>
    <hook id="vf_start"><![CDATA[
	// Include a file from the extension directory
	require $ext_info['path'].'/foobar.php';
    ]]></hook>
    <hook id="vf_pre_header_load"><![CDATA[
	// Call a function from foobar.php
	foobar_function();
    ]]></hook>
  </hooks>
</extension>

Now we will break this down:

<?xml version="1.0" encoding="UTF-8"?>

This is the basic XML declaration that describes what version of XML the document follows, and what character encoding is used. Since PunBB has full support for UTF-8 from version 1.3 onwards, you should use UTF-8 encoding.

<extension engine="1.0">

This tells PunBB which extension engine the extension was designed for. This is required in case the PunBB extension system is significantly changed in the future (making old extensions incompatible). The current extension engine version is 1.0.

<id>example_extension</id>

This is an identifier of the extension. PunBB uses this for identifying each of your installed extensions, so it should be unique. Note that the extension directory should be named after the extension ID. A good idea would be to use only lowercase letters and the underscore character “_” for spaces. The ID cannot be more than 50 characters long.

<title>Example Extension</title>

This is the title of your extension. Use your imagination.

<version>0.1</version>

The version number of your extension. You should follow the version numbering rules in determining what version number to use.

<author>John Doe</author>

This is your name. Does not require that much imagination now, does it?

<minversion>1.3</minversion>
<maxtestedon>1.3.4</maxtestedon>

The minimum version of PunBB the extension requires, and the maximum version it was tested on. If your PunBB version is lower than minversion or maxtestedon, PunBB gives you a warning when installing the extension.

  <dependencies>
    <dependency>another_extension</dependency>
  </dependencies>

This tells PunBB to only allow this extension to be installed if the given dependencies are both installed and enabled, it will also stop any given extensions being uninstalled or disabled while this extension is running.

  <install><![CDATA[
    // Installation code
  ]]></install>

One important thing to note about the install procedure is it will be repeated when upgrading, therefore it should check before it does anything that only needs to be done once. You can detect an upgrade by the constant EXT_CUR_VERSION.

  <uninstall><![CDATA[
    // Uninstallation code
  ]]></uninstall>

Hooks are special “tags” in the PunBB code, that can be replaced with any piece of code specified in a manifest file. A typical hook looks like this:

($hook = get_hook('vf_start')) ? eval($hook)) : null;

What you need to pay attention to here is ”vf_start”. This is the name of the hook. In this case, the hook resides in the beginning of viewforum.php (thus the prefix “vf_”). If you were to replace that hook with a code snippet of your own, you will need to remember this name for the manifest.

<hooks>
  <hook id="vf_start"><![CDATA[
	// Include a file from the extension directory
	require $ext_info['path'].'/foobar.php';
  ]]></hook>
  <hook id="vf_pre_header_load"><![CDATA[
	// Call a function from foobar.php
	foobar_function();
  ]]></hook>
</hooks>

The hooks section tells PunBB what to do with the hooks. It has subsections for each hook used in the extension, identified with their name. The PHP code with which the hook is replaced with resides in the CDATA section (identified by the <![CDATA[ and ]]> tags). That is, the hooks vf_start and vf_pre_header_load will be replaced with anything you enter in their respective CDATA sections.

This example uses two hooks, both in viewforum.php. The first hook (vf_start) simply includes a PHP file from the extension directory. As you can see, we use $ext_info['path'] to get the path to the extensions folder. The second hook simply calls a function called defined in foobar.php.

In addition to “merely” adding functions through external files, hooks allow you to circumvent PunBB's core functionality, and replace them with your own. For example, you can use temporary variables to get around the BBCode parser, and replace it with a completely different parser.

If you want to repeat code in multiple hooks you can do it by separating the hook names with a ”,” the code below shows how to use the same code in vf_start and vt_start.

<hooks>
  <hook id="vf_start, vt_start"><![CDATA[
	// Do something in both viewforum and viewtopic
  ]]></hook>
</hooks>

When using hooks we can also specify a priority for our code. Priority is useful in avoiding conflicts with other extensions. For example, if your code tries to return a value, in most cases you would want your code to run last so as not to prevent other code from executing.

Priority ranges from 1 to 10, with 1 specifying code that should be run first and 10 specifying code that should be run last. If two extensions specify the same priority for the same hook, their installation order determines which runs first. The default priority is 5. An example of how to set priority is shown below.

<hooks>
  <hook id="vf_start" priority="2"><![CDATA[
	// Include a file from the extension directory
	require $ext_info['path'].'/foobar.php';
  ]]></hook>
</hooks>

Every extension is provided with the $ext_info array, which contains information about the extension.

• You must not use includes in the uninstall process, since the code within the uninstall hook is copied to the database upon installation (and thus must be able to be run by itself). All of the code for these must be contained within the manifest.xml file.
• When using includes in hooks it's recommended in general to include functions and libraries.

If the extension contains any strings that could be translated these should be put in a language file. The structure for language files is extensions/ext_id/lang/Language.php, for example extensions/example_extension/lang/English.php. The language file would then contain

<?php
 
$lang_example_extension = array(
   'Example 1'   =>   'An example language string',
);

To include the language file the following code would be used

if (file_exists($ext_info['path'].'/lang/'.$forum_user['language'].'.php'))
   require $ext_info['path'].'/lang/'.$forum_user['language'].'.php';
else
   require $ext_info['path'].'/lang/English.php';

It is important your extension work in all 3 database systems supported by PunBB. To do this, you should use the helper functions provided in the database abstraction layer as much as possible.

Extension versions should be numbered in the same format as PunBB, that is for example 1.2.3 where 1 is the major version, 2 is the minor version and 3 is the release. Extensions in beta stages should be numbered 0.x.x, each time new functionality is added the minor version should be increased, and after a full/major rewrite the major number should be increased. Small bugfixes should increase the release number.

Extensions in PunBB can be disabled from the administration panel or via a constant in config.php. This action does not uninstall the extension but simply turns off its hooks. It is important you think about this situation when coding your extension. As a result, in general you can not perform destructive actions on the core database (eg: remove the Guest user, delete a core configuration value, shrink a column to an unusable size, drop a table or column, etc).

It is also important to make sure that any files in your extension that are accessed directly return some form of error message if they are accessed when the extension is disabled.

When writing extensions it is important you think about the task your extension will perform, where possible try to do one task and do it well. When writing more complex extensions it is best to break them down into multiple extensions and use dependencies to combine them. For example a donation extension could be separate from a cash extension but depend on it. Then users who do not want the donate function can choose not to install that part.

Even extensions themselves can be extended. Use hooks in your extension to give other developers the chance to enhance your extension. Hooks of extensions can be used exactly like normal hooks. To guarantee that the extension you extended is available, add dependencies to your manifest.

1. Create the wiki article for the extension and write the general idea and the specification there.
   • The page url must be http://punbb.informer.com/wiki/punbb13:extensions:<extension_id>, e.g. http://punbb.informer.com/wiki/punbb13:extensions:pun_pm.
   • You may also start the discussion in Forums to ask users to add their feature requests to the specification.
2. Add the ticket to the Trac (or just start a text file, if you have no Trac). List the main tasks to complete the extension.
3. To be invented: Create the automatic test (e.g. using pun_admin_simpletest) for all the features in your task-list.
4. Code them all! Follow your task-list and strike out done.
   • Commit your changes to the SVN separately: one feature or one bug fix is one commit. Do not commit multiple changes simultaneously.
   • BTW: Use SVN or other VCS. (I personally prefer Bazaar.)
5. Add the documentation to the wiki article.
   • Extension usage.
   • Extension customization and integration.
6. Publish extension in the extension repository (as soon as it passed all the automatic tests).
   • Third-party developers may propose their extensions to be reviewed and published in the repository.
7. Release the extension in Forums.

• PunBB 1.3 Extensions

This description is mainly based on the FluxBB documentation. We express our thanks to the FluxBB development team.