1: <?php
2:
3: namespace Charcoal\Object;
4:
5: /**
6: *
7: */
8: interface HierarchicalInterface
9: {
10: /**
11: * Determine if this object has a direct parent.
12: *
13: * @return boolean
14: */
15: public function hasMaster();
16:
17: /**
18: * Determine if this object is the head (top-level) of its hierarchy.
19: *
20: * Top-level objects do not have a parent (master).
21: *
22: * @return boolean
23: */
24: public function isTopLevel();
25:
26: /**
27: * Determine if this object is the tail (last-level) of its hierarchy.
28: *
29: * Last-level objects do not have a children.
30: *
31: * @return boolean
32: */
33: public function isLastLevel();
34:
35: /**
36: * Retrieve this object's position (level) in its hierarchy.
37: *
38: * Starts at "1" (top-level).
39: *
40: * @return integer
41: */
42: public function hierarchyLevel();
43:
44: /**
45: * Retrieve this object's immediate parent.
46: *
47: * @return HierarchicalInterface|null
48: */
49: public function master();
50:
51: /**
52: * Retrieve the top-level ancestor of this object.
53: *
54: * @return HierarchicalInterface|null
55: */
56: public function toplevelMaster();
57:
58: /**
59: * Determine if this object has any ancestors.
60: *
61: * @return boolean
62: */
63: public function hasParents();
64:
65: /**
66: * Retrieve this object's ancestors (from immediate parent to top-level).
67: *
68: * @return array
69: */
70: public function hierarchy();
71:
72: /**
73: * Retrieve this object's ancestors, inverted from top-level to immediate.
74: *
75: * @return array
76: */
77: public function invertedHierarchy();
78:
79: /**
80: * Determine if the object is the parent of the given object.
81: *
82: * @param mixed $child The child (or ID) to match against.
83: * @return boolean
84: */
85: public function isMasterOf($child);
86:
87: /**
88: * Determine if the object is a parent/ancestor of the given object.
89: *
90: * @param mixed $child The child (or ID) to match against.
91: * @return boolean
92: */
93: public function recursiveIsMasterOf($child);
94:
95: /**
96: * Get wether the object has any children at all
97: * @return boolean
98: */
99: public function hasChildren();
100:
101: /**
102: * Get the number of chidlren directly under this object.
103: * @return integer
104: */
105: public function numChildren();
106:
107: /**
108: * Get the total number of children in the entire hierarchy.
109: * This method counts all children and sub-children, unlike `numChildren()` which only count 1 level.
110: * @return integer
111: */
112: public function recursiveNumChildren();
113:
114:
115: /**
116: * Get the children directly under this object.
117: * @return array
118: */
119: public function children();
120:
121: /**
122: * @param mixed $master The master object (or ident) to check against.
123: * @return boolean The master object (or ident) to check against.
124: */
125: public function isChildOf($master);
126:
127: /**
128: * @param mixed $master The master object (or ident) to check against.
129: * @return boolean
130: */
131: public function recursiveIsChildOf($master);
132:
133: /**
134: * @return boolean
135: */
136: public function hasSiblings();
137:
138: /**
139: * @return integer
140: */
141: public function numSiblings();
142:
143: /**
144: * Get all the objects on the same level as this one.
145: * @return array
146: */
147: public function siblings();
148:
149: /**
150: * @param mixed $sibling The sibling object (or ident) to check against.
151: * @return boolean
152: */
153: public function isSiblingOf($sibling);
154: }
155: