Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
n/a
0 / 0
n/a
0 / 0
CRAP
n/a
0 / 0
1<?php
2
3namespace MediaWiki\Extension\DiscussionTools;
4
5use MediaWiki\Extension\DiscussionTools\ThreadItem\CommentItem;
6use MediaWiki\Extension\DiscussionTools\ThreadItem\HeadingItem;
7use MediaWiki\Extension\DiscussionTools\ThreadItem\ThreadItem;
8
9/**
10 * Groups thread items (headings and comments) generated by parsing a discussion page.
11 */
12interface ThreadItemSet {
13    /**
14     * @param ThreadItem $item
15     * @internal Only used by CommentParser
16     */
17    public function addThreadItem( ThreadItem $item );
18
19    /**
20     * @return bool
21     * @internal Only used by CommentParser
22     */
23    public function isEmpty(): bool;
24
25    /**
26     * @param ThreadItem $item
27     * @internal Only used by CommentParser
28     */
29    public function updateIdAndNameMaps( ThreadItem $item );
30
31    /**
32     * Get all discussion comments (and headings) within a DOM subtree.
33     *
34     * This returns a flat list, use getThreads() to get a tree structure starting at section headings.
35     *
36     * For example, for a MediaWiki discussion like this (we're dealing with HTML DOM here,
37     * the wikitext syntax is just for illustration):
38     *
39     *     == A ==
40     *     B. ~~~~
41     *     : C.
42     *     : C. ~~~~
43     *     :: D. ~~~~
44     *     ::: E. ~~~~
45     *     ::: F. ~~~~
46     *     : G. ~~~~
47     *     H. ~~~~
48     *     : I. ~~~~
49     *
50     * This function would return a structure like:
51     *
52     *     [
53     *       HeadingItem( { level: 0, range: (h2: A)        } ),
54     *       CommentItem( { level: 1, range: (p: B)         } ),
55     *       CommentItem( { level: 2, range: (li: C, li: C) } ),
56     *       CommentItem( { level: 3, range: (li: D)        } ),
57     *       CommentItem( { level: 4, range: (li: E)        } ),
58     *       CommentItem( { level: 4, range: (li: F)        } ),
59     *       CommentItem( { level: 2, range: (li: G)        } ),
60     *       CommentItem( { level: 1, range: (p: H)         } ),
61     *       CommentItem( { level: 2, range: (li: I)        } )
62     *     ]
63     *
64     * @return ThreadItem[] Thread items
65     */
66    public function getThreadItems(): array;
67
68    /**
69     * Same as getFlatThreadItems, but only returns the CommentItems
70     *
71     * @return CommentItem[] Comment items
72     */
73    public function getCommentItems(): array;
74
75    /**
76     * Find ThreadItems by their name
77     *
78     * This will usually return a single-element array, but it may return multiple comments if they're
79     * indistinguishable by name. In that case, use their IDs to disambiguate.
80     *
81     * @param string $name Name
82     * @return ThreadItem[] Thread items, empty array if not found
83     */
84    public function findCommentsByName( string $name ): array;
85
86    /**
87     * Find a ThreadItem by its ID
88     *
89     * @param string $id ID
90     * @return ThreadItem|null Thread item, null if not found
91     */
92    public function findCommentById( string $id ): ?ThreadItem;
93
94    /**
95     * Group discussion comments into threads and associate replies to original messages.
96     *
97     * Each thread must begin with a heading. Original messages in the thread are treated as replies to
98     * its heading. Other replies are associated based on the order and indentation level.
99     *
100     * WARNING: Sub-headings are included twice in this tree, once as the child item of the
101     * "parent" heading, and once again in the root object.
102     *
103     * Note that the objects in `comments` are extended in-place with the additional data.
104     *
105     * For example, for a MediaWiki discussion like this (we're dealing with HTML DOM here,
106     * the wikitext syntax is just for illustration):
107     *
108     *     == A ==
109     *     B. ~~~~
110     *     : C.
111     *     : C. ~~~~
112     *     :: D. ~~~~
113     *     ::: E. ~~~~
114     *     ::: F. ~~~~
115     *     : G. ~~~~
116     *     H. ~~~~
117     *     : I. ~~~~
118     *
119     * This function would return a structure like:
120     *
121     *     [
122     *       HeadingItem( { level: 0, range: (h2: A), replies: [
123     *         CommentItem( { level: 1, range: (p: B), replies: [
124     *           CommentItem( { level: 2, range: (li: C, li: C), replies: [
125     *             CommentItem( { level: 3, range: (li: D), replies: [
126     *               CommentItem( { level: 4, range: (li: E), replies: [] } ),
127     *               CommentItem( { level: 4, range: (li: F), replies: [] } ),
128     *             ] } ),
129     *           ] } ),
130     *           CommentItem( { level: 2, range: (li: G), replies: [] } ),
131     *         ] } ),
132     *         CommentItem( { level: 1, range: (p: H), replies: [
133     *           CommentItem( { level: 2, range: (li: I), replies: [] } ),
134     *         ] } ),
135     *       ] } )
136     *     ]
137     *
138     * @return HeadingItem[] Tree structure of comments, top-level items are the headings.
139     */
140    public function getThreads(): array;
141
142    /**
143     * Same as #getThreads, but without the duplicate sub-headings described in the
144     * documentation of that method.
145     *
146     * @return HeadingItem[] Tree structure of comments, top-level items are the headings.
147     */
148    public function getThreadsStructured(): array;
149}