Documentation

Category
in package

SMF

implements ArrayAccess uses BackwardCompatibility, ArrayAccessHelper

This class loads information about categories. It also handles low-level tasks for managing categories, such as creating, deleting, and modifying them.

Implements the \ArrayAccess interface to ease backward compatibility with the deprecated global $cat_tree variable.

Interfaces

ArrayAccess

Properties

$boardList : array<string|int, mixed>
$can_collapse : bool
$children : array<string|int, mixed>
$css_class : string
$description : string
$header_link : string
$id : int
$is_collapsed : bool
$last_board_order : int
$link : string
$loaded : array<string|int, mixed>
$name : string
$new : bool
$order : int
$show_unread : bool
$url : string
$parsed_descriptions : array<string|int, mixed>
$prop_aliases : array<string|int, mixed>
$tree_order : array<string|int, mixed>
$backcompat : array<string|int, mixed>

Methods

create() : int: Create a new category.
delete() : void: Remove one or more categories.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
getTree() : void: Load a lot of useful information regarding the boards and categories.
getTreeOrder() : array<string|int, mixed>: Tries to load up the entire board order and category very very quickly Returns an array with two elements, cats and boards
init() : self|null: Creates a new instance of this class if necessary, or updates an existing instance if one already exists for the given ID number. In either case, the instance will be returned.
load() : array<string|int, mixed>: Loads categories by ID number and/or by custom query.
modify() : void: Edit the position and properties of a category.
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.
parseDescription() : void: Parses BBCode in $this->description and updates it with the result.
recursiveBoards() : void: Recursively get a list of boards.
sort() : void: Takes a category array and sorts it
unparseDescription() : void: Restores $this->description to its unparsed value.
__construct() : mixed: Constructor. Protected to force instantiation via Category::init() or Category::load().
queryData() : Generator<string|int, array<string|int, mixed>>: Generator that runs queries about category data and yields the result rows.

$boardList


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

A list of boards grouped by category ID.

$can_collapse


    public
        bool
    $can_collapse

Whether this category is collapsible.

$children


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

Boards that are children of this category.

$css_class


    public
        string
    $css_class

A space-separated list of CSS classes.

$description


    public
        string
    $description

This category's description.

$header_link


    public
        string
    $header_link

HTML anchor link for this category. Used in board index table headers.

$id


    public
        int
    $id

This category's ID number.

$is_collapsed


    public
        bool
    $is_collapsed

Whether the current user has collapsed this category.

$last_board_order


    public
        int
    $last_board_order

The positional order of the board immediately before this category.

$link


    public
        string
    $link

HTML anchor link for this category.

$loaded


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

All loaded instances of this class.

$name


    public
        string
    $name

This category's name.

$new


    public
        bool
    $new

Whether this category contains posts that the current user hasn't read.

$order


    public
        int
    $order

The positional order of this category.

$show_unread


    public
        bool
    $show_unread

Whether to show an unread link for this category.

$url


    public
        string
    $url

URL for this category.

$parsed_descriptions


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

Holds parsed versions of category descriptions.

$prop_aliases


    protected
        array<string|int, mixed>
    $prop_aliases
     = ['id_cat' => 'id', 'cat_order' => 'order', 'href' => 'url', 'boards' => 'children']

Alternate names for some object properties.

$tree_order


    protected
    static    array<string|int, mixed>
    $tree_order
     = ['cats' => [], 'boards' => []]

Holds results of Category::getTreeOrder().

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['prop_names' => ['loaded' => 'cat_tree', 'boardList' => 'boardList']]

BackwardCompatibility settings for this class.

create()

Create a new category.


    public
            static        create(array<string|int, mixed> $catOptions) : int

General function to create a new category and set its position. Allows (almost) the same options as the modifyCat() function.

Parameters

$catOptions : array<string|int, mixed>: An array of data and settings related to the new category. Should contain 'cat_name' and can also have 'cat_desc', 'move_after' and 'is_collapsable'.

Return values

int —

ID of the newly created category.

delete()

Remove one or more categories.


    public
            static        delete(array<string|int, mixed> $categories[, int $moveBoardsTo = null ]) : void

general function to delete one or more categories. allows to move all boards in the categories to a different category before deleting them. if moveChildrenTo is set to null, all boards inside the given categories will be deleted. deletes all information that's associated with the given categories. updates the statistics to reflect the new situation.

Parameters

$categories : array<string|int, mixed>: The IDs of the categories to delete
$moveBoardsTo : int = null: The ID of the category to move any boards to or null to delete the boards

exportStatic()

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


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
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'].

$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.

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

getTree()

Load a lot of useful information regarding the boards and categories.


    public
            static        getTree() : void

The information retrieved is stored in static properties: Board::$loaded Instances of SMF\Board for each board. Category::$boardList A list of board IDs grouped by category ID. Category::$loaded Complete hierarchy of all categories and boards.

getTreeOrder()

Tries to load up the entire board order and category very very quickly Returns an array with two elements, cats and boards


    public
            static        getTreeOrder() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of categories and boards

init()

Creates a new instance of this class if necessary, or updates an existing instance if one already exists for the given ID number. In either case, the instance will be returned.


    public
            static        init(int $id[, array<string|int, mixed> $props = [] ]) : self|null

If an instance already exists for the given ID number, then $props will simply be passed to the existing instance's set() method, and then the existing instance will be returned.

If an instance does not exist for the given ID number and $props is empty, a query will be performed to populate the properties with data from the categories table.

Parameters

$id : int: The ID number of the category.
$props : array<string|int, mixed> = []: Array of properties to set.

Return values

self|null —

An instance of this class.

load()

Loads categories by ID number and/or by custom query.


    public
            static        load([array<string|int, mixed>|int $ids = [] ][, array<string|int, mixed> $query_customizations = [] ]) : array<string|int, mixed>

If both arguments are empty, loads all categories.

Parameters

$ids : array<string|int, mixed>|int = []: The ID numbers of zero or more categories.
$query_customizations : array<string|int, mixed> = []: Customizations to the SQL query.

Return values

array<string|int, mixed> —

Instances of this class for the loaded categories.

modify()

Edit the position and properties of a category.


    public
            static        modify(int $category_id, array<string|int, mixed> $catOptions) : void

general function to modify the settings and position of a category. used by ManageBoards.php to change the settings of a category.

Parameters

$category_id : int: The ID of the category
$catOptions : array<string|int, mixed>: An array containing data and options related to the category

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.

parseDescription()

Parses BBCode in $this->description and updates it with the result.


    public
                    parseDescription() : void

recursiveBoards()

Recursively get a list of boards.


    public
            static        recursiveBoards(array<string|int, mixed> &$list, Category|Board &$tree) : void

Used by self::getTree().

Parameters

$list : array<string|int, mixed>: The board list
$tree : Category|Board: The board tree

sort()

Takes a category array and sorts it


    public
            static        sort(array<string|int, mixed> &$categories) : void

Parameters

$categories : array<string|int, mixed>: The categories

unparseDescription()

Restores $this->description to its unparsed value.


    public
                    unparseDescription() : void

__construct()

Constructor. Protected to force instantiation via Category::init() or Category::load().


    protected
                    __construct(int $id[, array<string|int, mixed> $props = [] ]) : mixed

Creates an instance for the give ID number, sets any properties supplied in $props, and adds the instance to the Category::$loaded array.

If $props is empty, a query will be performed to populate the properties with data from the categories table.

Parameters

$id : int: The ID number of the category.
$props : array<string|int, mixed> = []: Array of properties to set.

queryData()

Generator that runs queries about category data and yields the result rows.


    protected
            static        queryData(array<string|int, mixed> $selects[, array<string|int, mixed> $params = [] ][, array<string|int, mixed> $joins = [] ][, array<string|int, mixed> $where = [] ][, array<string|int, mixed> $order = [] ][, array<string|int, mixed> $group = [] ][, int|string $limit = 0 ]) : Generator<string|int, array<string|int, mixed>>

Parameters

$selects : array<string|int, mixed>: Table columns to select.
$params : array<string|int, mixed> = []: Parameters to substitute into query text.
$joins : array<string|int, mixed> = []: Zero or more complete JOIN clauses. E.g.: 'LEFT JOIN {db_prefix}boards AS b ON (c.id_cat = b.id_cat)' Note: 'FROM {db_prefix}categories AS c' is always part of the query.
$where : array<string|int, mixed> = []: Zero or more conditions for the WHERE clause. Conditions will be placed in parentheses and concatenated with AND. If this is left empty, no WHERE clause will be used.
$order : array<string|int, mixed> = []: Zero or more conditions for the ORDER BY clause. If this is left empty, no ORDER BY clause will be used.
$group : array<string|int, mixed> = []: Zero or more conditions for the GROUP BY clause. If this is left empty, no GROUP BY clause will be used.
$limit : int|string = 0: Maximum number of results to retrieve. If this is left empty, all results will be retrieved.

Return values

Generator<string|int, array<string|int, mixed>> —

Iterating over the result gives database rows.

Category in package SMF implements ArrayAccess uses BackwardCompatibility, ArrayAccessHelper

Tags

Table of Contents

Interfaces

Properties

Methods

Properties

$boardList

$can_collapse

$children

$css_class

$description

$header_link

$id

$is_collapsed

$last_board_order

$link

$loaded

$name

$new

$order

$show_unread

$url

$parsed_descriptions

$prop_aliases

$tree_order

$backcompat

Methods

create()

Parameters

Return values

delete()

Parameters

exportStatic()

getTree()

getTreeOrder()

Return values

init()

Parameters

Return values

load()

Parameters

Return values

modify()

Parameters

offsetExists()

Parameters

Return values

offsetGet()

Parameters

Return values

offsetSet()

Parameters

offsetUnset()

Parameters

parseDescription()

recursiveBoards()

Parameters

sort()

Parameters

unparseDescription()

__construct()

Parameters

queryData()

Parameters

Return values

Category
in package

SMF

implements ArrayAccess uses BackwardCompatibility, ArrayAccessHelper