www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/comment/src/CommentStorageInterface.php

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