Documentation

Bans
in package
implements ActionInterface uses ActionTrait, BackwardCompatibility

This class contains all the methods used for the ban center.

Table of Contents

Interfaces

ActionInterface
Interface for all action classes.

Properties

$subaction  : string
$subactions  : array<string|int, mixed>
$obj  : static

Methods

browseTriggers()  : void
This handles the screen for showing the banned entities.
call()  : void
Convenience method to load() and execute() an instance of this class.
canBeLogged()  : bool
Determines whether this action can be logged in the online log.
canShowDebuggingInfo()  : bool
Determines whether debugging info should be shown.
canShowInMaintenanceMode()  : bool
Determines whether this action allows access in maintenance mode.
edit()  : void
Adds new bans and modifies existing ones.
editTrigger()  : void
This function handles the ins and outs of the screen for adding new ban triggers or modifying existing ones.
execute()  : void
Dispatcher to whichever sub-action method is necessary.
getOutputType()  : OutputTypeInterface
Gets the output type for this action.
isAgreementAction()  : bool
Determines whether this action can be accessed without accepting the registration agreement and privacy policy.
isRestrictedGuestAccessAllowed()  : bool
Determines whether this action allows access if guest access is restricted.
isSimpleAction()  : bool
Determines whether this is a simple action.
list()  : void
Shows a list of bans currently set.
list_getBanItems()  : array<string|int, mixed>
Retrieves all the ban items belonging to a certain ban group
list_getBanLogEntries()  : array<string|int, mixed>
Load a list of ban log entries from the database.
list_getBans()  : array<string|int, mixed>
Get bans, what else? For the given options.
list_getBanTriggers()  : array<string|int, mixed>
Gets ban triggers for the given parameters.
list_getNumBanItems()  : int
Gets the number of ban items belonging to a certain ban group
list_getNumBanLogEntries()  : int
This returns the total count of ban log entries. Callback for $listOptions['get_count'] in BanLog().
list_getNumBans()  : int
Get the total number of ban from the ban group table
list_getNumBanTriggers()  : int
Returns the total number of ban triggers of the given type.
load()  : static
Static wrapper for constructor.
log()  : void
This handles the listing of ban log entries, and allows their deletion.
subActionProvider()  : null|array<string|int, mixed>
Called by Subs-Compat.php BackwardCompatibility wrapper functions to provide subaction execution for existing mods
updateBanMembers()  : void
As it says... this tries to review the list of banned members, to match new bans.
__construct()  : mixed
Constructor. Protected to force instantiation via self::load().
addTriggers()  : bool
This function actually inserts the ban triggers into the database.
banLoadAdditionalIPs()  : array<string|int, mixed>
Finds additional IPs related to a certain user
banLoadAdditionalIPsError()  : array<string|int, mixed>
Loads additional IPs used by a member from the error log
banLoadAdditionalIPsMember()  : array<string|int, mixed>
Loads additional IPs used by a specific member
checkExistingTriggerIP()  : bool
Checks whether a given IP range already exists in the trigger list.
edit2()  : void
This method handles submitted forms that add, modify or remove ban triggers.
getMemberData()  : array<string|int, mixed>
Gets basic member data for the ban.
init()  : mixed
Does some initial setup.
insertBanGroup()  : int|false
Creates a new ban group.
logTriggersUpdates()  : void
A small function to unify logging of triggers (updates and new)
removeBanGroups()  : bool
This function removes a bunch of ban groups based on ids.
removeBanLogs()  : bool
Removes logs.
removeBanTriggers()  : bool
This function removes a bunch of triggers based on IDs.
saveTriggers()  : array<string|int, mixed>
Saves one or more ban triggers into a ban item.
updateBanGroup()  : int
Updates an existing ban group.
updateTriggers()  : void
Updates an existing ban trigger in the database.
validateTriggers()  : array<string|int, mixed>
This function validates the ban triggers

Properties

$subaction

public string $subaction = 'list'

The requested sub-action. This should be set by the constructor.

$subactions

public static array<string|int, mixed> $subactions = ['list' => 'list', 'edit' => 'edit', 'add' => 'edit', 'browse' => 'browseTriggers', 'edittrigger' => 'editTrigger', 'log' => 'log']

Available sub-actions.

$obj

protected static static $obj

An instance of this class. This is used by the load() method to prevent multiple instantiations.

Methods

browseTriggers()

This handles the screen for showing the banned entities.

public browseTriggers() : void

It is accessed by ?action=admin;area=ban;sa=browse It uses sub-tabs for browsing by IP, hostname, email or username.

Uses a standard list (@see SMF\ItemList())

call()

Convenience method to load() and execute() an instance of this class.

public static call() : void

canBeLogged()

Determines whether this action can be logged in the online log.

public canBeLogged() : bool
Return values
bool

canShowDebuggingInfo()

Determines whether debugging info should be shown.

public canShowDebuggingInfo() : bool
Return values
bool

canShowInMaintenanceMode()

Determines whether this action allows access in maintenance mode.

public canShowInMaintenanceMode() : bool
Return values
bool —

True if access is allowed, false otherwise.

edit()

Adds new bans and modifies existing ones.

public edit() : void

Adding new bans: - is accessed by ?action=admin;area=ban;sa=add.

Modifying existing bans:

  • is accessed by ?action=admin;area=ban;sa=edit;bg=x
  • shows a list of ban triggers for the specified ban.

editTrigger()

This function handles the ins and outs of the screen for adding new ban triggers or modifying existing ones.

public editTrigger() : void

Adding new ban triggers: - is accessed by ?action=admin;area=ban;sa=edittrigger;bg=x - uses the ban_edit_trigger sub template of ManageBans.

Editing existing ban triggers:

  • is accessed by ?action=admin;area=ban;sa=edittrigger;bg=x;bi=y
  • uses the ban_edit_trigger sub template of ManageBans.

execute()

Dispatcher to whichever sub-action method is necessary.

public execute() : void

isAgreementAction()

Determines whether this action can be accessed without accepting the registration agreement and privacy policy.

public isAgreementAction() : bool
Return values
bool

isRestrictedGuestAccessAllowed()

Determines whether this action allows access if guest access is restricted.

public isRestrictedGuestAccessAllowed() : bool
Return values
bool —

True if access is allowed, false otherwise.

isSimpleAction()

Determines whether this is a simple action.

public isSimpleAction() : bool
Return values
bool

list()

Shows a list of bans currently set.

public list() : void

It is accessed by ?action=admin;area=ban;sa=list. It removes expired bans. It allows sorting on different criteria. It also handles removal of selected ban items.

list_getBanItems()

Retrieves all the ban items belonging to a certain ban group

public static list_getBanItems([int $start = 0 ][, int $items_per_page = 0 ][, string $sort = '' ][, int $ban_group_id = 0 ]) : array<string|int, mixed>
Parameters
$start : int = 0

Which item to start with (for pagination purposes)

$items_per_page : int = 0

How many items to show on each page

$sort : string = ''

Not used here

$ban_group_id : int = 0

The ID of the group to get the bans for

Return values
array<string|int, mixed> —

An array with information about the returned ban items

list_getBanLogEntries()

Load a list of ban log entries from the database.

public static list_getBanLogEntries(int $start, int $items_per_page, string $sort) : array<string|int, mixed>

(no permissions check). Callback for $listOptions['get_items'] in BanLog()

Parameters
$start : int

The item to start with (for pagination purposes)

$items_per_page : int

How many items to show on each page

$sort : string

A string telling ORDER BY how to sort the results

Return values
array<string|int, mixed> —

An array of info about the ban log entries for the list.

list_getBans()

Get bans, what else? For the given options.

public static list_getBans(int $start, int $items_per_page, string $sort) : array<string|int, mixed>
Parameters
$start : int

Which item to start with (for pagination purposes)

$items_per_page : int

How many items to show on each page

$sort : string

A string telling ORDER BY how to sort the results

Return values
array<string|int, mixed> —

An array of information about the bans for the list

list_getBanTriggers()

Gets ban triggers for the given parameters.

public static list_getBanTriggers(int $start, int $items_per_page, string $sort, string $trigger_type) : array<string|int, mixed>

Callback for $listOptions['get_items'] in BanBrowseTriggers().

Parameters
$start : int

The item to start with (for pagination purposes)

$items_per_page : int

How many items to show on each page

$sort : string

A string telling ORDER BY how to sort the results

$trigger_type : string

The trigger type - can be 'ip', 'hostname' or 'email'

Return values
array<string|int, mixed> —

An array of ban trigger info for the list

list_getNumBanItems()

Gets the number of ban items belonging to a certain ban group

public static list_getNumBanItems() : int
Return values
int —

The number of ban items

list_getNumBanLogEntries()

This returns the total count of ban log entries. Callback for $listOptions['get_count'] in BanLog().

public static list_getNumBanLogEntries() : int
Return values
int —

The total number of ban log entries.

list_getNumBans()

Get the total number of ban from the ban group table

public static list_getNumBans() : int
Return values
int —

The total number of bans

list_getNumBanTriggers()

Returns the total number of ban triggers of the given type.

public static list_getNumBanTriggers(string $trigger_type) : int

Callback for $listOptions['get_count'] in BanBrowseTriggers().

Parameters
$trigger_type : string

The trigger type. Can be 'ip', 'hostname' or 'email'

Return values
int —

The number of triggers of the specified type

load()

Static wrapper for constructor.

public static load() : static
Return values
static —

An instance of this class.

log()

This handles the listing of ban log entries, and allows their deletion.

public log() : void

Shows a list of logged access attempts by banned users. It is accessed by ?action=admin;area=ban;sa=log. How it works:

  • allows sorting of several columns.
  • also handles deletion of (a selection of) log entries.

subActionProvider()

Called by Subs-Compat.php BackwardCompatibility wrapper functions to provide subaction execution for existing mods

public static subActionProvider([null|string $sa = null ][, bool $return_config = false ][, string|null $activity = null ]) : null|array<string|int, mixed>
Parameters
$sa : null|string = null
$return_config : bool = false
$activity : string|null = null
Return values
null|array<string|int, mixed>

updateBanMembers()

As it says... this tries to review the list of banned members, to match new bans.

public static updateBanMembers() : void

Note: if is_activated >= User::BANNED, then the member is banned.

__construct()

Constructor. Protected to force instantiation via self::load().

protected __construct() : mixed

addTriggers()

This function actually inserts the ban triggers into the database.

protected addTriggers([int $group_id = 0 ][, array<string|int, mixed> $triggers = [] ][, array<string|int, mixed> $logs = [] ]) : bool

Errors in Utils::$context['ban_errors']

Parameters
$group_id : int = 0

The ID of the group to add the triggers to. 0 to create a new one.

$triggers : array<string|int, mixed> = []

The triggers to add.

$logs : array<string|int, mixed> = []

The log data.

Return values
bool —

Whether or not the action was successful.

banLoadAdditionalIPs()

Finds additional IPs related to a certain user

protected banLoadAdditionalIPs(int $member_id) : array<string|int, mixed>
Parameters
$member_id : int

The ID of the member to get additional IPs for

Return values
array<string|int, mixed> —

An containing two arrays - ips_in_messages (IPs used in posts) and ips_in_errors (IPs used in error messages)

banLoadAdditionalIPsError()

Loads additional IPs used by a member from the error log

protected banLoadAdditionalIPsError(int $member_id) : array<string|int, mixed>
Parameters
$member_id : int

The ID of the member

Return values
array<string|int, mixed> —

An array of IPs associated with error messages generated by this user

banLoadAdditionalIPsMember()

Loads additional IPs used by a specific member

protected banLoadAdditionalIPsMember(int $member_id) : array<string|int, mixed>
Parameters
$member_id : int

The ID of the member

Return values
array<string|int, mixed> —

An array of IPs used in posts by this member

checkExistingTriggerIP()

Checks whether a given IP range already exists in the trigger list.

protected checkExistingTriggerIP(array<string|int, mixed> $ip_array[, string $fullip = '' ]) : bool
Parameters
$ip_array : array<string|int, mixed>

An array of IP trigger data.

$fullip : string = ''

The full IP.

Return values
bool —

Whether the IP trigger data is valid.

edit2()

This method handles submitted forms that add, modify or remove ban triggers.

protected edit2() : void

getMemberData()

Gets basic member data for the ban.

protected getMemberData(int $id) : array<string|int, mixed>
Parameters
$id : int

The ID of the member to get data for.

Return values
array<string|int, mixed> —

The ID, name, main IP, and email address of the member.

init()

Does some initial setup.

protected init() : mixed

insertBanGroup()

Creates a new ban group.

protected insertBanGroup([array<string|int, mixed> $ban_info = [] ]) : int|false

If the group is successfully created the ID is returned On error the error code is returned or false

Errors in Utils::$context['ban_errors']

Parameters
$ban_info : array<string|int, mixed> = []

An array containing 'name', which is the name of the ban group.

Return values
int|false —

The ban group's ID, or false on error.

logTriggersUpdates()

A small function to unify logging of triggers (updates and new)

protected static logTriggersUpdates(array<string|int, mixed> $logs[, bool $new = true ][, bool $removal = false ]) : void
Parameters
$logs : array<string|int, mixed>

an array of logs, each log contains the following keys:

  • bantype: a known type of ban (ip_range, hostname, email, user, main_ip)
  • value: the value of the bantype (e.g. the IP or the email address banned)
$new : bool = true

Whether the trigger is new or an update of an existing one

$removal : bool = false

Whether the trigger is being deleted

removeBanGroups()

This function removes a bunch of ban groups based on ids.

protected removeBanGroups(array<string|int, mixed> $group_ids) : bool

Doesn't clean the input.

Parameters
$group_ids : array<string|int, mixed>

The IDs of the groups to remove.

Return values
bool —

Returns true if successful or false if $group_ids is empty

removeBanLogs()

Removes logs.

protected removeBanLogs([array<string|int, mixed> $ids = [] ]) : bool

Doesn't clean the input.

Parameters
$ids : array<string|int, mixed> = []

IDs of the log entries to remove, or empty to remove all.

Return values
bool —

Returns true if successful or false if $ids is invalid.

removeBanTriggers()

This function removes a bunch of triggers based on IDs.

protected static removeBanTriggers([array<string|int, mixed>|int $items_ids = [] ][, int $group_id = null ]) : bool

Doesn't clean the inputs.

Parameters
$items_ids : array<string|int, mixed>|int = []

The triggers to remove.

$group_id : int = null

The ID of the group these triggers are associated with. If null, the triggers will be deleted from all groups.

Return values
bool —

Whether the operation was successful.

saveTriggers()

Saves one or more ban triggers into a ban item.

protected saveTriggers(array<string|int, mixed> $suggestions, int $ban_group[, int $member = 0 ][, int $ban_id = 0 ]) : array<string|int, mixed>

Checks the $_POST variable to verify that the trigger is present.

Parameters
$suggestions : array<string|int, mixed>

An array of suggested triggers (IP, email, etc.).

$ban_group : int

The ID of the group we're saving bans for.

$member : int = 0

The ID of the member associated with this ban (if applicable).

$ban_id : int = 0

The ID of the ban (0 if this is a new ban).

Return values
array<string|int, mixed> —

Triggers that encountered errors. Empty if triggers saved successfully.

updateBanGroup()

Updates an existing ban group.

protected updateBanGroup([array<string|int, mixed> $ban_info = [] ]) : int

Errors in Utils::$context['ban_errors']

Parameters
$ban_info : array<string|int, mixed> = []

An array of info about the ban group. Should have name and may also have an id.

Return values
int —

The ban group's ID.

updateTriggers()

Updates an existing ban trigger in the database.

protected updateTriggers([int $ban_item = 0 ][, int $group_id = 0 ][, array<string|int, mixed> $trigger = [] ][, array<string|int, mixed> $logs = [] ]) : void

Errors in Utils::$context['ban_errors']

Parameters
$ban_item : int = 0

The ID of the ban item.

$group_id : int = 0

The ID of the ban group.

$trigger : array<string|int, mixed> = []

An array of triggers.

$logs : array<string|int, mixed> = []

An array of log info.

validateTriggers()

This function validates the ban triggers

protected validateTriggers(array<string|int, mixed> &$triggers) : array<string|int, mixed>

Errors in Utils::$context['ban_errors']

Parameters
$triggers : array<string|int, mixed>

The triggers to validate

Return values
array<string|int, mixed> —

An array of riggers and log info ready to be used


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results