Rating of objects. More...

Public Member Functions
	buildBrowserKey ($userId=null, $browserKey=null)
	getUserRating ($objectGenre, $objectId, $ratingGroup=null, $userId=null, $browserKey=null)
	Returns user`s rating for selected object.
	getUserRatings ($objectGenre, $objectIds, $ratingGroup=null, $userId=null, $browserKey=null, $where=null, $order=null, $limit=null, $keyColumn=false, $totalCount=null)
	Returns user`s ratings for selected objects.
	setUserRating ($rating, $objectGenre, $objectId, $ratingGroup=null, $userId=null, $browserKey=null, $ip=null)
	Sets or updates user's rating.
	getObjectRating ($objectGenre, $objectId, $ratingGroup=null)
	Returns rating for specified object genre/id/group.
	getObjectRatings ($objectGenre, $objectIds, $ratingGroup=true, $where=null, $order=null, $limit=null, $keyColumn=false, &$totalCount=null)
	Returns ratings for specified objects, genres, ids, groups or users.
	removeRatingsForGroup ($ratingGroup)
	Removes ratings for specified group.
	removeRatingsForObject ($objectGenre, $objectId=null, $ratingGroup=null)
	Enter description here ...
	removeRatingsByUser ($userId, $browserKey)
	Removes ratings by specified user.
	calculateRank ($rankId, array $options=array())
	Calculates ranking.
	getRank ($rankId, $db=null)
	runCron ()
Static Public Member Functions
static	instance ($id=self::ID_MAIN, $create=true)
static	getRatingIdsFromRank ($rank)
static	getObjectIdsFromRank ($rank)
static	onObjectRemoveCommit (KWebEvent $event)
Data Fields
const	ID_MAIN = 'main'
const	GROUP_MAIN = ''
	$defaultGroup
	Default rating_group.
	$ipLimit
	$allowChange
	$allowMultiple = false
	Allows for multiple ratings by the same user_id as long as browser_key is different.
	$browserKeySuffix = ''
	Suffix appended to default browser keys.
	$allowAnonymous = true
	$rankOptions = array()
	Default options for building rankings for this rating object as [rankId] => array()
const	FIELD_RATING = 'rating'
const	FIELD_RATING_SUM = 'rating_sum'
const	FIELD_RATING_COUNT = 'rating_count'
const	FIELD_OBJECT_GENRE = 'object_genre'
const	FIELD_OBJECT_ID = 'object_id'
const	FIELD_RATING_ID = 'rating_id'
const	FIELD_RATING_TIME = 'rating_time'
const	RANK_RATING_ID = 'rating_id'
const	RANK_GROUP = 'group'
const	RANK_FROM_TIME = 'from'
	Time in seconds.
const	RANK_TO_TIME = 'to'
	Time in seconds.
const	RANK_ALLOW = 'allow'
	Allowed genres/types.
const	RANK_MIN_RATING_COUNT = 'count'
const	RANK_LIMIT = 'limit'
const	RANK_DB = 'db'
const	RANK_JOIN = 'join'
const	RANK_WHERE = 'where'
const	RANK_TITLE = 'title'
const	RANK_EXPRESSION = 'expression'
	Column or expression to use as a ranking calculation.
const	RANK_EXAEQUO = 'exaequo'
	Use ex aequo positioning of ratings (default TRUE)
const	RANK_MAX_POSITION = 'max_position'
	Max position in rank.
const	LIMIT_COUNT = "count"
	$minRatingCountDefault = 3
	$limitDefault = 10
	$maxPositionDefault = 100
Static Public Attributes
static	$inst = null
static	$instances = array()
Protected Member Functions
	__construct ($id=false)
Static Protected Member Functions
static	getTime ($time)

Detailed Description

Rating of objects.

Ratings are identified with currently logged in user id, or browser key of anonymous session. Every rating is stored in the database (k_rating_log) with a key of rating_id, user_id, browser_key

Alternatively browser_key can be used to store many different ratings made by the same person. For this to work, you have to set $allowMultiple to true and override buildBrowserKey, or provide unique browserKey to functions accepting it.

If multiple ratings are time based, the best way to build the browser key is to use time string based on the time period. Multiple ratings should only be used with ratings for logged in users.

Author:: Rafał Lindemann, STAMINA

Constructor & Destructor Documentation

KWebRating::__construct ( $ id = false ) [protected]

Member Function Documentation

KWebRating::buildBrowserKey	(	$	userId = `null`,
		$	browserKey = `null`
	)

KWebRating::calculateRank	(	$	rankId,
		array $	options = `array()`
	)

Calculates ranking.

Parameters:

$rankId	string Ranking id
$options	array Options

Returns:: boolean

static KWebRating::getObjectIdsFromRank ( $ rank ) [static]

KWebRating::getObjectRating	(	$	objectGenre,
		$	objectId,
		$	ratingGroup = `null`
	)

Returns rating for specified object genre/id/group.

Parameters:

unknown_type	$objectGenre
unknown_type	$objectId
	$ratingGroup	- rating group or false\|null\|""

Returns:: KWebRating_Entry

KWebRating::getObjectRatings	(	$	objectGenre,
		$	objectIds,
		$	ratingGroup = `true`,
		$	where = `null`,
		$	order = `null`,
		$	limit = `null`,
		$	keyColumn = `false`,
		&$	totalCount = `null`
	)

Returns ratings for specified objects, genres, ids, groups or users.

Parameters:

unknown_type	$objectGenre	value, array or null
unknown_type	$objectId	value, array or null
	$ratingGroup	- value, array or null. Pass true for default group
	$where	- SQL additional where
	$order	- SQL order - defaults to FIELD_RATING . ' desc'
	$limit	- SQL limit - ie '0,10'
	$keyColumn	- if false returned data will be flat, otherwise this column will be used as key => rows
	$totalCount	- value to assign total count (or null)

Returns:: table with FIELD_RATING etc...

KWebRating::getRank	(	$	rankId,
		$	db = `null`
	)

static KWebRating::getRatingIdsFromRank ( $ rank ) [static]

static KWebRating::getTime ( $ time ) [static, protected]

KWebRating::getUserRating	(	$	objectGenre,
		$	objectId,
		$	ratingGroup = `null`,
		$	userId = `null`,
		$	browserKey = `null`
	)

Returns user`s rating for selected object.

Parameters:

$objectGenre
$objectId
$ratingGroup	- rating group or false\|null\|""
$userId	- null for current user, false/0 to ommit this parameter
$browserKey	- computer's id and/or rating unique key - null for session`s key, false to ommit this parameter

Returns:: KWebRating_Entry

KWebRating::getUserRatings	(	$	objectGenre,
		$	objectIds,
		$	ratingGroup = `null`,
		$	userId = `null`,
		$	browserKey = `null`,
		$	where = `null`,
		$	order = `null`,
		$	limit = `null`,
		$	keyColumn = `false`,
		$	totalCount = `null`
	)

Returns user`s ratings for selected objects.

Parameters:

$objectGenre	- specific genre or FALSE if ids are uids
$objectIds	- ids or uids
$ratingGroup	- rating group, null or true for default group or false for all groups
$userId	- null for current user, 0 or -1 for anonymous, FALSE to ommit this parameter
$browserKey	- computer's id and/or rating unique key - null for session`s key, false to ommit this parameter

Returns:: table with KWebRating_Entry

static KWebRating::instance	(	$	id = `self::ID_MAIN`,
		$	create = `true`
	)		`[static]`

Returns:: KWebRating

static KWebRating::onObjectRemoveCommit ( KWebEvent $ event ) [static]

KWebRating::removeRatingsByUser	(	$	userId,
		$	browserKey
	)

Removes ratings by specified user.

Parameters:

$userId
$browserKey	If userId is 0 and browserKey is FALSE then ALL anonymous votes will be removed!

Returns:: Number of removed items

KWebRating::removeRatingsForGroup ( $ ratingGroup )

Removes ratings for specified group.

Parameters:

$ratingGroup - rating group or false|null|""

Returns:: Number of removed items

KWebRating::removeRatingsForObject	(	$	objectGenre,
		$	objectId = `null`,
		$	ratingGroup = `null`
	)

Enter description here ...

Parameters:

$objectGenre
$objectId	- object id or NULL to remove ALL genre's ratings
$ratingGroup	- rating group or false\|null\|""

Returns:: Number of removed items

KWebRating::runCron ( )

KWebRating::setUserRating	(	$	rating,
		$	objectGenre,
		$	objectId,
		$	ratingGroup = `null`,
		$	userId = `null`,
		$	browserKey = `null`,
		$	ip = `null`
	)

Sets or updates user's rating.

Parameters:

$rating	Rating value (amount depends on implementation). Average rating is stored as int, so to make half ratings the rating value should be multiplied by two. To have precise control on average amount for sorting, the rating should be multiplied by 1000.
$objectGenre
$objectId
$ratingGroup	- rating group or false\|null\|""
$userId	- voting user's Id, NULL for currently logged in, or FALSE for anonymous vote
$browserKey	- voting computer's Id and/or rating unique key, NULL for current session
$ip	- voting IP, NULL for current session, or FALSE no to check or store IP

Returns:: boolean TRUE if successfull, FALSE if spam was detected, or updating of rating is prohibited

Field Documentation

KWebRating::$allowAnonymous = true

KWebRating::$allowChange

KWebRating::$allowMultiple = false

Allows for multiple ratings by the same user_id as long as browser_key is different.

KWebRating::$browserKeySuffix = ''

Suffix appended to default browser keys.

Should be used to differentiate multiple ratings by the same person For example to allow one rating every day one can use strftime('Ymd') as a suffix. For one rating every second one can use simply time()

KWebRating::$defaultGroup

Default rating_group.

Defaults to GROUP_MAIN for main KWebRating instance, or to $id of other instances

KWebRating::$inst = null [static]

KWebRating::$instances = array() [static]

KWebRating::$ipLimit

KWebRating::$limitDefault = 10

KWebRating::$maxPositionDefault = 100

KWebRating::$minRatingCountDefault = 3

KWebRating::$rankOptions = array()

Default options for building rankings for this rating object as [rankId] => array()

const KWebRating::FIELD_OBJECT_GENRE = 'object_genre'