You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

282 lines
6.0 KiB

3 years ago
  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 Roeland Jago Douma <roeland@famdouma.nl>
  9. * @author Thomas Müller <thomas.mueller@tmit.eu>
  10. *
  11. * @license AGPL-3.0
  12. *
  13. * This code is free software: you can redistribute it and/or modify
  14. * it under the terms of the GNU Affero General Public License, version 3,
  15. * as published by the Free Software Foundation.
  16. *
  17. * This program is distributed in the hope that it will be useful,
  18. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20. * GNU Affero General Public License for more details.
  21. *
  22. * You should have received a copy of the GNU Affero General Public License, version 3,
  23. * along with this program. If not, see <http://www.gnu.org/licenses/>
  24. *
  25. */
  26. namespace OCP\Comments;
  27. /**
  28. * Interface IComment
  29. *
  30. * This class represents a comment
  31. *
  32. * @since 9.0.0
  33. */
  34. interface IComment {
  35. public const MAX_MESSAGE_LENGTH = 1000;
  36. /**
  37. * returns the ID of the comment
  38. *
  39. * It may return an empty string, if the comment was not stored.
  40. * It is expected that the concrete Comment implementation gives an ID
  41. * by itself (e.g. after saving).
  42. *
  43. * @return string
  44. * @since 9.0.0
  45. */
  46. public function getId();
  47. /**
  48. * sets the ID of the comment and returns itself
  49. *
  50. * It is only allowed to set the ID only, if the current id is an empty
  51. * string (which means it is not stored in a database, storage or whatever
  52. * the concrete implementation does), or vice versa. Changing a given ID is
  53. * not permitted and must result in an IllegalIDChangeException.
  54. *
  55. * @param string $id
  56. * @return IComment
  57. * @throws IllegalIDChangeException
  58. * @since 9.0.0
  59. */
  60. public function setId($id);
  61. /**
  62. * returns the parent ID of the comment
  63. *
  64. * @return string
  65. * @since 9.0.0
  66. */
  67. public function getParentId();
  68. /**
  69. * sets the parent ID and returns itself
  70. * @param string $parentId
  71. * @return IComment
  72. * @since 9.0.0
  73. */
  74. public function setParentId($parentId);
  75. /**
  76. * returns the topmost parent ID of the comment
  77. *
  78. * @return string
  79. * @since 9.0.0
  80. */
  81. public function getTopmostParentId();
  82. /**
  83. * sets the topmost parent ID and returns itself
  84. *
  85. * @param string $id
  86. * @return IComment
  87. * @since 9.0.0
  88. */
  89. public function setTopmostParentId($id);
  90. /**
  91. * returns the number of children
  92. *
  93. * @return int
  94. * @since 9.0.0
  95. */
  96. public function getChildrenCount();
  97. /**
  98. * sets the number of children
  99. *
  100. * @param int $count
  101. * @return IComment
  102. * @since 9.0.0
  103. */
  104. public function setChildrenCount($count);
  105. /**
  106. * returns the message of the comment
  107. *
  108. * @return string
  109. * @since 9.0.0
  110. */
  111. public function getMessage();
  112. /**
  113. * sets the message of the comment and returns itself
  114. *
  115. * When the given message length exceeds MAX_MESSAGE_LENGTH an
  116. * MessageTooLongException shall be thrown.
  117. *
  118. * @param string $message
  119. * @param int $maxLength
  120. * @return IComment
  121. * @throws MessageTooLongException
  122. * @since 9.0.0 - $maxLength added in 16.0.2
  123. */
  124. public function setMessage($message, $maxLength = self::MAX_MESSAGE_LENGTH);
  125. /**
  126. * returns an array containing mentions that are included in the comment
  127. *
  128. * @return array each mention provides a 'type' and an 'id', see example below
  129. * @since 11.0.0
  130. *
  131. * The return array looks like:
  132. * [
  133. * [
  134. * 'type' => 'user',
  135. * 'id' => 'citizen4'
  136. * ],
  137. * [
  138. * 'type' => 'group',
  139. * 'id' => 'media'
  140. * ],
  141. *
  142. * ]
  143. *
  144. */
  145. public function getMentions();
  146. /**
  147. * returns the verb of the comment
  148. *
  149. * @return string
  150. * @since 9.0.0
  151. */
  152. public function getVerb();
  153. /**
  154. * sets the verb of the comment, e.g. 'comment' or 'like'
  155. *
  156. * @param string $verb
  157. * @return IComment
  158. * @since 9.0.0
  159. */
  160. public function setVerb($verb);
  161. /**
  162. * returns the actor type
  163. *
  164. * @return string
  165. * @since 9.0.0
  166. */
  167. public function getActorType();
  168. /**
  169. * returns the actor ID
  170. *
  171. * @return string
  172. * @since 9.0.0
  173. */
  174. public function getActorId();
  175. /**
  176. * sets (overwrites) the actor type and id
  177. *
  178. * @param string $actorType e.g. 'users'
  179. * @param string $actorId e.g. 'zombie234'
  180. * @return IComment
  181. * @since 9.0.0
  182. */
  183. public function setActor($actorType, $actorId);
  184. /**
  185. * returns the creation date of the comment.
  186. *
  187. * If not explicitly set, it shall default to the time of initialization.
  188. *
  189. * @return \DateTime
  190. * @since 9.0.0
  191. */
  192. public function getCreationDateTime();
  193. /**
  194. * sets the creation date of the comment and returns itself
  195. *
  196. * @param \DateTime $dateTime
  197. * @return IComment
  198. * @since 9.0.0
  199. */
  200. public function setCreationDateTime(\DateTime $dateTime);
  201. /**
  202. * returns the date of the most recent child
  203. *
  204. * @return \DateTime
  205. * @since 9.0.0
  206. */
  207. public function getLatestChildDateTime();
  208. /**
  209. * sets the date of the most recent child
  210. *
  211. * @param \DateTime $dateTime
  212. * @return IComment
  213. * @since 9.0.0
  214. */
  215. public function setLatestChildDateTime(\DateTime $dateTime);
  216. /**
  217. * returns the object type the comment is attached to
  218. *
  219. * @return string
  220. * @since 9.0.0
  221. */
  222. public function getObjectType();
  223. /**
  224. * returns the object id the comment is attached to
  225. *
  226. * @return string
  227. * @since 9.0.0
  228. */
  229. public function getObjectId();
  230. /**
  231. * sets (overwrites) the object of the comment
  232. *
  233. * @param string $objectType e.g. 'files'
  234. * @param string $objectId e.g. '16435'
  235. * @return IComment
  236. * @since 9.0.0
  237. */
  238. public function setObject($objectType, $objectId);
  239. /**
  240. * returns the reference id of the comment
  241. *
  242. * @return string|null
  243. * @since 19.0.0
  244. */
  245. public function getReferenceId(): ?string;
  246. /**
  247. * sets (overwrites) the reference id of the comment
  248. *
  249. * @param string|null $referenceId e.g. sha256 hash sum
  250. * @return IComment
  251. * @since 19.0.0
  252. */
  253. public function setReferenceId(?string $referenceId): IComment;
  254. }