Nextcloud PHP API (master)

ICommentsManager
in

Interface ICommentsManager

This class manages the access to comments

Tags
since
9.0.0

Table of Contents

Constants

DELETED_USER  = 'deleted_users'

Methods

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)
deleteCommentsExpiredAtObject()  : bool
Delete comments with field expire_date less than current date Only will delete the message related with the object.
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
getCommentsWithVerbForObjectSinceComment()  : array<int, IComment>
getForObject()  : array<int, IComment>
returns comments for a specific object (e.g. a file).
getForObjectSince()  : array<int, IComment>
getLastCommentBeforeDate()  : int
getLastCommentDateByActor()  : array<string|int, DateTime>
getNumberOfCommentsForObject()  : int
getNumberOfCommentsForObjectSinceComment()  : int
getNumberOfCommentsWithVerbsForObjectSinceComment()  : int
getNumberOfUnreadCommentsForFolder()  : array<string|int, mixed>
Get the number of unread comments for all files in a folder
getNumberOfUnreadCommentsForObjects()  : array<string|int, mixed>
getReactionComment()  : IComment
Get comment related with user reaction
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()  : mixed
Returns the comment specified by the id and all it's child comments
load()  : void
Load the Comments app into the page
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.
retrieveAllReactions()  : array<string|int, IComment>
Retrieve all reactions of a message
retrieveAllReactionsWithSpecificReaction()  : array<string|int, IComment>
Retrieve all reactions with specific reaction of a message
save()  : bool
saves the comment permanently
search()  : array<int, IComment>
Search for comments with a given content
searchForObjects()  : array<string|int, IComment>
Search for comments on one or more objects with a given content
setReadMark()  : mixed
sets the read marker for a given file to the specified date for the provided user
supportReactions()  : bool
Support reactions

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

deleteCommentsExpiredAtObject()

Delete comments with field expire_date less than current date Only will delete the message related with the object.

public deleteCommentsExpiredAtObject(string $objectType[, string $objectId = '' ]) : bool
Parameters
$objectType : string

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

$objectId : string = ''

e.g. the file id, leave empty to expire on all objects of this type

Tags
since
25.0.0
Return values
bool —

true if at least one row was deleted

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

getCommentsWithVerbForObjectSinceComment()

public getCommentsWithVerbForObjectSinceComment(string $objectType, string $objectId, array<string|int, string> $verbs, int $lastKnownCommentId[, string $sortDirection = 'asc' ][, int $limit = 30 ][, bool $includeLastKnown = false ]) : array<int, IComment>
Parameters
$objectType : string

the object type, e.g. 'files'

$objectId : string

the id of the object

$verbs : array<string|int, string>

List of verbs to filter by

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

$includeLastKnown : bool = false
Tags
since
24.0.0
Return values
array<int, IComment>

getForObject()

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

public getForObject(string $objectType, string $objectId[, int $limit = 0 ][, int $offset = 0 ][, DateTime|null $notOlderThan = null ]) : array<int, 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 = 0

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

$offset : int = 0

optional, starting point

$notOlderThan : DateTime|null = null

optional, timestamp of the oldest comments that may be returned

Tags
since
9.0.0
Return values
array<int, IComment>

getForObjectSince()

public getForObjectSince(string $objectType, string $objectId, int $lastKnownCommentId[, string $sortDirection = 'asc' ][, int $limit = 30 ][, bool $includeLastKnown = false ]) : array<int, IComment>
  • Use getCommentsWithVerbForObjectSinceComment instead
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.

$includeLastKnown : bool = false
Tags
since
14.0.0
Return values
array<int, IComment>

getLastCommentBeforeDate()

public getLastCommentBeforeDate(string $objectType, string $objectId, DateTime $beforeDate[, string $verb = '' ]) : int
Parameters
$objectType : string
$objectId : string
$beforeDate : DateTime
$verb : string = ''
Tags
since
21.0.0
Return values
int

getLastCommentDateByActor()

public getLastCommentDateByActor(string $objectType, string $objectId, string $verb, string $actorType, array<string|int, string> $actors) : array<string|int, DateTime>
Parameters
$objectType : string
$objectId : string
$verb : string
$actorType : string
$actors : array<string|int, string>
Tags
psalm-return

array<string, \DateTime>

since
21.0.0
Return values
array<string|int, DateTime> —

Map of "string actor" => "\DateTime most recent comment date"

getNumberOfCommentsForObject()

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

string the object type, e.g. 'files'

$objectId : mixed

string 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

getNumberOfCommentsForObjectSinceComment()

public getNumberOfCommentsForObjectSinceComment(string $objectType, string $objectId, int $lastRead[, string $verb = '' ]) : int
  • Use getNumberOfCommentsWithVerbsForObjectSinceComment instead
Parameters
$objectType : string
$objectId : string
$lastRead : int
$verb : string = ''
Tags
since
21.0.0
Return values
int

getNumberOfCommentsWithVerbsForObjectSinceComment()

public getNumberOfCommentsWithVerbsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, array<string|int, string> $verbs) : int
Parameters
$objectType : string
$objectId : string
$lastRead : int
$verbs : array<string|int, string>
Tags
since
24.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<string|int, mixed>

use getNumberOfUnreadCommentsForObjects instead

Parameters
$folderId : int
$user : IUser
Tags
since
12.0.0
Return values
array<string|int, mixed> —

[$fileId => $unreadCount]

getNumberOfUnreadCommentsForObjects()

public getNumberOfUnreadCommentsForObjects(string $objectType, array<string|int, string> $objectIds, IUser $user[, string $verb = '' ]) : array<string|int, mixed>
Parameters
$objectType : string

the object type, e.g. 'files'

$objectIds : array<string|int, string>

the id of the object

$user : IUser
$verb : string = ''

Limit the verb of the comment - Added in 14.0.0

Tags
psalm-return

array<string, int>

since
21.0.0
Return values
array<string|int, mixed> —

Map with object id => # of unread comments

getReactionComment()

Get comment related with user reaction

public getReactionComment(int $parentId, string $actorType, string $actorId, string $reaction) : IComment

Throws PreConditionNotMetException when the system haven't the minimum requirements to use reactions

Parameters
$parentId : int
$actorType : string
$actorId : string
$reaction : string
Tags
throws
NotFoundException
throws
PreConditionNotMetException
since
24.0.0
Return values
IComment

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 = 0 ][, int $offset = 0 ]) : mixed
Parameters
$id : string
$limit : int = 0

max number of entries to return, 0 returns all

$offset : int = 0

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'=> [ … ] ], … ] ]

load()

Load the Comments app into the page

public load() : void
Tags
since
21.0.0

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.

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

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

retrieveAllReactions()

Retrieve all reactions of a message

public retrieveAllReactions(int $parentId) : array<string|int, IComment>

Throws PreConditionNotMetException when the system haven't the minimum requirements to use reactions

Parameters
$parentId : int
Tags
throws
PreConditionNotMetException
since
24.0.0
Return values
array<string|int, IComment>

retrieveAllReactionsWithSpecificReaction()

Retrieve all reactions with specific reaction of a message

public retrieveAllReactionsWithSpecificReaction(int $parentId, string $reaction) : array<string|int, IComment>

Throws PreConditionNotMetException when the system haven't the minimum requirements to use reactions

Parameters
$parentId : int
$reaction : string
Tags
throws
PreConditionNotMetException
since
24.0.0
Return values
array<string|int, IComment>

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 ]) : array<int, 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
array<int, IComment>

searchForObjects()

Search for comments on one or more objects with a given content

public searchForObjects(string $search, string $objectType, array<string|int, mixed> $objectIds, string $verb, int $offset[, int $limit = 50 ]) : array<string|int, IComment>
Parameters
$search : string

content to search for

$objectType : string

Limit the search by object type

$objectIds : array<string|int, mixed>

Limit the search by object ids

$verb : string

Limit the verb of the comment

$offset : int
$limit : int = 50
Tags
since
21.0.0
Return values
array<string|int, 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

supportReactions()

Support reactions

public supportReactions() : bool
Tags
since
24.0.0
Return values
bool 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results