CommentStorageInterface.php 4.03 KB
Newer Older
1
2
3
4
<?php

/**
 * @file
5
 * Contains \Drupal\comment\CommentStorageInterface.
6
7
8
9
 */

namespace Drupal\comment;

10
use Drupal\Core\Entity\EntityInterface;
11
use Drupal\Core\Entity\EntityStorageInterface;
12
use Drupal\Core\Entity\FieldableEntityInterface;
13
14

/**
15
 * Defines an interface for comment entity storage classes.
16
 */
17
interface CommentStorageInterface extends EntityStorageInterface {
18
19

  /**
20
   * Gets the maximum encoded thread value for the top level comments.
21
   *
22
   * @param \Drupal\comment\CommentInterface $comment
23
24
25
26
27
28
   *   A comment entity.
   *
   * @return string
   *   The maximum encoded thread value among the top level comments of the
   *   node $comment belongs to.
   */
29
  public function getMaxThread(CommentInterface $comment);
30
31

  /**
32
   * Gets the maximum encoded thread value for the children of this comment.
33
   *
34
   * @param \Drupal\comment\CommentInterface $comment
35
36
37
38
39
   *   A comment entity.
   *
   * @return string
   *   The maximum encoded thread value among all replies of $comment.
   */
40
41
42
43
44
45
46
47
48
  public function getMaxThreadPerThread(CommentInterface $comment);

  /**
   * Calculates the page number for the first new comment.
   *
   * @param int $total_comments
   *   The total number of comments that the entity has.
   * @param int $new_comments
   *   The number of new comments that the entity has.
49
   * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
50
51
52
53
54
55
56
   *   The entity to which the comments belong.
   * @param string $field_name
   *   The field name on the entity to which comments are attached.
   *
   * @return array|null
   *   The page number where first new comment appears. (First page returns 0.)
   */
57
  public function getNewCommentPageNumber($total_comments, $new_comments, FieldableEntityInterface $entity, $field_name);
58

59
60
61
62
63
64
  /**
   * Gets the display ordinal or page number for a comment.
   *
   * @param \Drupal\comment\CommentInterface $comment
   *   The comment to use as a reference point.
   * @param int $comment_mode
65
66
   *   The comment display mode: CommentManagerInterface::COMMENT_MODE_FLAT or
   *   CommentManagerInterface::COMMENT_MODE_THREADED.
67
68
69
70
71
72
73
74
75
76
77
   * @param int $divisor
   *   Defaults to 1, which returns the display ordinal for a comment. If the
   *   number of comments per page is provided, the returned value will be the
   *   page number. (The return value will be divided by $divisor.)
   *
   * @return int
   *   The display ordinal or page number for the comment. It is 0-based, so
   *   will represent the number of items before the given comment/page.
   */
  public function getDisplayOrdinal(CommentInterface $comment, $comment_mode, $divisor = 1);

78
79
80
  /**
   * Gets the comment ids of the passed comment entities' children.
   *
81
   * @param \Drupal\comment\CommentInterface[] $comments
82
83
84
85
86
87
   *   An array of comment entities keyed by their ids.
   * @return array
   *   The entity ids of the passed comment entities' children as an array.
   */
  public function getChildCids(array $comments);

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
  /**
   * Retrieves comments for a thread, sorted in an order suitable for display.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The entity whose comment(s) needs rendering.
   * @param string $field_name
   *   The field_name whose comment(s) needs rendering.
   * @param int $mode
   *   The comment display mode: CommentManagerInterface::COMMENT_MODE_FLAT or
   *   CommentManagerInterface::COMMENT_MODE_THREADED.
   * @param int $comments_per_page
   *   (optional) The amount of comments to display per page.
   *   Defaults to 0, which means show all comments.
   * @param int $pager_id
   *   (optional) Pager id to use in case of multiple pagers on the one page.
   *   Defaults to 0; is only used when $comments_per_page is greater than zero.
   *
   * @return array
   *   Ordered array of comment objects, keyed by comment id.
   */
  public function loadThread(EntityInterface $entity, $field_name, $mode, $comments_per_page = 0, $pager_id = 0);

110
111
112
113
114
115
116
117
  /**
   * Returns the number of unapproved comments.
   *
   * @return int
   *   The number of unapproved comments.
   */
  public function getUnapprovedCount();

118
}