annotate core/modules/comment/src/CommentStorageInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\comment;
Chris@0 4
Chris@0 5 use Drupal\Core\Entity\EntityInterface;
Chris@0 6 use Drupal\Core\Entity\ContentEntityStorageInterface;
Chris@0 7 use Drupal\Core\Entity\FieldableEntityInterface;
Chris@0 8
Chris@0 9 /**
Chris@0 10 * Defines an interface for comment entity storage classes.
Chris@0 11 */
Chris@0 12 interface CommentStorageInterface extends ContentEntityStorageInterface {
Chris@0 13
Chris@0 14 /**
Chris@0 15 * Gets the maximum encoded thread value for the top level comments.
Chris@0 16 *
Chris@0 17 * @param \Drupal\comment\CommentInterface $comment
Chris@0 18 * A comment entity.
Chris@0 19 *
Chris@0 20 * @return string
Chris@0 21 * The maximum encoded thread value among the top level comments of the
Chris@0 22 * node $comment belongs to.
Chris@0 23 */
Chris@0 24 public function getMaxThread(CommentInterface $comment);
Chris@0 25
Chris@0 26 /**
Chris@0 27 * Gets the maximum encoded thread value for the children of this comment.
Chris@0 28 *
Chris@0 29 * @param \Drupal\comment\CommentInterface $comment
Chris@0 30 * A comment entity.
Chris@0 31 *
Chris@0 32 * @return string
Chris@0 33 * The maximum encoded thread value among all replies of $comment.
Chris@0 34 */
Chris@0 35 public function getMaxThreadPerThread(CommentInterface $comment);
Chris@0 36
Chris@0 37 /**
Chris@0 38 * Calculates the page number for the first new comment.
Chris@0 39 *
Chris@0 40 * @param int $total_comments
Chris@0 41 * The total number of comments that the entity has.
Chris@0 42 * @param int $new_comments
Chris@0 43 * The number of new comments that the entity has.
Chris@0 44 * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
Chris@0 45 * The entity to which the comments belong.
Chris@0 46 * @param string $field_name
Chris@0 47 * The field name on the entity to which comments are attached.
Chris@0 48 *
Chris@0 49 * @return array|null
Chris@0 50 * The page number where first new comment appears. (First page returns 0.)
Chris@0 51 */
Chris@0 52 public function getNewCommentPageNumber($total_comments, $new_comments, FieldableEntityInterface $entity, $field_name);
Chris@0 53
Chris@0 54 /**
Chris@0 55 * Gets the display ordinal or page number for a comment.
Chris@0 56 *
Chris@0 57 * @param \Drupal\comment\CommentInterface $comment
Chris@0 58 * The comment to use as a reference point.
Chris@0 59 * @param int $comment_mode
Chris@0 60 * The comment display mode: CommentManagerInterface::COMMENT_MODE_FLAT or
Chris@0 61 * CommentManagerInterface::COMMENT_MODE_THREADED.
Chris@0 62 * @param int $divisor
Chris@0 63 * Defaults to 1, which returns the display ordinal for a comment. If the
Chris@0 64 * number of comments per page is provided, the returned value will be the
Chris@0 65 * page number. (The return value will be divided by $divisor.)
Chris@0 66 *
Chris@0 67 * @return int
Chris@0 68 * The display ordinal or page number for the comment. It is 0-based, so
Chris@0 69 * will represent the number of items before the given comment/page.
Chris@0 70 */
Chris@0 71 public function getDisplayOrdinal(CommentInterface $comment, $comment_mode, $divisor = 1);
Chris@0 72
Chris@0 73 /**
Chris@0 74 * Gets the comment ids of the passed comment entities' children.
Chris@0 75 *
Chris@0 76 * @param \Drupal\comment\CommentInterface[] $comments
Chris@0 77 * An array of comment entities keyed by their ids.
Chris@0 78 * @return array
Chris@0 79 * The entity ids of the passed comment entities' children as an array.
Chris@0 80 */
Chris@0 81 public function getChildCids(array $comments);
Chris@0 82
Chris@0 83 /**
Chris@0 84 * Retrieves comments for a thread, sorted in an order suitable for display.
Chris@0 85 *
Chris@0 86 * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@0 87 * The entity whose comment(s) needs rendering.
Chris@0 88 * @param string $field_name
Chris@0 89 * The field_name whose comment(s) needs rendering.
Chris@0 90 * @param int $mode
Chris@0 91 * The comment display mode: CommentManagerInterface::COMMENT_MODE_FLAT or
Chris@0 92 * CommentManagerInterface::COMMENT_MODE_THREADED.
Chris@0 93 * @param int $comments_per_page
Chris@0 94 * (optional) The amount of comments to display per page.
Chris@0 95 * Defaults to 0, which means show all comments.
Chris@0 96 * @param int $pager_id
Chris@0 97 * (optional) Pager id to use in case of multiple pagers on the one page.
Chris@0 98 * Defaults to 0; is only used when $comments_per_page is greater than zero.
Chris@0 99 *
Chris@0 100 * @return array
Chris@0 101 * Ordered array of comment objects, keyed by comment id.
Chris@0 102 */
Chris@0 103 public function loadThread(EntityInterface $entity, $field_name, $mode, $comments_per_page = 0, $pager_id = 0);
Chris@0 104
Chris@0 105 /**
Chris@0 106 * Returns the number of unapproved comments.
Chris@0 107 *
Chris@0 108 * @return int
Chris@0 109 * The number of unapproved comments.
Chris@0 110 */
Chris@0 111 public function getUnapprovedCount();
Chris@0 112
Chris@0 113 }