Infos développeurs
Informations pour les développeurs pour profiter de votre installation existante de PunBB.
Table des matières
Syndication
Le script extern.php est utiliser pour inclure des informations à propos
de vos forums sur des pages externes aux forums et pour syndiquer les discussions
récentes via RSS. Le script peut afficher une liste de discussions récentes
(triée par messages, dates ou derniers messages), une liste d’utilisateurs
actifs ou une collection de statistiques générales. Le script peut être
appeler directement par l’intermédiaire d’une URL (pour RSS), de la commande
inclue de PHP ou par l’utilisation du Server Side Includes (SSI).
Le comportement du script est commandé par l’intermédiaire de variables
fournies au script dans l’URL. Les différentes variables sont : action
(que faut-il afficher), show (combien de discussions afficher), forum (l’ID
du forum à sonder pour récupèrer les discussions) et type (sortie comme
HTML ou RSS). La seule variable obligatoire est action.
Les valeurs de possibles (par defaut) sont :
- action : active (affiche les discussions le plus récemment
actives) (HTML ou RSS)
new (afficher les plus récentes discussions) (HTML ou RSS)
online (afficher les utilisateurs en ligne) (HTML)
online_full (comme ci-dessus, mais inclut une liste complète) (HTML)
stats (afficher les statistiques des forums) (HTML)
- show : N’importe qu’elle valeur, nombre entier entre
1 et 50. Cette variable est ignorées pour la sortie RSS. 15 par défaut.
- fid : Un ou plusieurs ID de forum (séparés par des virgules).
Si ignorée, des discussions de tous les forums lisibles par les invités
seront récupérées.
- type : RSS. Toute autre chose signifie une sortie en
HTML.
Voici quelques exemples en utilisant la fonction include() de PHP.
- Afficher les 15 discussions les plus récemment actives depuis tous les forums :
include('http://host.com/forums/extern.php?action=active');
- Afficher les 10 discussions les plus récentes depuis les forums d’ID 5, 6 et 7 :
include('http://host.com/forums/extern.php?action=new&show=10&fid=5,6,7');
- Afficher les utilisateurs en ligne :
include('http://host.com/forums/extern.php?action=online');
- Afficher les utilisateurs en ligne avec une liste complète :
include('http://host.com/forums/extern.php?action=online_full');
- Afficher les statistiques des forums :
include('http://host.com/forums/extern.php?action=stats');
Voici quelques exemples en utilisant SSI.
- Afficher les 5 discussions les plus récentes depuis les forums d’ID 11 et 22 :
<!--#include
virtual="forums/extern.php?action=new&show=5&fid=11,22"
-->
- Afficher les statistiques des forums :
<!--#include virtual="forums/extern.php?action=stats"
-->
Et enfin quelques exemples en utilisant extern.php pour produire un fil RSS 0.91
- Afficher les 15 discussions les plus récemment actives :
http://host.com/extern.php?action=active&type=RSS
- Afficher les 15 discussions les plus récemment actives depuis le forum d’ID 2 :
http://host.com/extern.php?action=active&type=RSS&fid=2
Intégration dans un site web
Intégrer PunBB dans le code de votre site web est facile si vous connaissez
un petit peu PHP. En incluant le script common.php de PunBB, vous accédez à toutes
les variables globales de PunBB comme $db et $pun_user. Cependant, afin
d’inclure ce fichier, vous devez définir une constante appelée PUN_ROOT.
Cette constante devra fixer le chemin relatif vers votre répertoire de
forums PunBB. Par exemple, si votre page d’accueil de votre site est localisé dans
/home/user/public_html/ et vos forum sont dans /home/user/public_html/forums/,
votre PUN_ROOT devrait alrs être ./forums/
Le code PHP pour accomplir ceci pourrait ressembler à quelque chose comme ça :
define('PUN_ROOT', './forums/');
require PUN_ROOT.'include/common.php';
Une fois que vous avez inclus common.php, vous pouvez accéder et utiliser
toutes les variables globales et fonctions de PunBB. Typiquement, vous
serez le plus intéressé par le tableau $pun_user. Ce tableau contient des
informations sur l’utilisateur courant. Une autre variable intéressante
est l’objet de base de données $db. Comment employer ces variables dans
vos propres scripts est hors du propos de ce document, mais voici un petit
exemple vous montrant comment afficher un message simple saluant l’utilisateur
courant sur votre page d’accueil :
Bonjour <?php echo pun_htmlspecialchars($pun_user['username']); ?>!
En plus de définir PUN_ROOT, vous pouvez définir un certain nombre d’autres
constantes pour changer le comportement de PunBB en incluant common.php.
Les deux les plus intéressantes de ces constantes sont PUN_TURN_OFF_MAINT
et PUN_QUIET_VISIT. Si PUN_TURN_OFF_MAINT est défini en incluant common.php,
si les forums sont en mode maintenance, PunBB ne bloquera pas pour afficher
le message de maintenance. Vous ne voulez généralement pas que ce message
s’affiche sur votre page d’accueil, pour cela définir cette constante est
une bonne idée. L’autre constante, PUN_QUIET_VISIT, empêche PunBB de mettre à jour
les données de dernières visite de l’utilisateur courant dans la base de
données de sorte qu’une visite à la page d’accueil ne compte pas comme
visite dans les forums. C’est également un comportement souhaitable dans
la plupart des cas. La valeur à laquelle vous placez ces constantes n’importe
pas, mais les régler à une valeur de 1 est probablement une bonne idée.
Exemple :
define('PUN_TURN_OFF_MAINT', 1);
define('PUN_QUIET_VISIT', 1);
Veuillez noter que ces constantes doivent être définies avant que common.php soit inclus.
Plugins
Les plugins admin Les plugins Admin sont des modules pour l’interface d’administration
de PunBB qui peuvent êtres installés en placant simplement le script plugin
dans le répertoire plugins. Voyez le plugin exemple pour des informations
sur la façon d’écrire votre propre plugin. Voici quelques notes d’intérêssantes
pour les aspirants auteurs de plugin :
- Si vous voulez afficher un message par l’intermédiaire de la fonction
message(), vous devez le faire avant d’appeler generate_admin_menu($plugin).
- Les plugins sont chargés par admin_loader.php et ne doivent pas être
terminés (par exemple en appelant exit()). Après que le script du plugin
ait fini, le script du chargeur affiche le pied de page, ainsi inutil
de vous souciez de cela. Cependant veuillez noter que terminer un plugin
en appelant message() ou redirect() est très bien.
- L’attribut action de toute balise <form> et l’URL cible pour la
fonction redirect() doit être placé à la valeur de $_SERVER[’REQUEST_URI’].
Cette URL peut cependant être étendue pour inclure des variables supplémentaires
(comme l’ajout de &foo=bar dans le plugin exemple).
- Si votre plugin est pour les administrateurs seulement, le nom de fichier
doit avoir le préfixe AP_. S’il est pour les administrateurs et les modérateurs,
utilisez le préfixe AMP_. Le plugin exemple a le préfixe AMP_ et est
donc disponible dans le menu de navigation aux administrateurs et aux
modérateurs.
- Utilisez _ au lieu des espaces dans le nom de fichier.
- Tant que les scripts de plugin sont inclus depuis le scripts admin_loader.php
de PunBB, vous avez accès toutes les fonctions et variables globales
de PunBB (par exemple $db, $pun_config, $pun_user etc.).
- Faites de votre mieux pour garder l’aspect et l’ergonomie de votre interface
utilisateur de plugins semblable au reste des scripts d’administration.
N’hésitez pas à emprunter le marquage et le code aux scripts d’admin
pour l’employer dans vos plugins.
- Les plugins doivent êtres délivrés sous la licence d’utilisation GNU/GPL
ou une licence compatible. Recopiez le préambule GPL (situé en haut des
scripts de PunBB) dans votre script de plugin et changez l e copyright
pour qu’il corresponde à l’auteur du plugin (c’est à dire vous).
Références tables de la base de données
Ce qui suit est une liste complète de toutes les tables de base de données
de PunBB avec leurs champs respectifs. Les clés primaire sont soulignées.
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. |