Perforce Chronicle 2012.2/486814
API Documentation
Public Member Functions | Static Public Member Functions | Public Attributes | Static Protected Attributes

Comment_Model_Comment Class Reference

Modelling and storage of comment entries. More...

Inheritance diagram for Comment_Model_Comment:
P4Cms_Record P4Cms_Record_Connected P4Cms_Model P4Cms_ModelInterface

List of all members.

Public Member Functions

 getPostTime ()
 Get the recorded time this comment was posted.
 getVotes ()
 Get the votes counted for this comment.
 setPostTime ($time)
 Explicitly set the time that this comment was posted.
 setStatus ($status)
 Set the status of this comment.
 setVotes ($votes)
 Explicitly set the number of votes for this comment.
 voteDown ()
 Adjust the number of votes on this comment down by one.
 voteUp ()
 Adjust the number of votes on this comment up by one.

Static Public Member Functions

static fetchAll ($query=null, P4Cms_Record_Adapter $adapter=null)
 Extend parent to join against users and expand user name into full name and email where appropriate.
static fetchVotedComments ($user, $path, P4Cms_Record_Adapter $adapter=null)
 Get all comments voted on by the given user under the given path.

Public Attributes

const STATUS_APPROVED = 'approved'
const STATUS_PENDING = 'pending'
const STATUS_REJECTED = 'rejected'

Static Protected Attributes

static $_fields
 Specifies the array of fields that the current Record class wishes to use.
static $_idField = 'id'
 All records should have an id field.
static $_storageSubPath = 'comments'
 Specifies the sub-path to use for storage of records.

Detailed Description

Modelling and storage of comment entries.

Comments are grouped by path. Each comment entry id should (typically) be stored in a sub-folder under comments (e.g. comments/content/123) where '123' is the id of the content entry the comment is associated with.

We permit numeric ids when adding because we want to include numeric content (or other) record ids as path components of the comment id.

Copyright:
2011-2012 Perforce Software. All rights reserved
License:
Please see LICENSE.txt in top-level folder of this distribution.
Version:
2012.2/486814

Member Function Documentation

static Comment_Model_Comment::fetchAll ( $  query = null,
P4Cms_Record_Adapter $  adapter = null 
) [static]

Extend parent to join against users and expand user name into full name and email where appropriate.

Parameters:
P4Cms_Record_Query | array | null$queryoptional - query options to augment result.
P4Cms_Record_Adapter$adapteroptional - storage adapter to use.
Returns:
P4Cms_Model_Iterator all records of this type.

Reimplemented from P4Cms_Record.

    {
        // if no adapter given, use default.
        $adapter  = $adapter ?: static::getDefaultAdapter();

        // let parent do initial fetch.
        $comments = parent::fetchAll($query, $adapter);

        // fill in full-name and email of users if we have any comments.
        // we do this because comments from authenticated users are
        // stored without the full-name/email, just the username.
        if (count($comments)) {
            $p4     = $adapter->getConnection();
            $result = $p4->run('users', $comments->invoke('getValue', array('user')));
            $lookup = array();
            foreach ($result->getData() as $user) {
                $lookup[$user['User']] = array(
                    'name'  => $user['FullName'],
                    'email' => $user['Email']
                );
            }
            foreach ($comments as $comment) {
                if (isset($comment->user) && isset($lookup[$comment->user])) {
                    $comment->setValues($lookup[$comment->user]);
                }
            }
        }

        return $comments;
    }
static Comment_Model_Comment::fetchVotedComments ( $  user,
$  path,
P4Cms_Record_Adapter $  adapter = null 
) [static]

Get all comments voted on by the given user under the given path.

Any change that contains the word 'vote' in the description is considered to be a vote. This is a rather fragile linkage. If the change description for comment votes is altered, this will stop working.

Optimized to only lookup the comment ids. If you wish to read other fields, you will incur a populate per comment.

Parameters:
string$userthe id of the user to fetch voted comments for.
string$paththe path under which to fetch comments.
P4Cms_Record_Adapter$adapteroptional - storage adapter to use.
Returns:
P4Cms_Model_Iterator all comments voted on by the given user under the given path. 
    {
        // if no adapter given, use default.
        $adapter = $adapter ?: static::getDefaultAdapter();

        // ensure path has no trailing slash.
        $path = rtrim($path, '/');

        // fetch all changes made by the given user against this path.
        $changes = P4_Change::fetchAll(
            array(
                P4_Change::FETCH_BY_USER     => $user,
                P4_Change::FETCH_BY_FILESPEC => static::getStoragePath() . '/' . $path . '/...'
            ),
            $adapter->getConnection()
        );

        // further limit changes to those with the word 'vote' in the description.
        $changes->filter(
            'Description',
            'Vote',
            array(
                P4_Model_Iterator::FILTER_NO_CASE,
                P4_Model_Iterator::FILTER_CONTAINS
            )
        );

        // if no changes, nothing more to query.
        if (!$changes->count()) {
            return new P4Cms_Model_Iterator;
        }

        // fetch comments affected by these changes.
        $ids      = array_map('strval', $changes->invoke('getId'));
        $filter   = new P4Cms_Record_Filter;
        $filter->addFstat('headChange', $ids);
        $comments = Comment_Model_Comment::fetchAll(
            array(
                'filter'      => $filter,
                'paths'       => array($path . '/...'),
                'limitFields' => 'depotFile'
            ),
            $adapter
        );

        return $comments;
    }
Comment_Model_Comment::getPostTime ( )

Get the recorded time this comment was posted.

Returns:
int the time this comment was allegedly posted. 
    {
        return intval($this->_getValue('postTime'));
    }
Comment_Model_Comment::getVotes ( )

Get the votes counted for this comment.

Returns:
int the number of votes for this comment. 
    {
        return intval($this->_getValue('votes'));
    }
Comment_Model_Comment::setPostTime ( $  time)

Explicitly set the time that this comment was posted.

Parameters:
int$timethe time this comment was posted
Returns:
Comment_Model_Comment provides fluent interface. 
    {
        return $this->_setValue('postTime', $time);
    }
Comment_Model_Comment::setStatus ( $  status)

Set the status of this comment.

Parameters:
string$statusthe state to set this comment to.
Returns:
Comment_Model_Comment provides fluent interface.
Exceptions:
InvalidArgumentExceptionif given status is not a valid state. 
    {
        $states = array(
            static::STATUS_APPROVED,
            static::STATUS_PENDING,
            static::STATUS_REJECTED
        );

        if (!in_array($status, $states, true)) {
            throw new InvalidArgumentException(
                "Cannot set status of comment. Given status is not a valid state."
            );
        }

        return $this->_setValue('status', $status);
    }
Comment_Model_Comment::setVotes ( $  votes)

Explicitly set the number of votes for this comment.

Parameters:
int$votesthe number of votes this comment should have.
Returns:
Comment_Model_Comment provides fluent interface. 
    {
        return $this->_setValue('votes', $votes);
    }
Comment_Model_Comment::voteDown ( )

Adjust the number of votes on this comment down by one.

Returns:
Comment_Model_Comment provides fluent interface. 
    {
        return $this->setVotes($this->getVotes() - 1);
    }
Comment_Model_Comment::voteUp ( )

Adjust the number of votes on this comment up by one.

Returns:
Comment_Model_Comment provides fluent interface. 
    {
        return $this->setVotes($this->getVotes() + 1);
    }

Member Data Documentation

Comment_Model_Comment::$_fields [static, protected]
Initial value:
 array(
        'id',
        'user',
        'name',
        'comment',
        'postTime'  => array(
            'accessor'  => 'getPostTime',
            'mutator'   => 'setPostTime'
        ),
        'votes'     => array(
            'accessor'  => 'getVotes',
            'mutator'   => 'setVotes'
        ),
        'status'    => array(
            'mutator'   => 'setStatus'
        )
    )

Specifies the array of fields that the current Record class wishes to use.

The implementing class MUST set this property.

Reimplemented from P4Cms_Record.

Comment_Model_Comment::$_idField = 'id' [static, protected]

All records should have an id field.

Reimplemented from P4Cms_Record.

Comment_Model_Comment::$_storageSubPath = 'comments' [static, protected]

Specifies the sub-path to use for storage of records.

This is used in combination with the records path (provided by the storage adapter) to construct the full storage path. The implementing class MUST set this property.

Reimplemented from P4Cms_Record.

const Comment_Model_Comment::STATUS_APPROVED = 'approved'
const Comment_Model_Comment::STATUS_PENDING = 'pending'
const Comment_Model_Comment::STATUS_REJECTED = 'rejected'
The documentation for this class was generated from the following file: