Command Implementation
doMsg(string $msg)- Causes the shoutbox to be replaced with $msg until the user uses /return (useful for making error messages, notices, etc.)
help(string $command - default '')- Allows users to get help on a command. Use <arg> to denote required arguments and [arg] to denote optional ones. Note that all <> must be entered as < and > or they will not work. Make sure to add an entry in this function for any new commands.
boolean processCommand(string $text)- Process an admin command. If this function fails to find a match, it defaults to the user commands.
boolean processUserCommand(string $text)- Process a user command. This function attempts to match against all known commands. If a valid command match isn't found, the function will return false and the shout ("command") will be displayed as a regular shout.
User Permissions
boolean isGuest(array $user - defaults to current user)- Returns true if the user is a guest, false otherwise.
boolean isMod(array $user - defaults to current user)- Returns true if the user is a shoutbox moderator, false otherwise.
boolean isPostBanned(array $user - defaults to current user)- Returns true if the user isn't allowed to shout, false otherwise.
Administrative Functions
boolean deleteShout(string $spanTitle, string $chatPath)- Delete the given shout, identified by its spanTitle (a string formatted as "$shoutTime | $ip") from the file $chatPath.
boolean doBan(string $type, string $mode, string $id)- Ban a user. $type is one of 'ban_ips_' or 'ban_names_', signifying the type of ban (IP or username/displayname). $mode is one of 'u', 'rp' or 'p' for unbanning, banning from reading and posting, or banning from posting only respectively. $id is the actual name or IP to be banned. The return value is true if (un)banning was successful, and false otherwise.
writeBanlist()- Update the banlist file (_banlist.php).
Reading Shouts
history()- Show the history file in a neat, formatted HTML style.
initShoutbox(array $user, boolean $fromSMF)- Initialize the shoutbox, printing the interface (tool links and the shout form) as well as the current shouts. $fromSMF tells this function whether it was called as an independent script or if it was invoked from SMF (in which case output compression is turned off).
string processChats(string $chatText, array $user - defaults to current user)- Process raw chat text for display: stripping admin links, censoring IPs and formatting the timestamp.
string readChat(string $chatPath, boolean $force - default false)- Return the processed contents of the chat file. If the client is viewing a special message or command, then readChat simply executes that command or returns the message (this command/message is stored in $_SESSION['readingCmd']) If $force is set, the shouts are returned regardless of the contents of $_SESSION['readingCmd'].
refreshChats(boolean $forceRefresh - defaults to false)- Called when reqtype is 'refresh'. This function refreshes the user's display of the chats, and will wait up to $updateTimeout seconds for new shouts before displaying them.
Shouting
string cleanupShout(string $text)- Cleans up and formats a shout: converts special characters to entities, strips bad BBCode, parses BBCode and censors the text according to the forum settings.
makeShout(string $newText, array $user - defaults to current user)- Makes a standard shout.
makeRawShout(string $newText, array $user - defaults to current user)- Uses $newText to make a shout with timestamp and adminlinks. If you are making custom shouts, you should always call makeShout or makeRawShout, never writeLine.
preg_timeformat(array $matches)- Function used to replace matched <timeval=[UNIX time offset]> with formatted times as per SMF's timeformat function. Called through preg_replace_callback. This function is located in settings.php.
truncateChat(integer $maxLines, string $chatPath, string $historyPath)- Move the first line of the file $chatPath to the file $historyPath history if the number of lines in $chatPath exceeds $maxLines. If $historyPath is the empty string, the first line will simply be deleted.
writeLine(string $newText, string $chatPath)- Write the given line to the chat file ($chatPath).
$_SESSION
readingCmd- The command (if it starts with /) or the message to be read back to the user instead of the normal shoutbox chats.
$_GET
n- Used by the history() function to determine the # of history lines to output.
help- If this is set, the shoutbox will output a full HTML help message (using help()). Use as a standalone page.
history- If this is set, the shoutbox will output a full HTML history page (with history()). Use as a standalone page.
banid- For the administrator's ban link: this is passed as the user ID of the member to be banned.
delete- For deleting shouts; this is a string in the form datecode | ip (this is the format used in the <em title>
unban- Username/identifier to unban (used by /banlist)
$_POST
reqtype- What function to carry out (shout, refresh, init)
shout- If reqtype is shout, then this is the shout to be made.
$_SERVER
REMOTE_ADDR- Used for $ip to determine their IP address.
Global Variables (excludes settings)
$ban_ips_readpost, $ban_ips_post, $ban_names_readpost, $ban_names_post- Ban variables. _ips or _names is the ban criteria (IP address or username) while _readpost or _post is the ban severity (banned from reading+posting or just posting)
$user- SMF user data array. This determines a lot of things about the user (like the username and status)
$ip- User's IP address. Gathered from $_SERVER['REMOTE_ADDR'].
$reqType- Request type; see $_POST['reqtype'].
To add a command, first decide whether this command is *user* or *moderator* level.
The general format of a command is "/command <required-arguments> [optional-arguments]".
Commands are processed in processCommand or processUserCommand. The former is for moderator commands, and the latter is for regular user commands.
Processing begins by parsing the args and then running through a long switch/case block. In this block, you will add your command code. Your code should begin with a "case '/commandname':" and end with a return true; statement.
The two things you will have access to locally are $args and $cmd. $args is a string containing all the arguments passed, and $cmd is the exact command used. For example, with the command "/foo bar baz", $cmd will be "/foo" and $args will be "bar baz". This will be handled by the "case '/foo':" statement.
Globally, any of the superglobals are available, plus any globals. You may have to include your own globals with a "global $variable1,$variable2;" line.
To make a message appear on the shoutbox (for one user only), set the variable $_SESSION['readingCmd'] to $text (which is the main argument for the processing function). This causes the exact text of the command to be reparsed every time the user requests the shoutbox data, and your information will be returned instead of the regular shouts. Don't do this if your command has side-effects, as they will be repeated every time the shoutbox refreshes; use doMsg in this case.
The doMsg function (an alternative to setting $_SESSION['readingCmd']) allows you to automatically set a message that will stay up until they use /return.
Remember that whenever your function needs to exit, it must do so with "return true;" so that the calling function will know not to "shout" the command.