Developer Information
Information for developers to enhance your existing PunBB
installation.
Table of Contents
Syndication
This script extern.php is used to include information about
your board from pages outside the forums and to syndicate news
about recent discussions via RSS. The script can display a list
of recent discussions (sorted by post time or last post time), a
list of active users or a collection of general board statistics.
The script can be called directly via an URL (for RSS), from a
PHP include command or through the use of Server Side Includes
(SSI).
The scripts behaviour is controlled via variables supplied in
the URL to the script. The different variables are: action (what
to output), show (how many topics to display), forum (the ID of
the forum to poll for topics) and type (output as HTML or RSS).
The only mandatory variable is action.
Possible/default values are:
- action: active (show most recently active
topics) (HTML or RSS)
new (show newest topics) (HTML or RSS)
online (show users online) (HTML)
online_full (as above, but includes a full list) (HTML)
stats (show board statistics) (HTML)
- show: Any integer value between 1 and 50.
This variables is ignored for RSS output. The default is
15.
- fid: One or more forum IDs
(comma-separated). If ignored, topics from all guest-readable
forums will be polled.
- type: RSS. Anything else means HTML
output.
Here are some examples using PHP include().
- Show the 15 most recently active topics from all
forums:
include('http://host.com/forums/extern.php?action=active');
- Show the 10 newest topics from forums with ID 5, 6 and
7:
include('http://host.com/forums/extern.php?action=new&show=10&fid=5,6,7');
- Show users online:
include('http://host.com/forums/extern.php?action=online');
- Show users online with full listing of users:
include('http://host.com/forums/extern.php?action=online_full');
- Show board statistics:
include('http://host.com/forums/extern.php?action=stats');
Here are some examples using SSI.
- Show the 5 newest topics from forums with ID 11 and
22:
<!--#include
virtual="forums/extern.php?action=new&show=5&fid=11,22"
-->
- Show board statistics:
<!--#include virtual="forums/extern.php?action=stats"
-->
And finally some examples using extern.php to output an RSS
0.91 feed.
- Output the 15 most recently active topics:
http://host.com/extern.php?action=active&type=RSS
- Output the 15 newest topics from forum with ID=2:
http://host.com/extern.php?action=active&type=RSS&fid=2
Website Integration
Integrating PunBB into your website code is easy if you know
a little PHP. By including PunBB's script common.php, you gain
access to all PunBB global variables such as $db and $pun_user.
However, in order to include this file, you need to define a
constant called PUN_ROOT. This constant should be set to the
relative path to your PunBB forum directory. For example, if
your website front page is located in /home/user/public_html/
and your forums are located in /home/user/public_html/forums/,
your PUN_ROOT should be './forums/'. The PHP code to accomplish
this could look something like this:
define('PUN_ROOT', './forums/');
require PUN_ROOT.'include/common.php';
Once you've included common.php, you can access and utilize
all of PunBB's global variables and functions. Typically, you
will be most interested in the $pun_user array. This array holds
information about the current user. Another interesting variable
is the database object $db. How to use these variables in your
own script is out of the scope of this document, but here's a
small example showing you how to print a simple message greeting
the current user on your website front page:
Hello <?php echo pun_htmlspecialchars($pun_user['username']); ?>!
In addition to defining PUN_ROOT, you can define a number of
other constants to alter the behaviour of PunBB when including
common.php. The two most interesting of these constants are
PUN_TURN_OFF_MAINT and PUN_QUIET_VISIT. If PUN_TURN_OFF_MAINT is
defined when including common.php, PunBB will not exit and
display the maintenance message if the forums are placed into
maintenance mode. You generally don't want this message to appear
on your website front page, so defining that constant is a good
idea. The other constant, PUN_QUIET_VISIT, prevents PunBB from
updating the current user's last visit data in the database so
that a visit to the front page doesn't count as a visit in the
forums. This is also desirable behaviour in most cases. It
doesn't matter what value you set these constants to, but setting
them to a value of 1 is probably a good idea. Example:
define('PUN_TURN_OFF_MAINT', 1);
define('PUN_QUIET_VISIT', 1);
Please note that these constants must be defined before
common.php is included.
Admin Plugins
Admin plugins are modules for the PunBB admin interface that
can be installed by simply dropping the plugin script in the
plugins/ directory. See the example plugin for information on how
to write your own plugin. Here are a few notes of interest for
aspiring plugin authors:
- If you want to display a message via the message()
function, you must do so before calling
generate_admin_menu($plugin).
- Plugins are loaded by admin_loader.php and must not be
terminated (e.g. by calling exit()). After the plugin script
has finished, the loader script displays the footer, so don't
worry about that. Please note that terminating a plugin by
calling message() or redirect() is fine though.
- The action attribute of any and all <form> tags and
the target URL for the redirect() function must be set to the
value of $_SERVER['REQUEST_URI']. This URL can however be
extended to include extra variables (like the addition of
&foo=bar in the example plugin).
- If your plugin is for administrators only, the filename
must have the prefix "AP_". If it is for both administrators
and moderators, use the prefix "AMP_". The example plugin has
the prefix "AMP_" and is therefore available for both admins
and moderators in the navigation menu.
- Use _ instead of spaces in the file name.
- Since plugin scripts are included from the PunBB script
admin_loader.php, you have access to all PunBB functions and
global variables (e.g. $db, $pun_config, $pun_user etc).
- Do your best to keep the look and feel of your plugins'
user interface similar to the rest of the admin scripts. Feel
free to borrow markup and code from the admin scripts to use in
your plugins.
- Plugins must be released under the GNU General Public
License or a GPL compatible license. Copy the GPL preamble at
the top of this file into your plugin script and alter the
copyright notice to refrect the author of the plugin (i.e.
you).
Database Tables Reference
The following is a complete list of all PunBB database tables
and their respective fields. Primary key fields are
underlined.
bans
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| username |
varchar(200) |
NULL |
The username this ban applies to. |
| ip |
varchar(255) |
NULL |
The IP address(es) or partial IP address(es) this ban
applies to. |
| email |
varchar(50) |
NULL |
The e-mail address or e-mail address domain name this
ban applies to. |
| message |
varchar(255) |
NULL |
A message that is displayed for the banned user. |
| expire |
int |
NULL |
A UNIX timestamp representing the day when the ban
expires. |
categories
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| cat_name |
varchar(80) |
'New Category' |
The name of the category. |
| disp_position |
int |
0 |
The vertical display position of the category (relative
to other categories). |
censoring
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| search_for |
varchar(60) |
|
The term to search for. |
| replace_with |
varchar(60) |
|
The term to replace search_for with. |
config
| Field |
Type |
Default |
Description |
| conf_name |
varchar(255) |
|
The name of a configuration variable. General
configuration options start with the prefix o_ and general
permission options start with p_. |
| conf_value |
text |
NULL |
The value of the configuration variable
conf_name. |
forum_perms
| Field |
Type |
Default |
Description |
| group_id |
int |
|
The user group for which these permissions apply.
Primary key identifier together with forum_id for this
table. |
| forum_id |
int |
|
The forum in which these permissions apply. Primary key
identifier together with group_id for this table. |
| read_forum |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| post_replies |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| post_topics |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
forums
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| forum_name |
varchar(80) |
'New forum' |
The name of the forum. |
| forum_desc |
text |
NULL |
A description of the forum. |
| redirect_url |
varchar(100) |
NULL |
The URL to redirect users to upon clicking the forum
link on the index page. |
| moderators |
text |
NULL |
A serialized PHP array of moderators. |
| num_topics |
mediumint/int |
0 |
The number of topics the forum contains. |
| num_posts |
mediumint/int |
0 |
The number of posts the forum contains. |
| last_post |
int |
NULL |
A UNIX timestamp representing the date/time the last
post was made in the forum. |
| last_post_id |
int |
NULL |
The ID of the last post that was made in the
forum. |
| last_poster |
varchar(200) |
NULL |
The username (or guest name) of the user that made the
last post in the forum. |
| sort_by |
tinyint/smallint |
0 |
0 = Display topics sorted by last post. 1 = Display topics sorted by topic start. |
| disp_position |
int |
0 |
The vertical display position of the forum (relative to
other forums in the same category). |
| cat_id |
int |
0 |
The category in which the forum resides. |
groups
| Field |
Type |
Default |
Description |
| g_id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| g_title |
varchar(50) |
|
The name of the group. |
| g_user_title |
varchar(50) |
NULL |
The title of users in this group. |
| g_read_board |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_post_replies |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_post_topics |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_post_polls |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_edit_posts |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_delete_posts |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_delete_topics |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_set_title |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_search |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
| g_search_users |
tinyint/smallint |
1 |
0 = Deny. 1 = Allow. |
g_edit_subjects_
interval |
smallint |
300 |
Number of seconds after post time that users in this
group may edit the subject of topics they've posted. |
| g_post_flood |
smallint |
30 |
Number of seconds that users in this group have to wait
between posts. |
| g_search_flood |
smallint |
30 |
Number of seconds that users in this group have to wait
between searches. |
online
| Field |
Type |
Default |
Description |
| user_id |
int |
1 |
ID of the user (always 1 for guests). |
| ident |
varchar(200) |
|
Identification string for the user. Username for logged
in users and IP address for guests. |
| logged |
int |
0 |
A UNIX timestamp representing the date/time for the
user's last activity. |
| idle |
tinyint/smallint |
0 |
0 = User has been active within the last "Online
timeout" seconds. 1 = User has timed out. |
posts
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| poster |
varchar(200) |
|
The username (or guest name) of the user that made the
post. |
| poster_id |
int |
1 |
The user ID of the user that made the post (always 1
for guests). |
| poster_ip |
varchar(15) |
NULL |
The IP address the post was made from. |
| poster_email |
varchar(50) |
NULL |
The guest e-mail address (if supplied). |
| message |
text |
|
The actual message contents. |
| hide_smilies |
tinyint/smallint |
0 |
0 = Let users decide whether to show smilies as images
or not in this post. 1 = Never show smilies as images in
this post. |
| posted |
int |
0 |
A UNIX timestamp representing the date/time the post
was made. |
| edited |
int |
NULL |
A UNIX timestamp representing the date/time the post
was last edited. |
| edited_by |
varchar(200) |
NULL |
The username of the user that last edited the
post. |
| topic_id |
int |
0 |
The topic ID in which the post resides. |
ranks
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| rank |
varchar(50) |
|
The rank title. |
| min_posts |
mediumint/int |
0 |
The number of posts a user must attain in order to
reach the rank. |
reports
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| post_id |
int |
0 |
The post the report relates to. |
| topic_id |
int |
0 |
The topic in which the reported post resides in. |
| forum_id |
int |
0 |
The forum in which the reported post resides in. |
| reported_by |
int |
0 |
The user ID of the user that reported the post. |
| created |
int |
0 |
A UNIX timestamp representing the date/time the post
was last edited. |
| message |
text |
|
The report message. |
| zapped |
int |
NULL |
A UNIX timestamp representing the date/time the report
was zapped (marked as read). |
| zapped_by |
int |
NULL |
The username of the administrator or moderator that
zapped the report. |
search_cache
| Field |
Type |
Default |
Description |
| id |
int |
0 |
The primary key identifier for this table. |
| ident |
varchar(200) |
|
Identification string for the searcher. Username for
logged in users and IP address for guests. |
| search_data |
text |
|
A serialized PHP array of search data (e.g. post ID's,
sort direction etc.). |
search_matches
| Field |
Type |
Default |
Description |
| post_id |
int |
0 |
The post this match relates to. |
| word_id |
mediumint/int |
0 |
The word this match relates to. |
| subject_match |
tinyint/smallint |
0 |
0 = Match is in the post message. 1 = Match is in the
topic subject. |
search_words
| Field |
Type |
Default |
Description |
| id |
mediumint/int |
|
An integer identifier for this table. |
| word |
varchar(20) |
|
The indexed word (primary key). |
subscriptions
| Field |
Type |
Default |
Description |
| user_id |
int |
0 |
The user that subscribes to topic_id. Primary
key identifier together with topic_id for this
table. |
| topic_id |
int |
0 |
The topic user_id subscribes to. Primary key
identifier together with user_id for this
table. |
topics
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| poster |
varchar(200) |
|
The username (or guest name) of the user that posted
the topic. |
| subject |
varchar(255) |
|
The topic subject. |
| posted |
int |
0 |
A UNIX timestamp representing the date/time the topic
was posted. |
| last_post |
int |
NULL |
A UNIX timestamp representing the date/time the last
post was made in the topic. |
| last_post_id |
int |
NULL |
The ID of the last post that was made in the
topic. |
| last_poster |
varchar(200) |
NULL |
The username (or guest name) of the user that made the
last post in the topic. |
| num_views |
mediumint/int |
0 |
The number of times the topic has been viewed. |
| num_replies |
mediumint/int |
0 |
The number of replies that have been posted in the
topic. |
| closed |
tinyint/smallint |
0 |
0 = Topic is open. 1 = Topic is closed. |
| sticky |
tinyint/smallint |
0 |
0 = Topic is a regular topic. 1 = Topic is a sticky
topic. |
| moved_to |
int |
NULL |
The forum to which the topic has been moved. |
| forum_id |
int |
0 |
The forum in which the topic resides. |
users
| Field |
Type |
Default |
Description |
| id |
int |
|
The auto-incrementing (identity) primary key identifier
for this table. |
| group_id |
int |
4 |
The user group to which this user belongs. |
| username |
varchar(200) |
|
The user's username. |
| password |
varchar(40) |
|
The user password as an 40 byte SHA1 hash or an 32 byte
MD5 hash. |
| email |
varchar(50) |
|
The user e-mail address. |
| title |
varchar(50) |
NULL |
The user custom title. |
| realname |
varchar(40) |
NULL |
The user's name. |
| url |
varchar(100) |
NULL |
A link to the user's website. |
| jabber |
varchar(75) |
NULL |
The user's Jabber address. |
| icq |
varchar(12) |
NULL |
The user's ICQ UIN. |
| msn |
varchar(50) |
NULL |
The user's MSN Messenger e-mail address. |
| aim |
varchar(30) |
NULL |
The user's AOL Instant Messenger username. |
| yahoo |
varchar(30) |
NULL |
The user's Yahoo Messenger username. |
| location |
varchar(30) |
NULL |
The user's geographical location. |
| use_avatar |
tinyint/smallint |
0 |
0 = Don't show avatar to other users. 1 = Show avatar
to other users. |
| signature |
text |
NULL |
The user's signature. |
| disp_topics |
tinyint/smallint |
NULL |
The number of topics to display on forum page (uses
forum default if left blank). |
| disp_posts |
tinyint/smallint |
NULL |
The number of posts to display on topic page (uses
forum default if left blank). |
| email_setting |
tinyint/smallint |
1 |
0 = Show e-mail address to other users. 1 = Hide e-mail
address, but allow form e-mail. 2 = Hide e-mail address and
disallow form e-mail. |
| save_pass |
tinyint/smallint |
1 |
0 = Don't remember user between visits. 1 = Remember
user between visits. |
| notify_with_post |
tinyint/smallint |
0 |
0 = Include only topic subject in subscription
notification e-mails. 1 = Include both topic subject and
post content in subscription notification e-mails. |
| show_smilies |
tinyint/smallint |
1 |
Show smilies as images. |
| show_img |
tinyint/smallint |
1 |
Show images in posts. |
| show_img_sig |
tinyint/smallint |
1 |
Show images in signatures. |
| show_avatars |
tinyint/smallint |
1 |
Show avatars. |
| show_sig |
tinyint/smallint |
1 |
Show signatures. |
| timezone |
float |
0 |
The user's timezone. |
| language |
varchar(25) |
'English' |
The user's preferred language for the forum UI. |
| style |
varchar(25) |
'Oxygen' |
The user's preferred style. |
| num_posts |
int |
0 |
The number of posts the user has made. |
| last_post |
int |
NULL |
A UNIX timestamp representing the date/time the last
post by the user was made. |
| registered |
int |
0 |
A UNIX timestamp representing the date the user
registered. |
| registration_ip |
varchar(15) |
0.0.0.0 |
The IP address used when registering. |
| last_visit |
int |
0 |
A UNIX timestamp representing the date/time the last
visit by the user commenced. |
| admin_note |
varchar(30) |
NULL |
A user note only viewable and editable by
administrators and moderators. |
| activate_string |
varchar(50) |
NULL |
A temporary storage string for new passwords and new
e-mail addresses. |
| activate_key |
varchar(8) |
NULL |
A temporary storage string for new password and new
e-mail address activation keys. |