Nextcloud PHP API (stable19)

ICommentsManager

Interface ICommentsManager

This class manages the access to comments

Tags
since
9.0.0

Table of Contents

DELETED_USER  = 'deleted_users'
create()  : IComment
creates a new comment and returns it. At this point of time, it is not saved in the used data storage. Use save() after setting other fields of the comment (e.g. message or verb).
delete()  : bool
permanently deletes the comment specified by the ID
deleteCommentsAtObject()  : bool
deletes all comments made of a specific object (e.g. on file delete)
deleteReadMarksFromUser()  : bool
deletes the read markers for the specified user
deleteReadMarksOnObject()  : bool
deletes the read markers on the specified object
deleteReferencesOfActor()  : bool
removes references to specific actor (e.g. on user delete) of a comment.
get()  : IComment
returns a comment instance
getForObject()  : \OCP\Comments\IComment[]
returns comments for a specific object (e.g. a file).
getForObjectSince()  : \OCP\Comments\IComment[]
getNumberOfCommentsForObject()  : int
getNumberOfUnreadCommentsForFolder()  : array
Get the number of unread comments for all files in a folder
getReadMark()  : DateTime|null
returns the read marker for a given file to the specified date for the provided user. It returns null, when the marker is not present, i.e.
getTree()  : array
returns the comment specified by the id and all it's child comments
registerDisplayNameResolver()  : mixed
registers a method that resolves an ID to a display name for a given type
registerEventHandler()  : mixed
registers an Entity to the manager, so event notifications can be send to consumers of the comments infrastructure
resolveDisplayName()  : string
resolves a given ID of a given Type to a display name.
save()  : bool
saves the comment permanently
search()  : \OCP\Comments\IComment[]
Search for comments with a given content
setReadMark()  : mixed
sets the read marker for a given file to the specified date for the provided user

Constants

DELETED_USER

public mixed DELETED_USER = 'deleted_users'
Tags
const

DELETED_USER type and id for a user that has been deleted

see
deleteReferencesOfActor
since
9.0.0

To be used as replacement for user type actors in deleteReferencesOfActor().

User interfaces shall show "Deleted user" as display name, if needed.

Methods

create()

creates a new comment and returns it. At this point of time, it is not saved in the used data storage. Use save() after setting other fields of the comment (e.g. message or verb).

public create(string $actorType, string $actorId, string $objectType, string $objectId) : IComment
Parameters
$actorType : string

the actor type (e.g. 'users')

$actorId : string

a user id

$objectType : string

the object type the comment is attached to

$objectId : string

the object id the comment is attached to

Tags
since
9.0.0
Return values
IComment —

delete()

permanently deletes the comment specified by the ID

public delete(string $id) : bool

When the comment has child comments, their parent ID will be changed to the parent ID of the item that is to be deleted.

Parameters
$id : string
Tags
since
9.0.0
Return values
bool —

deleteCommentsAtObject()

deletes all comments made of a specific object (e.g. on file delete)

public deleteCommentsAtObject(string $objectType, string $objectId) : bool
Parameters
$objectType : string

the object type (e.g. 'files')

$objectId : string

e.g. the file id

Tags
since
9.0.0
Return values
bool —

deleteReadMarksFromUser()

deletes the read markers for the specified user

public deleteReadMarksFromUser(IUser $user) : bool
Parameters
$user : IUser
Tags
since
9.0.0
Return values
bool —

deleteReadMarksOnObject()

deletes the read markers on the specified object

public deleteReadMarksOnObject(string $objectType, string $objectId) : bool
Parameters
$objectType : string
$objectId : string
Tags
since
9.0.0
Return values
bool —

deleteReferencesOfActor()

removes references to specific actor (e.g. on user delete) of a comment.

public deleteReferencesOfActor(string $actorType, string $actorId) : bool

The comment itself must not get lost/deleted.

A 'users' type actor (type and id) should get replaced by the value of the DELETED_USER constant of this interface.

Parameters
$actorType : string

the actor type (e.g. 'users')

$actorId : string

a user id

Tags
since
9.0.0
Return values
bool —

getForObject()

returns comments for a specific object (e.g. a file).

public getForObject(string $objectType, string $objectId, int $limit, int $offset[, DateTime|null $notOlderThan = null ]) : \OCP\Comments\IComment[]

The sort order is always newest to oldest.

Parameters
$objectType : string

the object type, e.g. 'files'

$objectId : string

the id of the object

$limit : int

optional, number of maximum comments to be returned. if not specified, all comments are returned.

$offset : int

optional, starting point

$notOlderThan : DateTime|null = null

optional, timestamp of the oldest comments that may be returned

Tags
since
9.0.0
Return values
\OCP\Comments\IComment[] —

getForObjectSince()

public getForObjectSince(string $objectType, string $objectId, int $lastKnownCommentId[, string $sortDirection = 'asc' ][, int $limit = 30 ]) : \OCP\Comments\IComment[]
Parameters
$objectType : string

the object type, e.g. 'files'

$objectId : string

the id of the object

$lastKnownCommentId : int

the last known comment (will be used as offset)

$sortDirection : string = 'asc'

direction of the comments (asc or desc)

$limit : int = 30

optional, number of maximum comments to be returned. if set to 0, all comments are returned.

Tags
since
14.0.0
Return values
\OCP\Comments\IComment[] —

getNumberOfCommentsForObject()

public getNumberOfCommentsForObject( $objectType,  $objectId[, DateTime|null $notOlderThan = null ][, string $verb = '' ]) : int
Parameters
$objectType :

the object type, e.g. 'files'

$objectId :

the id of the object

$notOlderThan : DateTime|null = null

optional, timestamp of the oldest comments that may be returned

$verb : string = ''

Limit the verb of the comment - Added in 14.0.0

Tags
since
9.0.0
Return values
int —

getNumberOfUnreadCommentsForFolder()

Get the number of unread comments for all files in a folder

public getNumberOfUnreadCommentsForFolder(int $folderId, IUser $user) : array
Parameters
$folderId : int
$user : IUser
Tags
since
12.0.0
Return values
array —

[$fileId => $unreadCount]

getReadMark()

returns the read marker for a given file to the specified date for the provided user. It returns null, when the marker is not present, i.e.

public getReadMark(string $objectType, string $objectId, IUser $user) : DateTime|null

no comments were marked as read.

Parameters
$objectType : string
$objectId : string
$user : IUser
Tags
since
9.0.0
Return values
DateTime|null —

getTree()

returns the comment specified by the id and all it's child comments

public getTree(string $id, int $limit, int $offset) : array
Parameters
$id : string
$limit : int

max number of entries to return, 0 returns all

$offset : int

the start entry

Tags
since
9.0.0

The return array looks like this [ 'comment' => IComment, // root comment 'replies' => [ 0 => [ 'comment' => IComment, 'replies' => [ 0 => [ 'comment' => IComment, 'replies' => [ … ] ], … ] ] 1 => [ 'comment' => IComment, 'replies'=> [ … ] ], … ] ]

Return values
array —

registerDisplayNameResolver()

registers a method that resolves an ID to a display name for a given type

public registerDisplayNameResolver(string $type, Closure $closure) : mixed
Parameters
$type : string
$closure : Closure
Tags
throws
OutOfBoundsException
since
11.0.0

Only one resolver shall be registered per type. Otherwise a \OutOfBoundsException has to thrown.

Return values
mixed —

registerEventHandler()

registers an Entity to the manager, so event notifications can be send to consumers of the comments infrastructure

public registerEventHandler(Closure $closure) : mixed
Parameters
$closure : Closure
Tags
since
11.0.0
Return values
mixed —

resolveDisplayName()

resolves a given ID of a given Type to a display name.

public resolveDisplayName(string $type, string $id) : string
Parameters
$type : string
$id : string
Tags
throws
OutOfBoundsException
since
11.0.0

If a provided type was not registered, an \OutOfBoundsException shall be thrown. It is upon the resolver discretion what to return of the provided ID is unknown. It must be ensured that a string is returned.

Return values
string —

save()

saves the comment permanently

public save(IComment $comment) : bool

if the supplied comment has an empty ID, a new entry comment will be saved and the instance updated with the new ID.

Otherwise, an existing comment will be updated.

Throws NotFoundException when a comment that is to be updated does not exist anymore at this point of time.

Parameters
$comment : IComment
Tags
throws
NotFoundException
since
9.0.0
Return values
bool —

search()

Search for comments with a given content

public search(string $search, string $objectType, string $objectId, string $verb, int $offset[, int $limit = 50 ]) : \OCP\Comments\IComment[]
Parameters
$search : string

content to search for

$objectType : string

Limit the search by object type

$objectId : string

Limit the search by object id

$verb : string

Limit the verb of the comment

$offset : int
$limit : int = 50
Tags
since
14.0.0
Return values
\OCP\Comments\IComment[] —

setReadMark()

sets the read marker for a given file to the specified date for the provided user

public setReadMark(string $objectType, string $objectId, DateTime $dateTime, IUser $user) : mixed
Parameters
$objectType : string
$objectId : string
$dateTime : DateTime
$user : IUser
Tags
since
9.0.0
Return values
mixed —

Search results