These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more
1 | <?php |
||
2 | |||
3 | declare(strict_types=1); |
||
4 | |||
5 | /** |
||
6 | * This file is part of phpDocumentor. |
||
7 | * |
||
8 | * For the full copyright and license information, please view the LICENSE |
||
9 | * file that was distributed with this source code. |
||
10 | * |
||
11 | * @link http://phpdoc.org |
||
12 | */ |
||
13 | |||
14 | namespace phpDocumentor\Descriptor; |
||
15 | |||
16 | use phpDocumentor\Descriptor\Validation\Error; |
||
17 | use phpDocumentor\Reflection\Fqsen; |
||
18 | |||
19 | /** |
||
20 | * Represents a file in the project. |
||
21 | * |
||
22 | * This class contains all structural elements of the file it represents. In most modern projects a |
||
23 | * file will contain a single element like a Class, Interface or Trait, sometimes multiple functions. |
||
24 | * Depending on the config settings of the parsed project it might include all source code from the file in the project. |
||
25 | * |
||
26 | * @api |
||
27 | * @package phpDocumentor\AST |
||
28 | */ |
||
29 | class FileDescriptor extends DescriptorAbstract implements Interfaces\FileInterface |
||
30 | { |
||
31 | /** @var string $hash */ |
||
32 | protected $hash; |
||
33 | |||
34 | /** @var string $path */ |
||
35 | protected $path = ''; |
||
36 | |||
37 | /** @var string|null $source */ |
||
38 | protected $source = null; |
||
39 | |||
40 | /** @var Collection<NamespaceDescriptor>|Collection<Fqsen> $namespaceAliases */ |
||
41 | protected $namespaceAliases; |
||
42 | |||
43 | /** @var Collection<string> $includes */ |
||
44 | protected $includes; |
||
45 | |||
46 | /** @var Collection<ConstantDescriptor> $constants */ |
||
47 | protected $constants; |
||
48 | |||
49 | /** @var Collection<FunctionDescriptor> $functions */ |
||
50 | protected $functions; |
||
51 | |||
52 | /** @var Collection<ClassDescriptor> $classes */ |
||
53 | protected $classes; |
||
54 | |||
55 | /** @var Collection<InterfaceDescriptor> $interfaces */ |
||
56 | protected $interfaces; |
||
57 | |||
58 | /** @var Collection<TraitDescriptor> $traits */ |
||
59 | protected $traits; |
||
60 | |||
61 | /** @var Collection<array<int|string, mixed>> $markers */ |
||
62 | protected $markers; |
||
63 | |||
64 | /** |
||
65 | * Initializes a new file descriptor with the given hash of its contents. |
||
66 | * |
||
67 | * @param string $hash An MD5 hash of the contents if this file. |
||
68 | */ |
||
69 | 15 | public function __construct(string $hash) |
|
70 | { |
||
71 | 15 | parent::__construct(); |
|
72 | |||
73 | 15 | $this->setHash($hash); |
|
74 | 15 | $this->setNamespaceAliases(new Collection()); |
|
75 | 15 | $this->setIncludes(new Collection()); |
|
76 | |||
77 | 15 | $this->setConstants(new Collection()); |
|
78 | 15 | $this->setFunctions(new Collection()); |
|
79 | 15 | $this->setClasses(new Collection()); |
|
80 | 15 | $this->setInterfaces(new Collection()); |
|
81 | 15 | $this->setTraits(new Collection()); |
|
82 | |||
83 | 15 | $this->setMarkers(new Collection()); |
|
84 | 15 | } |
|
85 | |||
86 | /** |
||
87 | * Returns the hash of the contents for this file. |
||
88 | */ |
||
89 | 1 | public function getHash() : string |
|
90 | { |
||
91 | 1 | return $this->hash; |
|
92 | } |
||
93 | |||
94 | /** |
||
95 | * Sets the hash of the contents for this file. |
||
96 | */ |
||
97 | 1 | protected function setHash(string $hash) : void |
|
98 | { |
||
99 | 1 | $this->hash = $hash; |
|
100 | 1 | } |
|
101 | |||
102 | /** |
||
103 | * Retrieves the contents of this file. |
||
104 | * |
||
105 | * When source is included in parsing process this property will contain the raw file contents. |
||
106 | */ |
||
107 | 2 | public function getSource() : ?string |
|
108 | { |
||
109 | 2 | return $this->source; |
|
110 | } |
||
111 | |||
112 | /** |
||
113 | * Sets the source contents for this file. |
||
114 | * |
||
115 | * @internal should not be called by any other class than the assamblers |
||
116 | */ |
||
117 | 2 | public function setSource(?string $source) : void |
|
118 | { |
||
119 | 2 | $this->source = $source; |
|
120 | 2 | } |
|
121 | |||
122 | /** |
||
123 | * Returns the namespace aliases that have been defined in this file. |
||
124 | * |
||
125 | * A namespace alias can either be a full descriptor of the namespace or just a {@see Fqsen} |
||
126 | * when the namespace was not part of the processed code. When it is a {@see NamespaceDescriptor} it |
||
127 | * will contain all structural elements in the namespace not just the once in this particlar file. |
||
128 | * |
||
129 | * @return Collection<NamespaceDescriptor>|Collection<Fqsen> |
||
130 | */ |
||
131 | 1 | public function getNamespaceAliases() : Collection |
|
132 | { |
||
133 | 1 | return $this->namespaceAliases; |
|
134 | } |
||
135 | |||
136 | /** |
||
137 | * Sets the collection of namespace aliases for this file. |
||
138 | * |
||
139 | * @internal should not be called by any other class than the assamblers |
||
140 | * |
||
141 | * @param Collection<NamespaceDescriptor>|Collection<Fqsen> $namespaceAliases |
||
142 | */ |
||
143 | 2 | public function setNamespaceAliases(Collection $namespaceAliases) : void |
|
144 | { |
||
145 | 2 | $this->namespaceAliases = $namespaceAliases; |
|
146 | 2 | } |
|
147 | |||
148 | /** |
||
149 | * Returns a list of all includes that have been declared in this file. |
||
150 | * |
||
151 | * @return Collection<string> |
||
152 | */ |
||
153 | 1 | public function getIncludes() : Collection |
|
154 | { |
||
155 | 1 | return $this->includes; |
|
156 | } |
||
157 | |||
158 | /** |
||
159 | * Sets a list of all includes that have been declared in this file. |
||
160 | * |
||
161 | * @internal should not be called by any other class than the assamblers |
||
162 | * |
||
163 | * @param Collection<string> $includes |
||
164 | */ |
||
165 | 2 | public function setIncludes(Collection $includes) : void |
|
166 | { |
||
167 | 2 | $this->includes = $includes; |
|
168 | 2 | } |
|
169 | |||
170 | /** |
||
171 | * Returns a list of constant descriptors contained in this file. |
||
172 | * |
||
173 | * {@inheritDoc} |
||
174 | */ |
||
175 | 1 | public function getConstants() : Collection |
|
176 | { |
||
177 | 1 | return $this->constants; |
|
178 | } |
||
179 | |||
180 | /** |
||
181 | * Sets a list of constant descriptors contained in this file. |
||
182 | * |
||
183 | * @internal should not be called by any other class than the assamblers |
||
184 | * |
||
185 | * @param Collection<ConstantDescriptor> $constants |
||
186 | */ |
||
187 | 2 | public function setConstants(Collection $constants) : void |
|
188 | { |
||
189 | 2 | $this->constants = $constants; |
|
190 | 2 | } |
|
191 | |||
192 | /** |
||
193 | * Returns a list of function descriptors contained in this file. |
||
194 | * |
||
195 | * {@inheritDoc} |
||
196 | */ |
||
197 | 1 | public function getFunctions() : Collection |
|
198 | { |
||
199 | 1 | return $this->functions; |
|
200 | } |
||
201 | |||
202 | /** |
||
203 | * Sets a list of function descriptors contained in this file. |
||
204 | * |
||
205 | * @internal should not be called by any other class than the assamblers |
||
206 | * |
||
207 | * @param Collection<FunctionDescriptor> $functions |
||
208 | */ |
||
209 | 2 | public function setFunctions(Collection $functions) : void |
|
210 | { |
||
211 | 2 | $this->functions = $functions; |
|
212 | 2 | } |
|
213 | |||
214 | /** |
||
215 | * Returns a list of class descriptors contained in this file. |
||
216 | * |
||
217 | * {@inheritDoc} |
||
218 | */ |
||
219 | 1 | public function getClasses() : Collection |
|
220 | { |
||
221 | 1 | return $this->classes; |
|
222 | } |
||
223 | |||
224 | /** |
||
225 | * Sets a list of class descriptors contained in this file. |
||
226 | * |
||
227 | * @internal should not be called by any other class than the assamblers |
||
228 | * |
||
229 | * @param Collection<ClassDescriptor> $classes |
||
230 | */ |
||
231 | 2 | public function setClasses(Collection $classes) : void |
|
232 | { |
||
233 | 2 | $this->classes = $classes; |
|
234 | 2 | } |
|
235 | |||
236 | /** |
||
237 | * Returns a list of interface descriptors contained in this file. |
||
238 | * |
||
239 | * {@inheritDoc} |
||
240 | */ |
||
241 | 1 | public function getInterfaces() : Collection |
|
242 | { |
||
243 | 1 | return $this->interfaces; |
|
244 | } |
||
245 | |||
246 | /** |
||
247 | * Sets a list of interface descriptors contained in this file. |
||
248 | * |
||
249 | * @internal should not be called by any other class than the assamblers |
||
250 | * |
||
251 | * @param Collection<InterfaceDescriptor> $interfaces |
||
252 | */ |
||
253 | 2 | public function setInterfaces(Collection $interfaces) : void |
|
254 | { |
||
255 | 2 | $this->interfaces = $interfaces; |
|
256 | 2 | } |
|
257 | |||
258 | /** |
||
259 | * Returns a list of trait descriptors contained in this file. |
||
260 | * |
||
261 | * {@inheritDoc} |
||
262 | */ |
||
263 | 1 | public function getTraits() : Collection |
|
264 | { |
||
265 | 1 | return $this->traits; |
|
266 | } |
||
267 | |||
268 | /** |
||
269 | * Sets a list of trait descriptors contained in this file. |
||
270 | * |
||
271 | * @internal should not be called by any other class than the assamblers |
||
272 | * |
||
273 | * @param Collection<TraitDescriptor> $traits |
||
274 | */ |
||
275 | 2 | public function setTraits(Collection $traits) : void |
|
276 | { |
||
277 | 2 | $this->traits = $traits; |
|
278 | 2 | } |
|
279 | |||
280 | /** |
||
281 | * Returns a series of markers contained in this file. |
||
282 | * |
||
283 | * A marker is a special inline comment that starts with a keyword and is followed by a single line description. |
||
284 | * |
||
285 | * Example: |
||
286 | * ``` |
||
287 | * // TODO: This is an item that needs to be done. |
||
288 | * ``` |
||
289 | * |
||
290 | * @return Collection<array<int|string, mixed>> |
||
291 | */ |
||
292 | 2 | public function getMarkers() : Collection |
|
293 | { |
||
294 | 2 | return $this->markers; |
|
295 | } |
||
296 | |||
297 | /** |
||
298 | * Sets a series of markers contained in this file. |
||
299 | * |
||
300 | * @internal should not be called by any other class than the assamblers |
||
301 | * |
||
302 | * @see getMarkers() for more information on markers. |
||
303 | * |
||
304 | * @param Collection<array<int|string, mixed>> $markers |
||
305 | */ |
||
306 | 2 | public function setMarkers(Collection $markers) : void |
|
307 | { |
||
308 | 2 | $this->markers = $markers; |
|
309 | 2 | } |
|
310 | |||
311 | /** |
||
312 | * Returns a list of all errors in this file and all its child elements. |
||
313 | * |
||
314 | * All errors from structual elements in the file are collected to the deepes level. |
||
315 | * |
||
316 | * @return Collection<Error> |
||
0 ignored issues
–
show
|
|||
317 | */ |
||
318 | 2 | public function getAllErrors() : Collection |
|
319 | { |
||
320 | 2 | $errors = $this->getErrors(); |
|
321 | |||
322 | 2 | $types = Collection::fromClassString(DescriptorAbstract::class) |
|
323 | 2 | ->merge($this->getClasses()) |
|
324 | 2 | ->merge($this->getInterfaces()) |
|
325 | 2 | ->merge($this->getTraits()); |
|
326 | |||
327 | 2 | $elements = Collection::fromClassString(DescriptorAbstract::class) |
|
328 | 2 | ->merge($this->getFunctions()) |
|
329 | 2 | ->merge($this->getConstants()) |
|
330 | 2 | ->merge($types); |
|
331 | |||
332 | 2 | foreach ($elements as $element) { |
|
333 | 1 | $errors = $errors->merge($element->getErrors()); |
|
334 | } |
||
335 | |||
336 | 2 | foreach ($types as $element) { |
|
337 | 1 | if ($element instanceof ClassDescriptor || |
|
338 | 1 | $element instanceof InterfaceDescriptor || |
|
339 | 1 | $element instanceof TraitDescriptor |
|
340 | ) { |
||
341 | 1 | foreach ($element->getMethods() as $item) { |
|
342 | 1 | $errors = $errors->merge($item->getErrors()); |
|
343 | } |
||
344 | } |
||
345 | |||
346 | 1 | if ($element instanceof ClassDescriptor || |
|
347 | 1 | $element instanceof InterfaceDescriptor |
|
348 | ) { |
||
349 | 1 | foreach ($element->getConstants() as $item) { |
|
350 | 1 | $errors = $errors->merge($item->getErrors()); |
|
351 | } |
||
352 | } |
||
353 | |||
354 | 1 | if (!$element instanceof ClassDescriptor && |
|
355 | 1 | !$element instanceof TraitDescriptor |
|
356 | ) { |
||
357 | 1 | continue; |
|
358 | } |
||
359 | |||
360 | 1 | foreach ($element->getProperties() as $item) { |
|
361 | 1 | $errors = $errors->merge($item->getErrors()); |
|
362 | } |
||
363 | } |
||
364 | |||
365 | 2 | return $errors; |
|
366 | } |
||
367 | |||
368 | /** |
||
369 | * Sets the file path for this file relative to the project's root. |
||
370 | * |
||
371 | * @internal should not be called by any other class than the assamblers |
||
372 | * |
||
373 | */ |
||
374 | 1 | public function setPath(string $path) : void |
|
375 | { |
||
376 | 1 | $this->path = $path; |
|
377 | 1 | } |
|
378 | |||
379 | /** |
||
380 | * Returns the relative file path. |
||
381 | * |
||
382 | * The path is a relative to the source file based on the dsn of the config. |
||
383 | */ |
||
384 | 1 | public function getPath() : string |
|
385 | { |
||
386 | 1 | return $this->path; |
|
387 | } |
||
388 | |||
389 | public function __toString() : string |
||
390 | { |
||
391 | return $this->getPath(); |
||
392 | } |
||
393 | } |
||
394 |
This check marks PHPDoc comments that could not be parsed by our parser. To see which comment annotations we can parse, please refer to our documentation on supported doc-types.