📚 API Reference

Complete reference for Xiuno BBS core functions and hooks

User Functions

user_read($uid)

Description: Retrieve user information by UID

Parameters:

  • $uid (int) - User ID

Returns: Array with user data or FALSE if not found

$user = user_read(1);
// Returns: array(
//     'uid' => 1,
//     'username' => 'admin',
//     'email' => '[email protected]',
//     'gid' => 1,
//     'create_ip' => '127.0.0.1',
//     'create_date' => 1234567890,
//     ...
// )

user_create($user)

Description: Create a new user

Parameters:

  • $user (array) - User data array

Required fields: username, password, email, gid

Returns: New user UID or FALSE on failure

$uid = user_create(array(
    'username' => 'john_doe',
    'password' => '12345678',  // Will be hashed automatically
    'email' => '[email protected]',
    'gid' => 101,  // Member group
    'create_ip' => xn_ip(),
    'create_date' => time(),
));

user_update($uid, $update)

Description: Update user information

Parameters:

  • $uid (int) - User ID
  • $update (array) - Fields to update

Returns: Boolean success status

user_update(1, array(
    'email' => '[email protected]',
    'threads' => 100,
    'posts' => 500,
));

user_delete($uid)

Description: Delete a user (posts remain)

Parameters:

  • $uid (int) - User ID

Returns: Boolean success status

user_delete(123);

user_find_by_username($username)

Description: Find user by username

Returns: User array or FALSE

$user = user_find_by_username('admin');

Thread Functions

thread_read($tid)

Description: Get thread by TID

Parameters:

  • $tid (int) - Thread ID

Returns: Thread array or FALSE

$thread = thread_read(1);
// Returns: array(
//     'tid' => 1,
//     'fid' => 1,
//     'uid' => 1,
//     'subject' => 'Welcome',
//     'firstpid' => 1,
//     'lastpid' => 10,
//     'views' => 1000,
//     'posts' => 50,
//     'create_date' => 1234567890,
//     ...
// )

thread_create($thread, $post)

Description: Create new thread with first post

Parameters:

  • $thread (array) - Thread data
  • $post (array) - First post data

Returns: New thread TID or FALSE

$tid = thread_create(
    array(
        'fid' => 1,
        'uid' => 1,
        'subject' => 'New Thread Title',
        'create_date' => time(),
    ),
    array(
        'message' => 'Thread content goes here...',
        'create_ip' => xn_ip(),
    )
);

thread_update($tid, $update)

Description: Update thread fields

Parameters:

  • $tid (int) - Thread ID
  • $update (array) - Fields to update

Common updates: subject, top (pin), closed (lock)

// Pin thread
thread_update(1, array('top' => 1));

// Lock thread
thread_update(1, array('closed' => 1));

thread_delete($tid)

Description: Delete thread and all posts

Parameters:

  • $tid (int) - Thread ID

Returns: Boolean success status

thread_delete(123);

thread_find_by_fid($fid, $page = 1, $pagesize = 20)

Description: Get threads in a forum

Parameters:

  • $fid (int) - Forum ID
  • $page (int) - Page number
  • $pagesize (int) - Threads per page

Returns: Array of threads

$threads = thread_find_by_fid(1, 1, 20);

Post Functions

post_read($pid)

Description: Get post by PID

Returns: Post array or FALSE

$post = post_read(1);

post_create($post)

Description: Create a new post (reply)

Parameters:

  • $post (array) - Post data

Required fields: tid, uid, message

Returns: New post PID or FALSE

$pid = post_create(array(
    'tid' => 1,
    'uid' => 1,
    'message' => 'Reply content...',
    'create_ip' => xn_ip(),
    'create_date' => time(),
));

post_update($pid, $update)

Description: Update post content

post_update(1, array(
    'message' => 'Updated content',
    'update_date' => time(),
));

post_delete($pid)

Description: Delete a post

post_delete(123);

Forum Functions

forum_read($fid)

Description: Get forum information

Returns: Forum array or FALSE

$forum = forum_read(1);
// Returns: array(
//     'fid' => 1,
//     'name' => 'General Discussion',
//     'brief' => 'Talk about anything',
//     'threads' => 1000,
//     'posts' => 5000,
//     ...
// )

forum_create($forum)

Description: Create new forum category

Required fields: name, orderby

$fid = forum_create(array(
    'name' => 'New Forum',
    'brief' => 'Forum description',
    'orderby' => 1,
    'threads' => 0,
    'posts' => 0,
));

forum_list()

Description: Get all forums

Returns: Array of forums

$forums = forum_list();

Cache Functions

kv_set($key, $value)

Description: Store data in cache

Parameters:

  • $key (string) - Cache key
  • $value (mixed) - Data to cache
kv_set('user_stats', array(
    'total_users' => 1000,
    'active_today' => 50,
));

kv_get($key)

Description: Retrieve cached data

Returns: Cached value or FALSE

$stats = kv_get('user_stats');

kv_delete($key)

Description: Remove key from cache

kv_delete('user_stats');

Utility Functions

xn_filter($str)

Description: Sanitize user input (XSS protection)

$clean = xn_filter($_POST['input']);

xn_ip()

Description: Get user's IP address

$ip = xn_ip();  // Returns: '192.168.1.1'

humantime($timestamp)

Description: Convert timestamp to human-readable format

echo humantime(time() - 3600);  // "1 hour ago"

format_date($timestamp, $format = 'Y-m-d H:i:s')

Description: Format timestamp to date string

echo format_date(time());  // "2026-04-06 10:30:45"

message($code, $message)

Description: Display message and stop execution

Parameters:

  • $code (int) - Status code (1 = success, -1 = error)
  • $message (string) - Message to display
message(1, 'Operation successful');
message(-1, 'Error: Invalid input');

Database Functions

$db->query($sql, $params...)

Description: Execute SQL query with parameters

global $db;

// Select with parameters
$users = $db->query("SELECT * FROM bbs_user WHERE gid = ?", 1);

// Insert
$db->query("INSERT INTO bbs_log (uid, action, date) VALUES (?, ?, ?)", 
    $uid, 'login', time());

// Update
$db->query("UPDATE bbs_user SET posts = posts + 1 WHERE uid = ?", $uid);

$db->query_first($sql, $params...)

Description: Get first result row

$user = $db->query_first("SELECT * FROM bbs_user WHERE uid = ?", 1);

$db->insert($table, $data)

Description: Insert data into table

global $db, $tablepre;

$db->insert("{$tablepre}log", array(
    'uid' => 1,
    'action' => 'login',
    'ip' => xn_ip(),
    'date' => time(),
));

$db->update($table, $where, $data)

Description: Update table records

$db->update("{$tablepre}user", 
    array('uid' => 1),  // WHERE condition
    array('lastip' => xn_ip())  // SET values
);

$db->delete($table, $where)

Description: Delete from table

$db->delete("{$tablepre}session", array('uid' => 1));

Plugin Hooks

User Hooks

Hook Name Parameters When It Fires
user_create_before &$user Before user registration
user_create_after $uid After user created
user_update_before $uid, &$update Before updating user
user_update_after $uid, $update After user updated
user_login_start $username Login attempt starts
user_login_after $uid After successful login

Thread Hooks

Hook Name Parameters When It Fires
thread_create_before &$thread Before creating thread
thread_create_after $tid After thread created
thread_read_start $tid When thread is viewed
thread_delete_before $tid Before deleting thread

Post Hooks

Hook Name Parameters When It Fires
post_create_before &$post Before creating post
post_create_after $pid After post created
post_update_before $pid, &$update Before updating post
post_delete_before $pid Before deleting post

Route Hooks

Hook Name When It Fires Use Case
route_index_start Homepage load begin Add custom homepage content
route_index_end Homepage load complete Inject widgets/scripts
route_thread_start Thread page load begin Modify thread display
route_user_start User profile load Add profile sections

Example: Complete API Usage

Creating a Discussion Thread

<?php
// Check user is logged in
if(!$uid) {
    message(-1, 'Please login first');
}

// Validate input
$subject = xn_filter($_POST['subject']);
$message = xn_filter($_POST['message']);
$fid = (int)$_POST['fid'];

if(empty($subject) || empty($message)) {
    message(-1, 'Subject and message required');
}

// Check forum exists
$forum = forum_read($fid);
if(!$forum) {
    message(-1, 'Forum not found');
}

// Create thread with first post
$thread = array(
    'fid' => $fid,
    'uid' => $uid,
    'subject' => $subject,
    'create_date' => time(),
);

$post = array(
    'message' => $message,
    'create_ip' => xn_ip(),
    'create_date' => time(),
);

$tid = thread_create($thread, $post);

if($tid) {
    // Update user stats
    user_update($uid, array(
        'threads' => $user['threads'] + 1
    ));
    
    // Redirect to new thread
    header("Location: ?thread-$tid.htm");
    exit;
} else {
    message(-1, 'Failed to create thread');
}
?>

User Authentication

<?php
$username = xn_filter($_POST['username']);
$password = $_POST['password'];

// Find user
$user = user_find_by_username($username);

if(!$user) {
    message(-1, 'User not found');
}

// Verify password
if(!password_verify($password, $user['password'])) {
    message(-1, 'Invalid password');
}

// Check if user is banned
if($user['gid'] == 102) {
    message(-1, 'Your account has been banned');
}

// Create session
session_start();
$_SESSION['uid'] = $user['uid'];
$_SESSION['username'] = $user['username'];
$_SESSION['gid'] = $user['gid'];

// Update last login
user_update($user['uid'], array(
    'lastip' => xn_ip(),
    'lastvisit' => time(),
));

// Redirect to homepage
header("Location: /");
exit;
?>
📘 More Resources:
• Plugin Development Guide - Build custom plugins
• Developer Forum - Ask questions and get help
• GitHub Repository - View source code