Documentation

Poll
in package
implements ArrayAccess uses 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|null
$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>

Methods

__set()  : void
Sets custom properties.
addChoice()  : void
Adds a new PollChoice object to $this->choices.
buildPermissions()  : void
Sets the values of $this->permissions.
canGuestsVote()  : bool
Figures out whether guests are allowed to vote in this board.
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()  : self
Creates a new instance of this class based on input from $_POST.
format()  : array<string|int, mixed>
Formats the poll data for use in templates.
load()  : self
Static wrapper for constructor.
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.
resetVotes()  : void
Resets the votes on this poll.
save()  : void
Saves this poll to the database.
__construct()  : mixed
Constructor. Protected to force instantiation via self::load() or self::create().
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|null $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 created 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 = 0

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.

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.

canGuestsVote()

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

public static canGuestsVote() : bool
Return values
bool —

Whether guests can vote.

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(self $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 : self

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(self $poll) : bool
Parameters
$poll : self

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 = [] ]) : self

Checks permissions and sanitizes input before doing anything.

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

Will hold errors encountered while creating the poll.

Return values
self —

An instance of this class, or null on failure.

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 ]) : self
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
self —

An instance of this class.

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.

Return values
mixed —

A reference to the property.

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.

resetVotes()

Resets the votes on this poll.

public resetVotes() : void

save()

Saves this poll to the database.

public save() : void

__construct()

Constructor. Protected to force instantiation 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.

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(array<string|int, mixed> &$errors) : void
Parameters
$errors : array<string|int, 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