1 | <?php |
||
26 | abstract class AbstractHierarchicalComponent |
||
27 | { |
||
28 | use ImmutableCollectionTrait; |
||
29 | |||
30 | use ImmutableComponentTrait; |
||
31 | |||
32 | const IS_ABSOLUTE = 1; |
||
33 | |||
34 | const IS_RELATIVE = 0; |
||
35 | |||
36 | /** |
||
37 | * Hierarchical component separator |
||
38 | * |
||
39 | * @var string |
||
40 | */ |
||
41 | protected static $separator; |
||
42 | |||
43 | /** |
||
44 | * Is the object considered absolute |
||
45 | * |
||
46 | * @var int |
||
47 | */ |
||
48 | protected $isAbsolute = self::IS_RELATIVE; |
||
49 | |||
50 | /** |
||
51 | * new instance |
||
52 | * |
||
53 | * @param null|string $str the component value |
||
54 | */ |
||
55 | abstract public function __construct($str); |
||
56 | |||
57 | /** |
||
58 | * Returns whether or not the component is absolute or not |
||
59 | * |
||
60 | * @return bool |
||
61 | */ |
||
62 | 27 | public function isAbsolute() |
|
66 | |||
67 | /** |
||
68 | * Returns an instance with the specified string |
||
69 | * |
||
70 | * This method MUST retain the state of the current instance, and return |
||
71 | * an instance that contains the modified data |
||
72 | * |
||
73 | * @param string $value |
||
74 | * |
||
75 | * @return static |
||
76 | */ |
||
77 | 612 | public function withContent($value = null) |
|
85 | |||
86 | /** |
||
87 | * DEPRECATION WARNING! This method will be removed in the next major point release |
||
88 | * |
||
89 | * @deprecated deprecated since version 4.2 |
||
90 | * |
||
91 | * @see withContent |
||
92 | * |
||
93 | * Returns an instance with the specified string |
||
94 | * |
||
95 | * This method MUST retain the state of the current instance, and return |
||
96 | * an instance that contains the modified data |
||
97 | * |
||
98 | * @param string $value |
||
99 | * |
||
100 | * @return static |
||
101 | */ |
||
102 | public function modify($value) |
||
106 | |||
107 | /** |
||
108 | * Returns the component literal value |
||
109 | * |
||
110 | * @return string|null |
||
111 | */ |
||
112 | abstract public function getContent(); |
||
113 | |||
114 | /** |
||
115 | * Returns the instance string representation; If the |
||
116 | * instance is not defined an empty string is returned |
||
117 | * |
||
118 | * @return string |
||
119 | */ |
||
120 | 1117 | public function __toString() |
|
124 | |||
125 | /** |
||
126 | * Returns the instance string representation |
||
127 | * with its optional URI delimiters |
||
128 | * |
||
129 | * @return string |
||
130 | */ |
||
131 | 824 | public function getUriComponent() |
|
135 | |||
136 | /** |
||
137 | * Returns an instance with the modified segment |
||
138 | * |
||
139 | * This method MUST retain the state of the current instance, and return |
||
140 | * an instance that contains the modified component with the replaced data |
||
141 | * |
||
142 | * @param int $offset the label offset to remove and replace by |
||
143 | * the given component |
||
144 | * @param HierarchicalComponent|string $component the component added |
||
145 | * |
||
146 | * @return static |
||
147 | */ |
||
148 | 72 | public function replace($offset, $component) |
|
167 | |||
168 | /** |
||
169 | * Validate a component as a HierarchicalComponent object |
||
170 | * |
||
171 | * @param HierarchicalComponent|string $component |
||
172 | * |
||
173 | * @return static |
||
174 | */ |
||
175 | 189 | protected function validateComponent($component) |
|
183 | |||
184 | /** |
||
185 | * DEPRECATION WARNING! This method will be removed in the next major point release |
||
186 | * |
||
187 | * @deprecated deprecated since version 4.2 |
||
188 | * |
||
189 | * return a new instance from an array or a traversable object |
||
190 | * |
||
191 | * @param \Traversable|string[] $data The segments list |
||
192 | * @param int $type one of the constant IS_ABSOLUTE or IS_RELATIVE |
||
193 | * |
||
194 | * @throws InvalidArgumentException If $type is not a recognized constant |
||
195 | * |
||
196 | * @return static |
||
197 | */ |
||
198 | public static function createFromArray($data, $type = self::IS_RELATIVE) |
||
207 | |||
208 | /** |
||
209 | * DEPRECATION WARNING! This method will be removed in the next major point release |
||
210 | * |
||
211 | * @deprecated deprecated since version 4.2 |
||
212 | * |
||
213 | * Return a formatted component string according to its type |
||
214 | * |
||
215 | * @param \Traversable|string[] $data The segments list |
||
216 | * @param int $type |
||
217 | * |
||
218 | * @throws InvalidArgumentException If $data is invalid |
||
219 | * |
||
220 | * @return string |
||
221 | */ |
||
222 | protected static function formatComponentString($data, $type) |
||
231 | } |
||
232 |
If you return a value from a function or method, it should be a sub-type of the type that is given by the parent type f.e. an interface, or abstract method. This is more formally defined by the Lizkov substitution principle, and guarantees that classes that depend on the parent type can use any instance of a child type interchangably. This principle also belongs to the SOLID principles for object oriented design.
Let’s take a look at an example:
Our function
my_function
expects aPost
object, and outputs the author of the post. The base classPost
returns a simple string and outputting a simple string will work just fine. However, the child classBlogPost
which is a sub-type ofPost
instead decided to return anobject
, and is therefore violating the SOLID principles. If aBlogPost
were passed tomy_function
, PHP would not complain, but ultimately fail when executing thestrtoupper
call in its body.