diff options
Diffstat (limited to 'lib/public/comments/icommentsmanager.php')
| -rw-r--r-- | lib/public/comments/icommentsmanager.php | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/lib/public/comments/icommentsmanager.php b/lib/public/comments/icommentsmanager.php new file mode 100644 index 00000000000..ebf7a34bf27 --- /dev/null +++ b/lib/public/comments/icommentsmanager.php @@ -0,0 +1,161 @@ +<?php + +namespace OCP\Comments; + +/** + * Interface ICommentsManager + * + * This class manages the access to comments + * + * @package OCP\Comments + * @since 9.0.0 + */ +interface ICommentsManager { + + /** + * returns a comment instance + * + * @param string $id the ID of the comment + * @return IComment + * @throws NotFoundException + * @since 9.0.0 + */ + public function get($id); + + /** + * returns the comment specified by the id and all it's child comments + * + * @param string $id + * @param int $limit max number of entries to return, 0 returns all + * @param int $offset the start entry + * @return [] + * @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'=> [ … ] + * ], + * … + * ] + * ] + */ + public function getTree($id, $limit = 0, $offset = 0); + + /** + * returns comments for a specific object (e.g. a file). + * + * The sort order is always newest to oldest. + * + * @param string $objectType the object type, e.g. 'files' + * @param string $objectId the id of the object + * @param int $limit optional, number of maximum comments to be returned. if + * not specified, all comments are returned. + * @param int $offset optional, starting point + * @param \DateTime $notOlderThan optional, timestamp of the oldest comments + * that may be returned + * @return IComment[] + * @throws NotFoundException in case the requested type or id is not present + * @since 9.0.0 + */ + public function getForObject( + $objectType, + $objectId, + $limit = 0, + $offset = 0, + \DateTime $notOlderThan = null + ); + + /** + * @param $objectType string the object type, e.g. 'files' + * @param $objectId string the id of the object + * @return Int + * @throws NotFoundException in case the requested type or id is not present + * @since 9.0.0 + */ + public function getNumberOfCommentsForObject($objectType, $objectId); + + /** + * 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). + * + * @param string $actorType the actor type (e.g. 'user') + * @param string $actorId a user id + * @param string $objectType the object type the comment is attached to + * @param string $objectId the object id the comment is attached to + * @return IComment + * @since 9.0.0 + */ + public function create($actorType, $actorId, $objectType, $objectId); + + /** + * permanently deletes the comment specified by the ID + * + * When the comment has child comments, their parent ID will be changed to + * the parent ID of the item that is to be deleted. + * + * @param string $id + * @return bool + * @since 9.0.0 + */ + public function delete($id); + + /** + * saves the comment permanently and returns it + * + * 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. + * + * @param IComment + * @return bool + * @throws NotFoundException + * @since 9.0.0 + */ + public function save(&$comment); + + /** + * removes references to specific actor (e.g. on user delete) of a comment. + * The comment itself must not get lost/deleted. + * + * @param string $actorType the actor type (e.g. 'user') + * @param string $actorId a user id + * @return boolean + * @since 9.0.0 + */ + public function deleteReferencesOfActor($actorType, $actorId); + + /** + * deletes all comments made of a specific object (e.g. on file delete) + * + * @param string $objectType the object type (e.g. 'file') + * @param string $objectId e.g. the file id + * @return boolean + * @since 9.0.0 + */ + public function deleteCommentsAtObject($objectType, $objectId); + +} |