Documentation

Poll
in package
implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Represents a poll.

Contains methods for doing just about everything regarding polls.

Table of Contents

Interfaces

ArrayAccess

Constants

CHECK_ACCESS  = 8
CHECK_EXPIRY  = 64
CHECK_IGNORE  = 16
CHECK_LOCKED  = 32
LOAD_BY_ID  = 0
LOAD_BY_RECENT  = 2
LOAD_BY_TOPIC  = 1
LOAD_BY_VOTES  = 4

Properties

$change_vote  : bool
$choices  : array<string|int, mixed>
$expire_time  : int
$formatted  : array<string|int, mixed>
$guest_vote  : bool
$has_voted  : bool
$hide_results  : int
$id  : int
$loaded  : array<string|int, mixed>
$max_votes  : int
$member  : int
$num_guest_voters  : int
$permissions  : array<string|int, mixed>
$poster_name  : string
$question  : string
$reset_poll  : int
$topic  : int
$total  : int
$total_voters  : int
$voters  : array<string|int, mixed>
$voting_locked  : int
$guest_vote_enabled  : bool
$joins  : array<string|int, mixed>
$order  : array<string|int, mixed>
$params  : array<string|int, mixed>
$prop_aliases  : array<string|int, mixed>
$selects  : array<string|int, mixed>
$where  : array<string|int, mixed>
$backcompat  : array<string|int, mixed>

Methods

__set()  : void
Sets custom properties.
addChoice()  : void
Adds a new PollChoice object to $this->choices.
buildPermissions()  : void
Sets the values of $this->permissions.
checkCreatePermission()  : bool
Verifies that the current user is allowed to create polls in this board.
checkEditPermission()  : bool
Verifies that the current user is allowed to edit the given poll.
checkRemovePermission()  : bool
Verifies that the current user is allowed to remove the given poll.
create()  : object
Creates a new instance of this class based on input from $_POST.
edit()  : void
Display screen for editing or adding a poll.
edit2()  : void
Update the settings for a poll, or add a new one.
exportStatic()  : void
Provides a way to export a class's public static properties and methods to global namespace.
format()  : array<string|int, mixed>
Formats the poll data for use in templates.
load()  : object
Static wrapper for constructor.
lock()  : void
Lock the voting for a poll.
offsetExists()  : bool
Checks whether a property has been set when object is accessed as an array.
offsetGet()  : mixed
Gets properties when object is accessed as an array.
offsetSet()  : void
Sets properties when object is accessed as an array.
offsetUnset()  : void
Unsets properties when object is accessed as an array.
remove()  : mixed
Remove a poll from a topic without removing the topic.
resetVotes()  : void
Resets the votes on this poll.
save()  : void
Saves this poll to the database.
vote()  : void
Allow the user to vote.
__construct()  : mixed
Constructor. Protected to force instantation via self::load() or self::create().
canGuestsVote()  : bool
Figures out whether guests are allowed to vote in this board.
checkAccess()  : void
If requested by the query options, adds SQL statements to the query variables to ensure that results exclude polls the user can't see.
checkExpiry()  : void
If requested by the query options, adds SQL statements to the query variables to ensure that results exclude expired polls.
checkLocked()  : void
If requested by the query options, adds SQL statements to the query variables to ensure that results exclude locked polls.
getMostActive()  : int
Gets the ID of the poll with the most voting activity.
getMostRecent()  : int
Gets the ID of the most recent poll.
getVoters()  : void
Gets the IDs of members who have voted in this poll.
initNewPoll()  : void
Sets object properties based on retrieved database rows.
loadPollData()  : void
Loads data about a poll.
resetQueryOptions()  : void
Resets query options and query variables to the default values.
sanitizeInput()  : void
Validates and sanitizes $_POST input for creating or editing a poll.
setProperties()  : void
Sets object properties based on retrieved database rows.

Constants

CHECK_ACCESS

public mixed CHECK_ACCESS = 8

CHECK_EXPIRY

public mixed CHECK_EXPIRY = 64

CHECK_IGNORE

public mixed CHECK_IGNORE = 16

CHECK_LOCKED

public mixed CHECK_LOCKED = 32

LOAD_BY_ID

public mixed LOAD_BY_ID = 0

LOAD_BY_RECENT

public mixed LOAD_BY_RECENT = 2

LOAD_BY_TOPIC

public mixed LOAD_BY_TOPIC = 1

LOAD_BY_VOTES

public mixed LOAD_BY_VOTES = 4

Properties

$change_vote

public bool $change_vote = false

Whether users can change their votes.

$choices

public array<string|int, mixed> $choices = []

The available choices for this poll.

$expire_time

public int $expire_time = 0

Unix timestamp when the poll closes.

$formatted

public array<string|int, mixed> $formatted = []

Formatted versions of this poll's properties, suitable for display.

$guest_vote

public bool $guest_vote = false

Whether guests can vote in this poll.

Even if this is true, they can only vote if self::$guest_vote_enabled is also true.

$has_voted

public bool $has_voted = false

Whether the current user has voted in this poll.

$hide_results

public int $hide_results = 0

The mode for hiding or showing results to the user.

$id

public int $id

This poll's ID number.

$loaded

public static array<string|int, mixed> $loaded = []

All loaded instances of this class.

$max_votes

public int $max_votes = 1

How many different choices the user can vote for. In other words, values greater than one mean multiple choice.

$member

public int $member = 0

ID of the member who created the poll.

$num_guest_voters

public int $num_guest_voters = 0

How many guests have voted.

$permissions

public array<string|int, mixed> $permissions = ['allow_lock_poll' => false, 'allow_edit_poll' => false, 'can_remove_poll' => false, 'allow_vote' => false, 'allow_results_view' => false, 'allow_change_vote' => false, 'allow_return_vote' => false]

Permissions that the current user has regarding this poll.

$poster_name

public string $poster_name = ''

Name of the member who creted the poll.

$question

public string $question = ''

The question for this poll.

$reset_poll

public int $reset_poll = 0

Unix timestamp when the poll's votes were reset.

If zero, the poll has never been reset.

$topic

public int $topic

ID of this poll's topic.

$total

public int $total = 0

Total number of votes cast in this poll.

$total_voters

public int $total_voters = 0

Total number of votes cast in this poll.

$voters

public array<string|int, mixed> $voters = []

IDs of members who have voted in this poll.

$voting_locked

public int $voting_locked = 0

Whether voting is locked for this poll. 0 = not locked, 1 = locked by user, 2 = locked by moderator.

$guest_vote_enabled

protected static bool $guest_vote_enabled

Whether guests can vote in this board.

Even if this is true, they can only vote in a particular poll if $this->guest_vote is also true.

$joins

protected array<string|int, mixed> $joins = ['pc' => 'LEFT JOIN {db_prefix}poll_choices AS pc ON (pc.id_poll = p.id_poll)', 'mem' => 'LEFT JOIN {db_prefix}members AS mem ON (mem.id_member = p.id_member)']

SQL join statements to use when loading data.

$order

protected array<string|int, mixed> $order = ['p.id_poll DESC']

SQL order by statements to use when loading data.

$params

protected array<string|int, mixed> $params = []

Parameters for the SQL query when loading data.

$prop_aliases

protected array<string|int, mixed> $prop_aliases = ['id_poll' => 'id', 'id_member' => 'member', 'expire' => 'expire_time', 'hide' => 'hide_results', 'id_topic' => 'topic', 'options' => 'choices']

Alternate names for some object properties.

$selects

protected array<string|int, mixed> $selects = ['pc.*', 'p.*', 'COALESCE(mem.real_name, p.poster_name) AS poster_name']

SQL select statements to use when loading data.

$where

protected array<string|int, mixed> $where = ['1=1']

SQL where statements to use when loading data.

$backcompat

private static array<string|int, mixed> $backcompat = ['func_names' => ['checkRemovePermission' => 'checkRemovePermission', 'vote' => 'Vote', 'lock' => 'LockVoting', 'edit' => 'EditPoll', 'edit2' => 'EditPoll2', 'remove' => 'RemovePoll']]

BackwardCompatibility settings for this class.

Methods

__set()

Sets custom properties.

public __set(string $prop, mixed $value) : void
Parameters
$prop : string

The property name.

$value : mixed

The value to set.

addChoice()

Adds a new PollChoice object to $this->choices.

public addChoice(array<string|int, mixed> $choice_props[, bool $allow_empty = false ]) : void
Parameters
$choice_props : array<string|int, mixed>
$allow_empty : bool = false

buildPermissions()

Sets the values of $this->permissions.

public buildPermissions() : void

Used when deciding what the current user can do with an existing poll.

checkCreatePermission()

Verifies that the current user is allowed to create polls in this board.

public static checkCreatePermission() : bool

If polls are disabled, simply returns false. Otherwise, will die with a fatal error if the user can't make the poll, or return true if they can.

Return values
bool —

Whether the current user can create a poll.

checkEditPermission()

Verifies that the current user is allowed to edit the given poll.

public static checkEditPermission(object $poll) : bool

If polls are disabled or the poll doesn't have an ID number, simply returns false. Otherwise, will die with a fatal error if the user can't edit the poll, or return true if they can.

Parameters
$poll : object

An instance of this class.

Return values
bool —

Whether the current user can edit this poll.

checkRemovePermission()

Verifies that the current user is allowed to remove the given poll.

public static checkRemovePermission(object $poll) : bool
Parameters
$poll : object

An instance of this class.

Return values
bool —

Whether the current user can remove this poll.

create()

Creates a new instance of this class based on input from $_POST.

public static create([array<string|int, mixed> &$errors = [] ]) : object

Checks permissions and sanitizes input before doing anything.

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

Will hold errors encountered while creating the poll.

Return values
object —

An instance of this class, or null on failure.

edit()

Display screen for editing or adding a poll.

public static edit() : void

Must be called with a topic specified in the URL. If the user is adding a poll to a topic, must contain the variable 'add' in the url. User must have poll_edit_any/poll_add_any permission for the relevant action, otherwise must be poll starter with poll_edit_own permission for editing, or be topic starter with poll_add_any permission for adding. Accessed via ?action=editpoll.

Uses Post language file. Uses Poll template, main sub-template.

edit2()

Update the settings for a poll, or add a new one.

public static edit2() : void

Must be called with a topic specified in the URL. The user must have poll_edit_any/poll_add_any permission for the relevant action. Otherwise they must be poll starter with poll_edit_own permission for editing, or be topic starter with poll_add_any permission for adding. In the case of an error, this function will redirect back to EditPoll and display the relevant error message. Upon successful completion of action will direct user back to topic. Accessed via ?action=editpoll2.

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.

public static exportStatic() : void

To do so:

  1. Use this trait in the class.
  2. At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

format()

Formats the poll data for use in templates.

public format([array<string|int, mixed> $format_options = [] ]) : array<string|int, mixed>

Result will include everything necessary to vote, view, or edit.

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

Options to control output.

Return values
array<string|int, mixed> —

A copy of $this->formatted.

load()

Static wrapper for constructor.

public static load(int $id[, int $options = 0 ]) : object
Parameters
$id : int

The ID number of a poll or topic. Use 0 if unknown.

$options : int = 0

Bitmask of this class's LOAD_* and CHECK_* constants.

Return values
object —

An instance of this class.

lock()

Lock the voting for a poll.

public static lock() : void

Must be called with a topic specified in the URL. An admin always has overriding permission to lock a poll. If not an admin must have poll_lock_any permission, otherwise must be poll starter with poll_lock_own permission. Upon successful completion of action will direct user back to topic. Accessed via ?action=lockvoting.

offsetExists()

Checks whether a property has been set when object is accessed as an array.

public offsetExists(mixed $prop) : bool
Parameters
$prop : mixed

The property name.

Return values
bool

offsetGet()

Gets properties when object is accessed as an array.

public offsetGet(mixed $prop) : mixed
Parameters
$prop : mixed

The property name.

offsetSet()

Sets properties when object is accessed as an array.

public offsetSet(mixed $prop, mixed $value) : void
Parameters
$prop : mixed

The property name.

$value : mixed

The value to set.

offsetUnset()

Unsets properties when object is accessed as an array.

public offsetUnset(mixed $prop) : void
Parameters
$prop : mixed

The property name.

remove()

Remove a poll from a topic without removing the topic.

public static remove() : mixed

Must be called with a topic specified in the URL. Requires poll_remove_any permission, unless it's the poll starter with poll_remove_own permission. Upon successful completion of action will direct user back to topic. Accessed via ?action=removepoll.

resetVotes()

Resets the votes on this poll.

public resetVotes() : void

save()

Saves this poll to the database.

public save() : void

vote()

Allow the user to vote.

public static vote() : void

It is called to record a vote in a poll. Must be called with a topic and option specified. Requires the poll_vote permission. Upon successful completion of action will direct user back to topic. Accessed via ?action=vote.

Uses Post language file.

__construct()

Constructor. Protected to force instantation via self::load() or self::create().

protected __construct([int $id = 0 ][, int $options = 0 ]) : mixed
Parameters
$id : int = 0

The ID number of a poll or topic. Use 0 if unknown.

$options : int = 0

Bitmask of this class's LOAD_* and CHECK_* constants.

canGuestsVote()

Figures out whether guests are allowed to vote in this board.

protected static canGuestsVote() : bool
Return values
bool —

Whether guests can vote.

checkAccess()

If requested by the query options, adds SQL statements to the query variables to ensure that results exclude polls the user can't see.

protected checkAccess(int $options) : void
Parameters
$options : int

The query options passed to the constructor.

checkExpiry()

If requested by the query options, adds SQL statements to the query variables to ensure that results exclude expired polls.

protected checkExpiry(int $options) : void
Parameters
$options : int

The query options passed to the constructor.

checkLocked()

If requested by the query options, adds SQL statements to the query variables to ensure that results exclude locked polls.

protected checkLocked(int $options) : void
Parameters
$options : int

The query options passed to the constructor.

getMostActive()

Gets the ID of the poll with the most voting activity.

protected getMostActive(int &$options) : int
Parameters
$options : int

The query options passed to the constructor.

Return values
int —

ID of the most active poll.

getMostRecent()

Gets the ID of the most recent poll.

protected getMostRecent(int &$options) : int
Parameters
$options : int

The query options passed to the constructor.

Return values
int —

ID of the most recent poll.

getVoters()

Gets the IDs of members who have voted in this poll.

protected getVoters() : void

initNewPoll()

Sets object properties based on retrieved database rows.

protected initNewPoll() : void

loadPollData()

Loads data about a poll.

protected loadPollData(int $id, int $load_by, int &$options) : void
Parameters
$id : int

The ID number of a poll or topic.

$load_by : int

One of the LOAD_* constants.

$options : int

The query options passed to the constructor.

resetQueryOptions()

Resets query options and query variables to the default values.

protected resetQueryOptions(int &$options) : void
Parameters
$options : int

The query options passed to the constructor.

sanitizeInput()

Validates and sanitizes $_POST input for creating or editing a poll.

protected static sanitizeInput(mixed &$errors) : void
Parameters
$errors : mixed

setProperties()

Sets object properties based on retrieved database rows.

protected setProperties(array<string|int, mixed> $row) : void
Parameters
$row : array<string|int, mixed>

A row from the database.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results