1
0

ICommentsManager.php 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475
  1. <?php
  2. /**
  3. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  4. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  5. * SPDX-License-Identifier: AGPL-3.0-only
  6. */
  7. namespace OCP\Comments;
  8. use OCP\IUser;
  9. use OCP\PreConditionNotMetException;
  10. /**
  11. * Interface ICommentsManager
  12. *
  13. * This class manages the access to comments
  14. *
  15. * @since 9.0.0
  16. */
  17. interface ICommentsManager {
  18. /**
  19. * @const DELETED_USER type and id for a user that has been deleted
  20. * @see deleteReferencesOfActor
  21. * @since 9.0.0
  22. *
  23. * To be used as replacement for user type actors in deleteReferencesOfActor().
  24. *
  25. * User interfaces shall show "Deleted user" as display name, if needed.
  26. */
  27. public const DELETED_USER = 'deleted_users';
  28. /**
  29. * returns a comment instance
  30. *
  31. * @param string $id the ID of the comment
  32. * @return IComment
  33. * @throws NotFoundException
  34. * @since 9.0.0
  35. */
  36. public function get($id);
  37. /**
  38. * Returns the comment specified by the id and all it's child comments
  39. *
  40. * @param string $id
  41. * @param int $limit max number of entries to return, 0 returns all
  42. * @param int $offset the start entry
  43. * @return array{comment: IComment, replies: list<array{comment: IComment, replies: array<empty, empty>}>}
  44. * @since 9.0.0
  45. *
  46. * The return array looks like this
  47. * [
  48. * 'comment' => IComment, // root comment
  49. * 'replies' =>
  50. * [
  51. * 0 =>
  52. * [
  53. * 'comment' => IComment,
  54. * 'replies' =>
  55. * [
  56. * 0 =>
  57. * [
  58. * 'comment' => IComment,
  59. * 'replies' => [ … ]
  60. * ],
  61. * …
  62. * ]
  63. * ]
  64. * 1 =>
  65. * [
  66. * 'comment' => IComment,
  67. * 'replies'=> [ … ]
  68. * ],
  69. * …
  70. * ]
  71. * ]
  72. */
  73. public function getTree($id, $limit = 0, $offset = 0);
  74. /**
  75. * returns comments for a specific object (e.g. a file).
  76. *
  77. * The sort order is always newest to oldest.
  78. *
  79. * @param string $objectType the object type, e.g. 'files'
  80. * @param string $objectId the id of the object
  81. * @param int $limit optional, number of maximum comments to be returned. if
  82. * not specified, all comments are returned.
  83. * @param int $offset optional, starting point
  84. * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments
  85. * that may be returned
  86. * @return list<IComment>
  87. * @since 9.0.0
  88. */
  89. public function getForObject(
  90. $objectType,
  91. $objectId,
  92. $limit = 0,
  93. $offset = 0,
  94. ?\DateTime $notOlderThan = null
  95. );
  96. /**
  97. * @param string $objectType the object type, e.g. 'files'
  98. * @param string $objectId the id of the object
  99. * @param int $lastKnownCommentId the last known comment (will be used as offset)
  100. * @param string $sortDirection direction of the comments (`asc` or `desc`)
  101. * @param int $limit optional, number of maximum comments to be returned. if
  102. * set to 0, all comments are returned.
  103. * @param bool $includeLastKnown
  104. * @return list<IComment>
  105. * @since 14.0.0
  106. * @deprecated 24.0.0 - Use getCommentsWithVerbForObjectSinceComment instead
  107. */
  108. public function getForObjectSince(
  109. string $objectType,
  110. string $objectId,
  111. int $lastKnownCommentId,
  112. string $sortDirection = 'asc',
  113. int $limit = 30,
  114. bool $includeLastKnown = false
  115. ): array;
  116. /**
  117. * @param string $objectType the object type, e.g. 'files'
  118. * @param string $objectId the id of the object
  119. * @param string[] $verbs List of verbs to filter by
  120. * @param int $lastKnownCommentId the last known comment (will be used as offset)
  121. * @param string $sortDirection direction of the comments (`asc` or `desc`)
  122. * @param int $limit optional, number of maximum comments to be returned. if
  123. * set to 0, all comments are returned.
  124. * @param bool $includeLastKnown
  125. * @return list<IComment>
  126. * @since 24.0.0
  127. */
  128. public function getCommentsWithVerbForObjectSinceComment(
  129. string $objectType,
  130. string $objectId,
  131. array $verbs,
  132. int $lastKnownCommentId,
  133. string $sortDirection = 'asc',
  134. int $limit = 30,
  135. bool $includeLastKnown = false
  136. ): array;
  137. /**
  138. * Search for comments with a given content
  139. *
  140. * @param string $search content to search for
  141. * @param string $objectType Limit the search by object type
  142. * @param string $objectId Limit the search by object id
  143. * @param string $verb Limit the verb of the comment
  144. * @param int $offset
  145. * @param int $limit
  146. * @return list<IComment>
  147. * @since 14.0.0
  148. */
  149. public function search(string $search, string $objectType, string $objectId, string $verb, int $offset, int $limit = 50): array;
  150. /**
  151. * Search for comments on one or more objects with a given content
  152. *
  153. * @param string $search content to search for
  154. * @param string $objectType Limit the search by object type
  155. * @param array $objectIds Limit the search by object ids
  156. * @param string $verb Limit the verb of the comment
  157. * @param int $offset
  158. * @param int $limit
  159. * @return IComment[]
  160. * @since 21.0.0
  161. */
  162. public function searchForObjects(string $search, string $objectType, array $objectIds, string $verb, int $offset, int $limit = 50): array;
  163. /**
  164. * @param $objectType string the object type, e.g. 'files'
  165. * @param $objectId string the id of the object
  166. * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments
  167. * that may be returned
  168. * @param string $verb Limit the verb of the comment - Added in 14.0.0
  169. * @return Int
  170. * @since 9.0.0
  171. */
  172. public function getNumberOfCommentsForObject($objectType, $objectId, ?\DateTime $notOlderThan = null, $verb = '');
  173. /**
  174. * @param string $objectType the object type, e.g. 'files'
  175. * @param string[] $objectIds the id of the object
  176. * @param IUser $user
  177. * @param string $verb Limit the verb of the comment - Added in 14.0.0
  178. * @return array Map with object id => # of unread comments
  179. * @psalm-return array<string, int>
  180. * @since 21.0.0
  181. */
  182. public function getNumberOfUnreadCommentsForObjects(string $objectType, array $objectIds, IUser $user, $verb = ''): array;
  183. /**
  184. * @param string $objectType
  185. * @param string $objectId
  186. * @param int $lastRead
  187. * @param string $verb
  188. * @return int
  189. * @since 21.0.0
  190. * @deprecated 24.0.0 - Use getNumberOfCommentsWithVerbsForObjectSinceComment instead
  191. */
  192. public function getNumberOfCommentsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, string $verb = ''): int;
  193. /**
  194. * @param string $objectType
  195. * @param string $objectId
  196. * @param int $lastRead
  197. * @param string[] $verbs
  198. * @return int
  199. * @since 24.0.0
  200. */
  201. public function getNumberOfCommentsWithVerbsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, array $verbs): int;
  202. /**
  203. * @param string $objectType
  204. * @param string $objectId
  205. * @param \DateTime $beforeDate
  206. * @param string $verb
  207. * @return int
  208. * @since 21.0.0
  209. */
  210. public function getLastCommentBeforeDate(string $objectType, string $objectId, \DateTime $beforeDate, string $verb = ''): int;
  211. /**
  212. * @param string $objectType
  213. * @param string $objectId
  214. * @param string $verb
  215. * @param string $actorType
  216. * @param string[] $actors
  217. * @return \DateTime[] Map of "string actor" => "\DateTime most recent comment date"
  218. * @psalm-return array<string, \DateTime>
  219. * @since 21.0.0
  220. */
  221. public function getLastCommentDateByActor(
  222. string $objectType,
  223. string $objectId,
  224. string $verb,
  225. string $actorType,
  226. array $actors
  227. ): array;
  228. /**
  229. * Get the number of unread comments for all files in a folder
  230. *
  231. * @param int $folderId
  232. * @param IUser $user
  233. * @return array [$fileId => $unreadCount]
  234. * @since 12.0.0
  235. * @deprecated 29.0.0 use getNumberOfUnreadCommentsForObjects instead
  236. */
  237. public function getNumberOfUnreadCommentsForFolder($folderId, IUser $user);
  238. /**
  239. * creates a new comment and returns it. At this point of time, it is not
  240. * saved in the used data storage. Use save() after setting other fields
  241. * of the comment (e.g. message or verb).
  242. *
  243. * @param string $actorType the actor type (e.g. 'users')
  244. * @param string $actorId a user id
  245. * @param string $objectType the object type the comment is attached to
  246. * @param string $objectId the object id the comment is attached to
  247. * @return IComment
  248. * @since 9.0.0
  249. */
  250. public function create($actorType, $actorId, $objectType, $objectId);
  251. /**
  252. * permanently deletes the comment specified by the ID
  253. *
  254. * When the comment has child comments, their parent ID will be changed to
  255. * the parent ID of the item that is to be deleted.
  256. *
  257. * @param string $id
  258. * @return bool
  259. * @since 9.0.0
  260. */
  261. public function delete($id);
  262. /**
  263. * Get comment related with user reaction
  264. *
  265. * Throws PreConditionNotMetException when the system haven't the minimum requirements to
  266. * use reactions
  267. *
  268. * @param int $parentId
  269. * @param string $actorType
  270. * @param string $actorId
  271. * @param string $reaction
  272. * @return IComment
  273. * @throws NotFoundException
  274. * @throws PreConditionNotMetException
  275. * @since 24.0.0
  276. */
  277. public function getReactionComment(int $parentId, string $actorType, string $actorId, string $reaction): IComment;
  278. /**
  279. * Retrieve all reactions of a message
  280. *
  281. * Throws PreConditionNotMetException when the system haven't the minimum requirements to
  282. * use reactions
  283. *
  284. * @param int $parentId
  285. * @return IComment[]
  286. * @throws PreConditionNotMetException
  287. * @since 24.0.0
  288. */
  289. public function retrieveAllReactions(int $parentId): array;
  290. /**
  291. * Retrieve all reactions with specific reaction of a message
  292. *
  293. * Throws PreConditionNotMetException when the system haven't the minimum requirements to
  294. * use reactions
  295. *
  296. * @param int $parentId
  297. * @param string $reaction
  298. * @return IComment[]
  299. * @throws PreConditionNotMetException
  300. * @since 24.0.0
  301. */
  302. public function retrieveAllReactionsWithSpecificReaction(int $parentId, string $reaction): array;
  303. /**
  304. * Support reactions
  305. *
  306. * @return bool
  307. * @since 24.0.0
  308. */
  309. public function supportReactions(): bool;
  310. /**
  311. * saves the comment permanently
  312. *
  313. * if the supplied comment has an empty ID, a new entry comment will be
  314. * saved and the instance updated with the new ID.
  315. *
  316. * Otherwise, an existing comment will be updated.
  317. *
  318. * Throws NotFoundException when a comment that is to be updated does not
  319. * exist anymore at this point of time.
  320. *
  321. * @param IComment $comment
  322. * @return bool
  323. * @throws NotFoundException
  324. * @since 9.0.0
  325. */
  326. public function save(IComment $comment);
  327. /**
  328. * removes references to specific actor (e.g. on user delete) of a comment.
  329. * The comment itself must not get lost/deleted.
  330. *
  331. * A 'users' type actor (type and id) should get replaced by the
  332. * value of the DELETED_USER constant of this interface.
  333. *
  334. * @param string $actorType the actor type (e.g. 'users')
  335. * @param string $actorId a user id
  336. * @return boolean
  337. * @since 9.0.0
  338. */
  339. public function deleteReferencesOfActor($actorType, $actorId);
  340. /**
  341. * deletes all comments made of a specific object (e.g. on file delete)
  342. *
  343. * @param string $objectType the object type (e.g. 'files')
  344. * @param string $objectId e.g. the file id
  345. * @return boolean
  346. * @since 9.0.0
  347. */
  348. public function deleteCommentsAtObject($objectType, $objectId);
  349. /**
  350. * sets the read marker for a given file to the specified date for the
  351. * provided user
  352. *
  353. * @param string $objectType
  354. * @param string $objectId
  355. * @param \DateTime $dateTime
  356. * @param \OCP\IUser $user
  357. * @since 9.0.0
  358. */
  359. public function setReadMark($objectType, $objectId, \DateTime $dateTime, \OCP\IUser $user);
  360. /**
  361. * returns the read marker for a given file to the specified date for the
  362. * provided user. It returns null, when the marker is not present, i.e.
  363. * no comments were marked as read.
  364. *
  365. * @param string $objectType
  366. * @param string $objectId
  367. * @param \OCP\IUser $user
  368. * @return \DateTime|null
  369. * @since 9.0.0
  370. */
  371. public function getReadMark($objectType, $objectId, \OCP\IUser $user);
  372. /**
  373. * deletes the read markers for the specified user
  374. *
  375. * @param \OCP\IUser $user
  376. * @return bool
  377. * @since 9.0.0
  378. */
  379. public function deleteReadMarksFromUser(\OCP\IUser $user);
  380. /**
  381. * deletes the read markers on the specified object
  382. *
  383. * @param string $objectType
  384. * @param string $objectId
  385. * @return bool
  386. * @since 9.0.0
  387. */
  388. public function deleteReadMarksOnObject($objectType, $objectId);
  389. /**
  390. * registers an Entity to the manager, so event notifications can be send
  391. * to consumers of the comments infrastructure
  392. *
  393. * @param \Closure $closure
  394. * @since 11.0.0
  395. */
  396. public function registerEventHandler(\Closure $closure);
  397. /**
  398. * registers a method that resolves an ID to a display name for a given type
  399. *
  400. * @param string $type
  401. * @param \Closure $closure
  402. * @throws \OutOfBoundsException
  403. * @since 11.0.0
  404. *
  405. * Only one resolver shall be registered per type. Otherwise a
  406. * \OutOfBoundsException has to thrown.
  407. */
  408. public function registerDisplayNameResolver($type, \Closure $closure);
  409. /**
  410. * resolves a given ID of a given Type to a display name.
  411. *
  412. * @param string $type
  413. * @param string $id
  414. * @return string
  415. * @throws \OutOfBoundsException
  416. * @since 11.0.0
  417. *
  418. * If a provided type was not registered, an \OutOfBoundsException shall
  419. * be thrown. It is upon the resolver discretion what to return of the
  420. * provided ID is unknown. It must be ensured that a string is returned.
  421. */
  422. public function resolveDisplayName($type, $id);
  423. /**
  424. * Load the Comments app into the page
  425. *
  426. * @since 21.0.0
  427. */
  428. public function load(): void;
  429. /**
  430. * Delete comments with field expire_date less than current date
  431. * Only will delete the message related with the object.
  432. *
  433. * @param string $objectType the object type (e.g. 'files')
  434. * @param string $objectId e.g. the file id, leave empty to expire on all objects of this type
  435. * @return boolean true if at least one row was deleted
  436. * @since 25.0.0
  437. */
  438. public function deleteCommentsExpiredAtObject(string $objectType, string $objectId = ''): bool;
  439. }