PHP Class CategoryModel, vanilla

Inheritance: extends Model
Exibir arquivo Open project: vanilla/vanilla Class Usage Examples

Public Properties

Property Type Description
$Categories Merged Category data, including Pure + UserCategory.
$JoinRecentUsers Whether or not to join users to recent posts. Forums with a lot of categories may need to optimize using this setting and simpler views.
$ShardCache Whether or not to explicitly shard the categories cache.
$Watching boolean

Public Methods

Method Description
__construct ( ) Class constructor. Defines the related database table name.
addCategoryColumns ( object $Data ) Modifies category data before it is returned.
allowedDiscussionTypes ( array $PermissionCategory, array $category = [] ) : array Checks the allowed discussion types on a category.
applyUpdates ( ) If looking at the root node, make sure it exists and that the nested set columns exist in the table.
calculateDisplayAs ( &$category ) Maintains backwards compatibilty with DisplayAs: Default-type categories by calculating the DisplayAs property into an expected DisplayAs type: Categories, Heading, or Discussions. Respects the now-deprecated config setting Vanilla.Categories.DoHeadings. Once we can be sure that all instances have their categories' DisplayAs properties explicitly set in the database (i.e., not Default) we can deprecate/remove this function.
categories ( integer | string | boolean $ID = false ) : array Gets either all of the categories or a single category.
categoryUrl ( $Category, string $Page = '', boolean | true $WithDomain = true ) : string Build URL to a category page.
categoryWatch ( $AllDiscussions = true ) : array
checkPermission ( array $category, string $permission ) : boolean Check a category's permission.
clearCache ( )
clearUserCache ( )
counts ( $Column ) : array
createCollection ( Gdn_SQLDriver $sql = null, Gdn_Cache $cache = null ) : CategoryCollection Create a new category collection tied to this model.
defaultCategory ( ) : mixed
delete ( $where = [], $options = [] ) Delete a category.
deleteAndReplace ( object $category, integer $newCategoryID ) Delete a single category and assign its discussions to another.
deleteID ( integer $categoryID, array $options = [] ) : boolean Delete a category.
filterCategoryPermissions ( array $categoryIDs ) : array Remove categories that a user does not have permission to view.
filterChildren ( array &$categories, string $childField = 'Children' ) Recursively remove children from categories configured to display as "Categories" or "Flat".
filterFollowing ( array $categories ) : array Filter a category tree to only the followed categories.
flattenTree ( array $categories ) : array Return a flattened version of a tree.
get ( string $OrderFields = '', string $OrderDirection = 'asc', integer $Limit = false, integer $Offset = false ) : Gdn_DataSet Get list of categories (respecting user permission).
getAll ( ) : object Get list of categories (disregarding user permission for admins).
getAncestors ( $categoryID, boolean $checkPermissions = true, boolean $includeHeadings = false ) : array Get all of the ancestor categories above this one.
getByCode ( $Code ) : object Get data for a single category selected by Url Code. Disregards permissions.
getByPermission ( string $Permission = 'Discussions.Add', null $CategoryID = null, array $Filter = [], array $PermFilter = [] ) : array
getChildTree ( integer | string $id, array $options = [] ) : array Get a category tree based on, but not including a parent category.
getChildren ( integer $categoryID ) Get the child categories of a category.
getDescendantCountByCode ( $Code ) Return the number of descendants for a specific category.
getDescendantsByCode ( string $Code ) : object
getDisplayAsOptions ( ) : array
getFiltered ( array $RestrictIDs = false, string $Permissions = false, array $ExcludeWhere = false ) : Gdn_DataSet Get a list of categories, considering several filters
getFull ( $CategoryID = false, $Permissions = false )
getFullByUrlCode ( string $UrlCode ) : object Get full data for a single category by its URL slug. Respects permissions.
getID ( integer $categoryID, string $datasetType = DATASET_TYPE_OBJECT, array $options = [] ) : object | array Get data for a single category selected by ID. Disregards permissions.
getMaxDisplayDepth ( ) : integer Get the maximum display depth for categories.
getNavDepth ( ) : integer Get the category nav depth.
getRolePermissions ( integer $categoryID ) : array Get the role specific permissions for a category.
getRootDisplayAs ( ) : string Get the display type for the root category.
getSubtree ( string $parentCategory, boolean $includeParent = true ) : array Get the subtree starting at a given parent.
getTreeAsFlat ( integer | string $id, integer | null $offset = null, integer | null $limit = null, string | null $filter = null, string $orderFields = 'Name', string $orderDirection = 'asc' ) : array
getWhereCache ( array $Where ) : array A simplified version of GetWhere that polls the cache instead of the database.
givePoints ( integer $UserID, integer $Points, string $Source = 'Other', integer $CategoryID, integer $Timestamp = false ) Give a user points specific to this category.
hasChildren ( string $CategoryID ) : boolean Check whether category has any children categories.
instance ( ) : CategoryModel The shared instance of this object.
joinCategories ( &$Data, string $Column = 'CategoryID', array $Options = [] )
joinModerators ( array $Data, string $Permission = 'Vanilla.Comments.Edit', string $Column = 'Moderators' )
joinRecent ( &$categoryTree ) Join recent posts and users to a category tree.
joinRecentChildPosts ( null &$Category = null, null &$Categories = null )
joinRecentPosts ( &$Data, null $CategoryID = null ) : boolean
joinUserCategory ( ) : boolean Whether or not to join information from GDN_UserCategory in {@link CategoryModel::calculateUser()}.
joinUserData ( &$Categories, boolean $AddUserCategory = true ) Add UserCategory modifiers
makeTree ( $Categories, null $Root = null ) : array
permissionCategory ( mixed $Category ) Return the category that contains the permissions for the given category.
rebuildTree ( boolean $BySort = false ) Rebuilds the category tree. We are using the Nested Set tree model.
recalculateTree ( ) Recalculate the dynamic tree columns in the category.
save ( $FormPostValues, array | false $Settings = false ) : integer Saves the category.
saveSubtree ( array $subtree, $parentID ) Save a subtree.
saveTree ( array $TreeArray ) Saves the category tree based on a provided tree array. We are using the Nested Set tree model.
saveUserTree ( integer $CategoryID, mixed $Set ) Grab the Category IDs of the tree.
setCache ( integer | boolean $ID = false, array | boolean $Data = false ) Grab and update the category cache
setField ( integer $ID, array | string $Property, boolean | false $Value = false ) : array | string Set a property on a category.
setJoinUserCategory ( boolean $joinUserCategory ) : CategoryModel Set whether or not to join information from GDN_UserCategory in {@link CategoryModel::calculateUser()}.
setLocalField ( $ID, $Property, $Value ) : boolean Set a property of a currently-loaded category in memory.
setRecentPost ( $CategoryID )
setStopHeadingsCalculation ( boolean $stopHeadingCalculation ) : CategoryModel Checks to see if the passed category depth is greater than the NavDepth and if so, stops calculating Headings as a DisplayAs property in the calculateDisplayAs method. Once we can be sure that all instances have their categories' DisplayAs properties explicitly set in the database (i.e., not Default) we can deprecate/remove this function.
where ( $Row, $Where ) : boolean

Protected Methods

Method Description
_MakeTreeChildren ( $Category, $Categories, null $DepthAdj = null ) : array
_SetTree ( array &$Node, integer $Left = 1, integer $Depth )
_treeSort ( $A, $B ) : integer Utility method for sorting via usort.
buildCache ( integer $CategoryID = null ) Build and augment the category cache.
rebuildLock ( boolean $release = false ) : boolean Request rebuild mutex.

Private Methods

Method Description
calculate ( &$category ) Calculate the dynamic fields of a category.
calculateData ( array &$Data ) Build calculated category data on the passed set.
calculateUser ( &$category, $addUserCategory = null ) Calculate the user-specific information on a category.
castID ( integer | string | null $category ) : integer | string | null Cast a category ID or slug to be passed to the various {@link CategoryCollection} methods.
gatherLastIDs ( array $categoryTree, &$result = null ) Gather all of the last discussion and comment IDs from the categories.
getOne ( string | integer $id ) Get a single category from the collection.
getUserCategories ( ) : array | mixed Get the per-category information for the current user.
joinRecentInternal ( &$categoryTree, array $discussions, array $comments ) This method supports {@link CategoryModel::joinRecent()}.
loadAllCategories ( ) Load all of the categories from the cache or the database.
saveSubtreeInternal ( array $subtree, integer | null $parentID = null, boolean $rebuild = true ) Save a subtree.

Method Details

_MakeTreeChildren() protected static method

protected static _MakeTreeChildren ( $Category, $Categories, null $DepthAdj = null ) : array
$Category
$Categories
$DepthAdj null
return array

_SetTree() protected method

Since: 2.0.18
protected _SetTree ( array &$Node, integer $Left = 1, integer $Depth )
$Node array
$Left integer
$Depth integer

__construct() public method

Class constructor. Defines the related database table name.
Since: 2.0.0
public __construct ( )

_treeSort() protected method

Utility method for sorting via usort.
Since: 2.0.18
protected _treeSort ( $A, $B ) : integer
$A First element to compare.
$B Second element to compare.
return integer -1, 1, 0 (per usort)

addCategoryColumns() public static method

Adds CountAllDiscussions column to each category representing the sum of discussions within this category as well as all subcategories.
Since: 2.0.17
public static addCategoryColumns ( object $Data )
$Data object SQL result.

allowedDiscussionTypes() public static method

Checks the allowed discussion types on a category.
public static allowedDiscussionTypes ( array $PermissionCategory, array $category = [] ) : array
$PermissionCategory array The permission category of the category.
$category array The category we're checking the permission on.
return array The allowed discussion types on the category.

applyUpdates() public method

If looking at the root node, make sure it exists and that the nested set columns exist in the table.
Since: 2.0.15
public applyUpdates ( )

buildCache() protected static method

Build and augment the category cache.
protected static buildCache ( integer $CategoryID = null )
$CategoryID integer The category to

calculateDisplayAs() public static method

Maintains backwards compatibilty with DisplayAs: Default-type categories by calculating the DisplayAs property into an expected DisplayAs type: Categories, Heading, or Discussions. Respects the now-deprecated config setting Vanilla.Categories.DoHeadings. Once we can be sure that all instances have their categories' DisplayAs properties explicitly set in the database (i.e., not Default) we can deprecate/remove this function.
public static calculateDisplayAs ( &$category )
$category The category to calculate the DisplayAs property for.

categories() public static method

Gets either all of the categories or a single category.
Since: 2.0.18
public static categories ( integer | string | boolean $ID = false ) : array
$ID integer | string | boolean Either the category ID or the category url code. If nothing is passed then all categories are returned.
return array Returns either one or all categories.

categoryUrl() public static method

Build URL to a category page.
public static categoryUrl ( $Category, string $Page = '', boolean | true $WithDomain = true ) : string
$Category
$Page string
$WithDomain boolean | true
return string

categoryWatch() public static method

Since: 2.0.18
public static categoryWatch ( $AllDiscussions = true ) : array
return array Category IDs.

checkPermission() public static method

Check a category's permission.
public static checkPermission ( array $category, string $permission ) : boolean
$category array The category to check.
$permission string The permission name to check.
return boolean Returns **true** if the current user has the permission or **false** otherwise.

clearCache() public static method

public static clearCache ( )

clearUserCache() public static method

public static clearUserCache ( )

counts() public method

public counts ( $Column ) : array
$Column
return array

createCollection() public method

Create a new category collection tied to this model.
public createCollection ( Gdn_SQLDriver $sql = null, Gdn_Cache $cache = null ) : CategoryCollection
$sql Gdn_SQLDriver
$cache Gdn_Cache
return CategoryCollection Returns a new collection.

defaultCategory() public static method

public static defaultCategory ( ) : mixed
return mixed

delete() public method

public delete ( $where = [], $options = [] )

deleteAndReplace() public method

Delete a single category and assign its discussions to another.
Since: 2.0.0
public deleteAndReplace ( object $category, integer $newCategoryID )
$category object
$newCategoryID integer Unique ID of category all discussion are being move to.

deleteID() public method

Delete a category.
public deleteID ( integer $categoryID, array $options = [] ) : boolean
$categoryID integer The ID of the category to delete.
$options array An array of options to affect the behavior of the delete. - **newCategoryID**: The new category to point discussions to.
return boolean Returns **true** on success or **false** otherwise.

filterCategoryPermissions() public static method

Remove categories that a user does not have permission to view.
public static filterCategoryPermissions ( array $categoryIDs ) : array
$categoryIDs array An array of categories to filter.
return array Returns an array of category IDs that are okay to view.

filterChildren() public static method

Recursively remove children from categories configured to display as "Categories" or "Flat".
public static filterChildren ( array &$categories, string $childField = 'Children' )
$categories array
$childField string

filterFollowing() public method

Filter a category tree to only the followed categories.
public filterFollowing ( array $categories ) : array
$categories array The category tree to filter.
return array Returns a category tree.

flattenTree() public static method

Return a flattened version of a tree.
public static flattenTree ( array $categories ) : array
$categories array The category tree.
return array Returns the flattened category tree.

get() public method

Get list of categories (respecting user permission).
Since: 2.0.0
public get ( string $OrderFields = '', string $OrderDirection = 'asc', integer $Limit = false, integer $Offset = false ) : Gdn_DataSet
$OrderFields string Ignored.
$OrderDirection string Ignored.
$Limit integer Ignored.
$Offset integer Ignored.
return Gdn_DataSet SQL results.

getAll() public method

Get list of categories (disregarding user permission for admins).
Since: 2.0.0
public getAll ( ) : object
return object SQL results.

getAncestors() public static method

Get all of the ancestor categories above this one.
public static getAncestors ( $categoryID, boolean $checkPermissions = true, boolean $includeHeadings = false ) : array
$checkPermissions boolean Whether or not to only return the categories with view permission.
$includeHeadings boolean Whether or not to include heading categories.
return array

getByCode() public method

Get data for a single category selected by Url Code. Disregards permissions.
Since: 2.0.0
public getByCode ( $Code ) : object
return object SQL results.

getByPermission() public static method

public static getByPermission ( string $Permission = 'Discussions.Add', null $CategoryID = null, array $Filter = [], array $PermFilter = [] ) : array
$Permission string
$CategoryID null
$Filter array
$PermFilter array
return array

getChildTree() public method

Get a category tree based on, but not including a parent category.
public getChildTree ( integer | string $id, array $options = [] ) : array
$id integer | string The parent category ID or slug.
$options array See {@link CategoryCollection::getTree()}.
return array Returns an array of categories with child categories in the **Children** key.

getChildren() public static method

Get the child categories of a category.
public static getChildren ( integer $categoryID )
$categoryID integer The category to get the children of.

getDescendantCountByCode() public method

Return the number of descendants for a specific category.
public getDescendantCountByCode ( $Code )

getDescendantsByCode() public method

Since: 2.0.18
public getDescendantsByCode ( string $Code ) : object
$Code string Where condition.
return object DataSet

getDisplayAsOptions() public static method

public static getDisplayAsOptions ( ) : array
return array

getFiltered() public method

Get a list of categories, considering several filters
public getFiltered ( array $RestrictIDs = false, string $Permissions = false, array $ExcludeWhere = false ) : Gdn_DataSet
$RestrictIDs array Optional list of category ids to mask the dataset
$Permissions string Optional permission to require. Defaults to Vanilla.Discussions.View.
$ExcludeWhere array Exclude categories with any of these flags
return Gdn_DataSet

getFull() public method

public getFull ( $CategoryID = false, $Permissions = false )

getFullByUrlCode() public method

Get full data for a single category by its URL slug. Respects permissions.
Since: 2.0.0
public getFullByUrlCode ( string $UrlCode ) : object
$UrlCode string Unique category slug from URL.
return object SQL results.

getID() public method

Get data for a single category selected by ID. Disregards permissions.
Since: 2.0.0
public getID ( integer $categoryID, string $datasetType = DATASET_TYPE_OBJECT, array $options = [] ) : object | array
$categoryID integer The unique ID of category we're getting data for.
$datasetType string Not used.
$options array Not used.
return object | array SQL results.

getMaxDisplayDepth() public method

Get the maximum display depth for categories.
public getMaxDisplayDepth ( ) : integer
return integer Returns the display depth as an integer.

getNavDepth() public method

Get the category nav depth.
public getNavDepth ( ) : integer
return integer Returns the nav depth as an integer.

getRolePermissions() public method

Get the role specific permissions for a category.
public getRolePermissions ( integer $categoryID ) : array
$categoryID integer The ID of the category to get the permissions for.
return array Returns an array of permissions.

getRootDisplayAs() public static method

Get the display type for the root category.
public static getRootDisplayAs ( ) : string
return string

getSubtree() public static method

Get the subtree starting at a given parent.
Since: 2.0.18
public static getSubtree ( string $parentCategory, boolean $includeParent = true ) : array
$parentCategory string The ID or url code of the parent category.
$includeParent boolean Whether or not to include the parent in the result.
return array An array of categories.

getTreeAsFlat() public method

public getTreeAsFlat ( integer | string $id, integer | null $offset = null, integer | null $limit = null, string | null $filter = null, string $orderFields = 'Name', string $orderDirection = 'asc' ) : array
$id integer | string The parent category ID or slug.
$offset integer | null Offset results by given value.
$limit integer | null Total number of results should not exceed this value.
$filter string | null Restrict results to only those with names matching this value, if provided.
$orderFields string
$orderDirection string
return array

getWhereCache() public method

A simplified version of GetWhere that polls the cache instead of the database.
Since: 2.2.2
public getWhereCache ( array $Where ) : array
$Where array
return array

givePoints() public static method

Give a user points specific to this category.
public static givePoints ( integer $UserID, integer $Points, string $Source = 'Other', integer $CategoryID, integer $Timestamp = false )
$UserID integer The user to give the points to.
$Points integer The number of points to give.
$Source string The source of the points.
$CategoryID integer The category to give the points for.
$Timestamp integer The time the points were given.

hasChildren() public method

Check whether category has any children categories.
Since: 2.0.0
public hasChildren ( string $CategoryID ) : boolean
$CategoryID string Unique ID for category being checked.
return boolean

instance() public static method

The shared instance of this object.
public static instance ( ) : CategoryModel
return CategoryModel Returns the instance.

joinCategories() public static method

Since: 2.0.18
public static joinCategories ( &$Data, string $Column = 'CategoryID', array $Options = [] )
$Column string Name of database column.
$Options array The 'Join' key may contain array of columns to join on.

joinModerators() public static method

Since: 2.0.0
public static joinModerators ( array $Data, string $Permission = 'Vanilla.Comments.Edit', string $Column = 'Moderators' )
$Data array
$Permission string
$Column string

joinRecent() public method

Join recent posts and users to a category tree.
public joinRecent ( &$categoryTree )

joinRecentChildPosts() public static method

public static joinRecentChildPosts ( null &$Category = null, null &$Categories = null )
$Category null
$Categories null

joinRecentPosts() public static method

public static joinRecentPosts ( &$Data, null $CategoryID = null ) : boolean
$Data
$CategoryID null
return boolean

joinUserCategory() public method

You only need the information from this table when looking at categories in a list. Controllers should set this flag if they are going to be sending read/unread information with the category.
public joinUserCategory ( ) : boolean
return boolean Returns the joinUserCategory.

joinUserData() public static method

Update &$Categories in memory by applying modifiers from UserCategory for the currently logged-in user.
Since: 2.0.18
public static joinUserData ( &$Categories, boolean $AddUserCategory = true )
$AddUserCategory boolean

makeTree() public static method

public static makeTree ( $Categories, null $Root = null ) : array
$Categories
$Root null
return array

permissionCategory() public static method

Return the category that contains the permissions for the given category.
Since: 2.2
public static permissionCategory ( mixed $Category )
$Category mixed

rebuildLock() protected static method

Allows competing instances to "vote" on the process that gets to rebuild the category cache.
protected static rebuildLock ( boolean $release = false ) : boolean
$release boolean
return boolean whether we may rebuild

rebuildTree() public method

Rebuilds the category tree. We are using the Nested Set tree model.
Since: 2.0.0
public rebuildTree ( boolean $BySort = false )
$BySort boolean Rebuild the tree by sort order instead of existing tree order.

recalculateTree() public method

Recalculate the dynamic tree columns in the category.
public recalculateTree ( )

save() public method

Saves the category.
Since: 2.0.0
public save ( $FormPostValues, array | false $Settings = false ) : integer
$Settings array | false Additional settings to affect saving.
return integer ID of the saved category.

saveSubtree() public method

Save a subtree.
public saveSubtree ( array $subtree, $parentID )
$subtree array A nested array where each array contains a CategoryID and optional Children element.

saveTree() public method

TreeArray comes in the format: '0' ... 'item_id' => "root" 'parent_id' => "none" 'depth' => "0" 'left' => "1" 'right' => "34" '1' ... 'item_id' => "1" 'parent_id' => "root" 'depth' => "1" 'left' => "2" 'right' => "3" etc...
Since: 2.0.16
public saveTree ( array $TreeArray )
$TreeArray array A fully defined nested set model of the category tree.

saveUserTree() public method

Grab the Category IDs of the tree.
Since: 2.0.18
public saveUserTree ( integer $CategoryID, mixed $Set )
$CategoryID integer
$Set mixed

setCache() public static method

Grab and update the category cache
Since: 2.0.18
public static setCache ( integer | boolean $ID = false, array | boolean $Data = false )
$ID integer | boolean
$Data array | boolean

setField() public method

Set a property on a category.
public setField ( integer $ID, array | string $Property, boolean | false $Value = false ) : array | string
$ID integer
$Property array | string
$Value boolean | false
return array | string

setJoinUserCategory() public method

Set whether or not to join information from GDN_UserCategory in {@link CategoryModel::calculateUser()}.
public setJoinUserCategory ( boolean $joinUserCategory ) : CategoryModel
$joinUserCategory boolean The new value to set.
return CategoryModel Returns `$this` for fluent calls.

setLocalField() public static method

Set a property of a currently-loaded category in memory.
public static setLocalField ( $ID, $Property, $Value ) : boolean
$ID
$Property
$Value
return boolean

setRecentPost() public method

public setRecentPost ( $CategoryID )
$CategoryID

setStopHeadingsCalculation() public method

Checks to see if the passed category depth is greater than the NavDepth and if so, stops calculating Headings as a DisplayAs property in the calculateDisplayAs method. Once we can be sure that all instances have their categories' DisplayAs properties explicitly set in the database (i.e., not Default) we can deprecate/remove this function.
public setStopHeadingsCalculation ( boolean $stopHeadingCalculation ) : CategoryModel
$stopHeadingCalculation boolean
return CategoryModel

where() public static method

public static where ( $Row, $Where ) : boolean
$Row
$Where
return boolean

Property Details

$Categories public_oe static_oe property

Merged Category data, including Pure + UserCategory.
public static $Categories

$JoinRecentUsers public_oe property

Whether or not to join users to recent posts. Forums with a lot of categories may need to optimize using this setting and simpler views.
public $JoinRecentUsers

$ShardCache public_oe static_oe property

Whether or not to explicitly shard the categories cache.
public static $ShardCache

$Watching public_oe property

public bool $Watching
return boolean