Composr API documentation
Back to top  

Forum driver class.

package core_forum_drivers
inherited_from \Forum_driver_base

 Methods

Check the connected DB is valid for this forum driver.

check_db() : boolean

Returns

booleanWhether it is valid

If we can't get a list of admins via a usergroup query, we have to disable the staff filter - else the staff filtering can cause disaster at the point of being turned on (because it can't automatically sync).

disable_staff_filter() : boolean
Inherited

Returns

booleanWhether the staff filter is disabled

Get a map between emoticon codes and templates representing the HTML-image-code for this emoticon. The emoticons presented of course depend on the forum involved.

find_emoticons() : array

Returns

arrayThe map

Get the topic ID from a topic identifier in the specified forum. It is used by comment topics, which means that the unique-topic-name assumption holds valid.

find_topic_id_for_topic_identifier(string $forum, \SHORT_TEXT $topic_identifier) : \?integer

Parameters

$forum

string

The forum name / ID

$topic_identifier

\SHORT_TEXT

The topic identifier

Returns

\?integerThe topic ID (null: not found)

Attempt to to find the member's language from their forum profile. It converts between language-identifiers using a map (lang/map.ini).

forum_get_lang(\MEMBER $member) : \?LANGUAGE_NAME

Parameters

$member

\MEMBER

The member who's language needs to be fetched

Returns

\?LANGUAGE_NAMEThe member's language (null: unknown)

Get the forum ID from a forum name.

forum_id_from_name(\SHORT_TEXT $forum_name) : integer

Parameters

$forum_name

\SHORT_TEXT

The forum name

Returns

integerThe forum ID

Get a URL to a forum.

forum_url(integer $id, boolean $tempcode_okay = false) : mixed
Inherited

Parameters

$id

integer

The ID of the forum

$tempcode_okay

boolean

Whether it is okay to return the result using Tempcode (more efficient)

Returns

mixedThe URL

Get custom profile fields values for all 'cms_' prefixed keys.

get_custom_fields(\MEMBER $member) : \?array

Parameters

$member

\MEMBER

The member ID

Returns

\?arrayA map of the custom profile fields, key_suffix=>value (null: no fields)

Get the forums' table prefix for the database.

get_drivered_table_prefix() : string

Returns

stringThe forum database table prefix

Find the base URL to the emoticons.

get_emo_dir() : \URLPATH

Returns

\URLPATHThe base URL

Get an emoticon chooser template.

get_emoticon_chooser(string $field_name = 'post') : \Tempcode

Parameters

$field_name

string

The ID of the form field the emoticon chooser adds to

Returns

\TempcodeThe emoticon chooser template

Get an array of maps for the topic in the given forum.

get_forum_topic_posts(integer $topic_id, integer $count, integer $max = 100, integer $start = 0, boolean $mark_read = true, boolean $reverse = false) : mixed

Parameters

$topic_id

integer

The topic ID

$count

integer

The comment count will be returned here by reference

$max

integer

Maximum comments to returned

$start

integer

Comment to start at

$mark_read

boolean

Whether to mark the topic read (ignored for this forum driver)

$reverse

boolean

Whether to show in reverse

Returns

mixedThe array of maps (Each map is: title, message, member, date) (-1 for no such forum, -2 for no such topic)

Find the usergroup ID of the forum guest member.

get_guest_group() : \GROUP
Inherited

Returns

\GROUPThe usergroup ID of the forum guest member

Find the member ID of the forum guest member.

get_guest_id() : \MEMBER

Returns

\MEMBERThe member ID of the forum guest member

Find all members with a name matching the given SQL LIKE string.

get_matching_members(string $pattern, \?integer $limit = null) : \?array

Parameters

$pattern

string

The pattern

$limit

\?integer

Maximum number to return (limits to the most recent active) (null: no limit)

Returns

\?arrayThe array of matched members (null: none found)

Get the avatar URL for the specified member ID.

get_member_avatar_url(\MEMBER $member) : \URLPATH

Parameters

$member

\MEMBER

The member ID

Returns

\URLPATHThe URL (blank: none)

Get a member's e-mail address.

get_member_email_address(\MEMBER $id) : \SHORT_TEXT
Inherited

Parameters

$id

\MEMBER

The member

Returns

\SHORT_TEXTThe e-mail address (blank: not known)

Find if this member may have e-mails sent to them

get_member_email_allowed(\MEMBER $member) : boolean

Parameters

$member

\MEMBER

The member ID

Returns

booleanWhether the member may have e-mails sent to them

Get a member ID from the given member's username.

get_member_from_username(\SHORT_TEXT $name) : \MEMBER

Parameters

$name

\SHORT_TEXT

The member name

Returns

\MEMBERThe member ID

Get a first known IP address of the given member.

get_member_ip(\MEMBER $member) : \IP

Parameters

$member

\MEMBER

The member ID

Returns

\IPThe IP address

Get the timestamp of a member's join date.

get_member_join_timestamp(\MEMBER $member) : \TIME

Parameters

$member

\MEMBER

The member ID

Returns

\TIMEThe timestamp

Get the photo thumbnail URL for the specified member ID.

get_member_photo_url(\MEMBER $member) : \URLPATH

Parameters

$member

\MEMBER

The member ID

Returns

\URLPATHThe URL (blank: none)

Gets a whole member row from the database.

get_member_row(\MEMBER $member) : \?array

Parameters

$member

\MEMBER

The member ID

Returns

\?arrayThe member row (null: no such member)

Gets a named field of a member row from the database.

get_member_row_field(\MEMBER $member, string $field) : mixed

Parameters

$member

\MEMBER

The member ID

$field

string

The field identifier

Returns

mixedThe field

Get the number of members registered on the forum.

get_members() : integer

Returns

integerThe number of members

Get a list of usergroups a member is in.

get_members_groups(\MEMBER $id, boolean $skip_secret = false, boolean $handle_probation = true) : array
Inherited

Parameters

$id

\MEMBER

The member

$skip_secret

boolean

Whether to skip looking at secret usergroups.

$handle_probation

boolean

Whether to take probation into account

Returns

arrayThe list of usergroups

Get a list of the moderator usergroups.

get_moderator_groups() : array
Inherited

Returns

arrayThe list of usergroups

Get a member row for the member of the given name.

get_mrow(\SHORT_TEXT $name) : \?array

Parameters

$name

\SHORT_TEXT

The member name

Returns

\?arrayThe profile-row (null: could not find)

Get the member ID of the next member after the given one, or NULL.

get_next_member(\MEMBER $member) : \?MEMBER

It cannot be assumed there are no gaps in member IDs, as members may be deleted.

Parameters

$member

\MEMBER

The member ID to increment

Returns

\?MEMBERThe next member ID (null: no next member)

Get the total posts ever made on the forum.

get_num_forum_posts() : integer

Returns

integerThe number of posts

Get the number of new forum posts on the system in the last 24 hours.

get_num_new_forum_posts() : integer
Inherited

Returns

integerNumber of forum posts

Get the number of members currently online on the forums.

get_num_users_forums() : integer

Returns

integerThe number of members

Get the given member's post count.

get_post_count(\MEMBER $member) : integer

Parameters

$member

\MEMBER

The member ID

Returns

integerThe post count

Load extra details for a list of posts. Does not need to return anything if forum driver doesn't support partial post loading (which is only useful for threaded topic partial-display).

get_post_remaining_details(\AUTO_LINK $topic_id, array $post_ids) : array
Inherited

Parameters

$topic_id

\AUTO_LINK

Topic the posts come from

$post_ids

array

List of post IDs

Returns

arrayExtra details

This is the opposite of the get_next_member function.

get_previous_member(\MEMBER $member) : \?MEMBER

Parameters

$member

\MEMBER

The member ID to decrement

Returns

\?MEMBERThe previous member ID (null: no previous member)

Get a list of the super admin usergroups.

get_super_admin_groups() : array
Inherited

Returns

arrayThe list of usergroups

Get the current member's theme identifier.

get_theme(\?ID_TEXT $zone_for = null) : \ID_TEXT
Inherited

Parameters

$zone_for

\?ID_TEXT

The zone we are getting the theme for (null: current zone)

Returns

\ID_TEXTThe theme identifier

Get the rows for the top given number of posters on the forum.

get_top_posters(integer $limit) : array

Parameters

$limit

integer

The limit to the number of top posters to fetch

Returns

arrayThe rows for the given number of top posters in the forum

Get the given member's topic count.

get_topic_count(\MEMBER $member) : integer

Parameters

$member

\MEMBER

The member ID

Returns

integerThe topic count

Get the total topics ever made on the forum.

get_topics() : integer

Returns

integerThe number of topics

Get a map of forum usergroups (id=>name).

get_usergroup_list(boolean $hide_hidden = false, boolean $only_permissive = false, boolean $force_show_all = false, \?array $force_find = null, \?MEMBER $for_member = null, boolean $skip_hidden = false) : array
Inherited

Parameters

$hide_hidden

boolean

Whether to obscure the name of hidden usergroups

$only_permissive

boolean

Whether to only grab permissive usergroups

$force_show_all

boolean

Do not limit things even if there are huge numbers of usergroups

$force_find

\?array

Usergroups that must be included in the results (null: no extras must be)

$for_member

\?MEMBER

Always return usergroups of this member (null: current member)

$skip_hidden

boolean

Whether to completely skip hidden usergroups

Returns

arrayThe map

Get a member's username.

get_username(\MEMBER $id, boolean $use_displayname = false) : \?SHORT_TEXT
Inherited

Parameters

$id

\MEMBER

The member

$use_displayname

boolean

Whether to use the displayname rather than the username (if we have them)

Returns

\?SHORT_TEXTThe username (null: deleted member)

Add the specified custom field to the forum (some forums implemented this using proper custom profile fields, others through adding a new field).

install_create_custom_field(string $name, integer $length, \BINARY $locked = 1, \BINARY $viewable = 0, \BINARY $settable = 0, \BINARY $required = 0) : boolean

Parameters

$name

string

The name of the new custom field

$length

integer

The length of the new custom field

$locked

\BINARY

Whether the field is locked

$viewable

\BINARY

Whether the field is for viewing

$settable

\BINARY

Whether the field is for setting

$required

\BINARY

Whether the field is required

Returns

booleanWhether the custom field was created successfully

Add the specified custom field to the forum (some forums implemented this using proper custom profile fields, others through adding a new field).

install_delete_custom_field(string $name) 
Inherited

Parameters

$name

string

The name of the new custom field

Get an array of paths to search for config at.

install_get_path_search_list() : array

Returns

arrayThe paths in which to search for the forum config

Get an array of attributes to take in from the installer. Almost all forums require a table prefix, which the requirement there-of is defined through this function.

install_specifics() : array

The attributes have 4 values in an array

  • name, the name of the attribute for _config.php
  • default, the default value (perhaps obtained through autodetection from forum config)
  • description, a textual description of the attributes
  • title, a textual title of the attribute

Returns

arrayThe attributes for the forum

Searches for forum auto-config at this path.

install_test_load_from(\PATH $path) : boolean

Parameters

$path

\PATH

The path in which to search

Returns

booleanWhether the forum auto-config could be found

Find if login cookie is md5-hashed.

is_hashed() : boolean

Returns

booleanWhether the login cookie is md5-hashed

Find whether a member is staff.

is_staff(\MEMBER $id, boolean $skip_staff_filter = false) : boolean
Inherited

Parameters

$id

\MEMBER

The member

$skip_staff_filter

boolean

Whether to avoid checking the staff filter (i.e. ignore M.S.N.'s)

Returns

booleanThe answer

Find whether a member is a super administrator.

is_super_admin(\MEMBER $id) : boolean
Inherited

Parameters

$id

\MEMBER

The member

Returns

booleanThe answer

Get a URL to a forum join page.

join_url() : mixed
Inherited

Returns

mixedThe URL

Makes a post in the specified forum, in the specified topic according to the given specifications. If the topic doesn't exist, it is created along with a spacer-post.

make_post_forum_topic(\SHORT_TEXT $forum_name, \SHORT_TEXT $topic_identifier, \MEMBER $member, \LONG_TEXT $post_title, \LONG_TEXT $post, string $content_title, string $topic_identifier_encapsulation_prefix, \?URLPATH $content_url = null, \?TIME $time = null, \?IP $ip = null, \?BINARY $validated = null, \?BINARY $topic_validated = 1, boolean $skip_post_checks = false, \SHORT_TEXT $poster_name_if_guest = '', \?AUTO_LINK $parent_id = null, boolean $staff_only = false) : array

Spacer posts exist in order to allow staff to delete the first true post in a topic. Without spacers, this would not be possible with most forum systems. They also serve to provide meta information on the topic that cannot be encoded in the title (such as a link to the content being commented upon).

Parameters

$forum_name

\SHORT_TEXT

The forum name

$topic_identifier

\SHORT_TEXT

The topic identifier (usually _)

$member

\MEMBER

The member ID

$post_title

\LONG_TEXT

The post title

$post

\LONG_TEXT

The post content in Comcode format

$content_title

string

The topic title; must be same as content title if this is for a comment topic

$topic_identifier_encapsulation_prefix

string

This is put together with the topic identifier to make a more-human-readable topic title or topic description (hopefully the latter and a $content_title title, but only if the forum supports descriptions)

$content_url

\?URLPATH

URL to the content (null: do not make spacer post)

$time

\?TIME

The post time (null: use current time)

$ip

\?IP

The post IP address (null: use current members IP address)

$validated

\?BINARY

Whether the post is validated (null: unknown, find whether it needs to be marked unvalidated initially). This only works with the Conversr driver.

$topic_validated

\?BINARY

Whether the topic is validated (null: unknown, find whether it needs to be marked unvalidated initially). This only works with the Conversr driver.

$skip_post_checks

boolean

Whether to skip post checks

$poster_name_if_guest

\SHORT_TEXT

The name of the poster

$parent_id

\?AUTO_LINK

ID of post being replied to (null: N/A)

$staff_only

boolean

Whether the reply is only visible to staff

Returns

arrayTopic ID (may be NULL), and whether a hidden post has been made

Get a URL to the specified member's home (control panel).

member_home_url(\MEMBER $id) : \URLPATH

Parameters

$id

\MEMBER

The member ID

Returns

\URLPATHThe URL to the members home

Get a URL to send a forum member a PM.

member_pm_url(\MEMBER $id, boolean $tempcode_okay = false) : mixed
Inherited

Parameters

$id

\MEMBER

The forum member

$tempcode_okay

boolean

Whether it is okay to return the result using Tempcode (more efficient)

Returns

mixedThe URL

Get a hyperlink (i.e. HTML link, not just a URL) to a forum member's member profile.

member_profile_hyperlink(\MEMBER $id, boolean $definitely_profile = false, string $_username = '', boolean $use_displayname = true) : \Tempcode
Inherited

Parameters

$id

\MEMBER

The forum member

$definitely_profile

boolean

Whether to be insistent that we go to the profile, rather than possibly starting an IM which can link to the profile

$_username

string

The username (blank: look it up)

$use_displayname

boolean

Whether to use the displayname rather than the username (if we have them)

Returns

\TempcodeThe hyperlink

Get a URL to a forum member's member profile.

member_profile_url(\MEMBER $id, boolean $definitely_profile = false, boolean $tempcode_okay = false) : mixed
Inherited

Parameters

$id

\MEMBER

The forum member

$definitely_profile

boolean

Whether to be insistent that we go to the profile, rather than possibly starting an IM which can link to the profile

$tempcode_okay

boolean

Whether it is okay to return the result using Tempcode (more efficient, and allows keep_* parameters to propagate which you almost certainly want!)

Returns

mixedThe URL

From a member row, get the member's e-mail address.

mrow_email(array $r) : \SHORT_TEXT

Parameters

$r

array

The profile-row

Returns

\SHORT_TEXTThe member e-mail address

From a member row, get the member's member ID.

mrow_id(array $r) : \MEMBER

Parameters

$r

array

The profile-row

Returns

\MEMBERThe member ID

From a member row, get the member's last visit date.

mrow_lastvisit(array $r) : \TIME

Parameters

$r

array

The profile-row

Returns

\TIMEThe last visit date

From a member row, get the member's name.

mrow_username(array $r) : string

Parameters

$r

array

The profile-row

Returns

stringThe member name

Pin a topic.

pin_topic(\AUTO_LINK $id, boolean $pin = true) 

Parameters

$id

\AUTO_LINK

The topic ID

$pin

boolean

True: pin it, False: unpin it

Get a URL to the specified post ID.

post_url(integer $id, string $forum) : \URLPATH

Parameters

$id

integer

The post ID

$forum

string

The forum ID

Returns

\URLPATHThe URL to the post

Try to find a member with the given IP address

probe_ip(\IP $ip) : array

Parameters

$ip

\IP

The IP address

Returns

arrayThe distinct rows found

Set a custom profile fields value. It should not be called directly.

set_custom_field(\MEMBER $member, string $field, string $value) 

Parameters

$member

\MEMBER

The member ID

$field

string

The field name

$value

string

The value

Get an array of topics in the given forum. Each topic is an array with the following attributes: - id, the topic ID - title, the topic title - lastusername, the username of the last poster - lasttime, the timestamp of the last reply - closed, a Boolean for whether the topic is currently closed or not - firsttitle, the title of the first post - firstpost, the first post (only set if $show_first_posts was true)

show_forum_topics(mixed $name, integer $limit, integer $start, integer $max_rows, \SHORT_TEXT $filter_topic_title = '', boolean $show_first_posts = false, string $date_key = 'lasttime', boolean $hot = false, \SHORT_TEXT $filter_topic_description = '') : \?array
set lasttime firsttime

Parameters

$name

mixed

The forum name or an array of forum IDs

$limit

integer

The limit

$start

integer

The start position

$max_rows

integer

The total rows (not a parameter: returns by reference)

$filter_topic_title

\SHORT_TEXT

The topic title filter

$show_first_posts

boolean

Whether to show the first posts

$date_key

string

The date key to sort by

$hot

boolean

Whether to limit to hot topics

$filter_topic_description

\SHORT_TEXT

The topic description filter

Returns

\?arrayThe array of topics (null: error)

Find whether a forum is threaded.

topic_is_threaded(integer $topic_id) : boolean
Inherited

Parameters

$topic_id

integer

The topic ID

Returns

booleanWhether it is

Get a URL to the specified topic ID. Most forums don't require the second parameter, but some do, so it is required in the interface.

topic_url(integer $id, string $forum) : \URLPATH

Parameters

$id

integer

The topic ID

$forum

string

The forum ID

Returns

\URLPATHThe URL to the topic

Get a URL to a forum 'user online' list.

users_online_url(boolean $tempcode_okay = false) : mixed
Inherited

Parameters

$tempcode_okay

boolean

Whether it is okay to return the result using Tempcode (more efficient)

Returns

mixedThe URL

Get a URL to the specified forum.

_forum_url(integer $id) : \URLPATH

Parameters

$id

integer

The forum ID

Returns

\URLPATHThe URL to the specified forum

Get the e-mail address for the specified member ID.

_get_member_email_address(\MEMBER $member) : \SHORT_TEXT

Parameters

$member

\MEMBER

The member ID

Returns

\SHORT_TEXTThe e-mail address

Get the number of new forum posts.

_get_num_new_forum_posts() : integer

Returns

integerThe number of posts

Get the name relating to the specified member ID.

_get_username(\MEMBER $member) : \?SHORT_TEXT

If this returns NULL, then the member has been deleted. Always take potential NULL output into account.

Parameters

$member

\MEMBER

The member ID

Returns

\?SHORT_TEXTThe member name (null: member deleted)

Get a URL to the registration page (for people to create member accounts).

_join_url() : \URLPATH

Returns

\URLPATHThe URL to the registration page

Get a URL to send a private/personal message to the given member.

_member_pm_url(\MEMBER $id) : \URLPATH

Parameters

$id

\MEMBER

The member ID

Returns

\URLPATHThe URL to the private/personal message page

Get a URL to the specified member's profile.

_member_profile_url(\MEMBER $id) : \URLPATH

Parameters

$id

\MEMBER

The member ID

Returns

\URLPATHThe URL to the member profile

Get a URL to the members-online page.

_users_online_url() : \URLPATH

Returns

\URLPATHThe URL to the members-online page

 Properties

 

$EMOTICON_CACHE

$EMOTICON_CACHE 

Default

null
 

$MEMBER_ROWS_CACHED

$MEMBER_ROWS_CACHED 

Default

array()
 

$connection

$connection 

Default