1
0

ICommentsManager.php 14 KB

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