xref: /PHP-Parser/lib/PhpParser/Node/Name.php (revision 954f7a41)
1<?php declare(strict_types=1);
2
3namespace PhpParser\Node;
4
5use PhpParser\NodeAbstract;
6
7class Name extends NodeAbstract {
8    /**
9     * @psalm-var non-empty-string
10     * @var string Name as string
11     */
12    public string $name;
13
14    /** @var array<string, bool> */
15    private static array $specialClassNames = [
16        'self'   => true,
17        'parent' => true,
18        'static' => true,
19    ];
20
21    /**
22     * Constructs a name node.
23     *
24     * @param string|string[]|self $name Name as string, part array or Name instance (copy ctor)
25     * @param array<string, mixed> $attributes Additional attributes
26     */
27    final public function __construct($name, array $attributes = []) {
28        $this->attributes = $attributes;
29        $this->name = self::prepareName($name);
30    }
31
32    public function getSubNodeNames(): array {
33        return ['name'];
34    }
35
36    /**
37     * Get parts of name (split by the namespace separator).
38     *
39     * @psalm-return non-empty-list<string>
40     * @return string[] Parts of name
41     */
42    public function getParts(): array {
43        return \explode('\\', $this->name);
44    }
45
46    /**
47     * Gets the first part of the name, i.e. everything before the first namespace separator.
48     *
49     * @return string First part of the name
50     */
51    public function getFirst(): string {
52        if (false !== $pos = \strpos($this->name, '\\')) {
53            return \substr($this->name, 0, $pos);
54        }
55        return $this->name;
56    }
57
58    /**
59     * Gets the last part of the name, i.e. everything after the last namespace separator.
60     *
61     * @return string Last part of the name
62     */
63    public function getLast(): string {
64        if (false !== $pos = \strrpos($this->name, '\\')) {
65            return \substr($this->name, $pos + 1);
66        }
67        return $this->name;
68    }
69
70    /**
71     * Checks whether the name is unqualified. (E.g. Name)
72     *
73     * @return bool Whether the name is unqualified
74     */
75    public function isUnqualified(): bool {
76        return false === \strpos($this->name, '\\');
77    }
78
79    /**
80     * Checks whether the name is qualified. (E.g. Name\Name)
81     *
82     * @return bool Whether the name is qualified
83     */
84    public function isQualified(): bool {
85        return false !== \strpos($this->name, '\\');
86    }
87
88    /**
89     * Checks whether the name is fully qualified. (E.g. \Name)
90     *
91     * @return bool Whether the name is fully qualified
92     */
93    public function isFullyQualified(): bool {
94        return false;
95    }
96
97    /**
98     * Checks whether the name is explicitly relative to the current namespace. (E.g. namespace\Name)
99     *
100     * @return bool Whether the name is relative
101     */
102    public function isRelative(): bool {
103        return false;
104    }
105
106    /**
107     * Returns a string representation of the name itself, without taking the name type into
108     * account (e.g., not including a leading backslash for fully qualified names).
109     *
110     * @psalm-return non-empty-string
111     * @return string String representation
112     */
113    public function toString(): string {
114        return $this->name;
115    }
116
117    /**
118     * Returns a string representation of the name as it would occur in code (e.g., including
119     * leading backslash for fully qualified names.
120     *
121     * @psalm-return non-empty-string
122     * @return string String representation
123     */
124    public function toCodeString(): string {
125        return $this->toString();
126    }
127
128    /**
129     * Returns lowercased string representation of the name, without taking the name type into
130     * account (e.g., no leading backslash for fully qualified names).
131     *
132     * @psalm-return non-empty-string&lowercase-string
133     * @return string Lowercased string representation
134     */
135    public function toLowerString(): string {
136        return strtolower($this->name);
137    }
138
139    /**
140     * Checks whether the identifier is a special class name (self, parent or static).
141     *
142     * @return bool Whether identifier is a special class name
143     */
144    public function isSpecialClassName(): bool {
145        return isset(self::$specialClassNames[strtolower($this->name)]);
146    }
147
148    /**
149     * Returns a string representation of the name by imploding the namespace parts with the
150     * namespace separator.
151     *
152     * @psalm-return non-empty-string
153     * @return string String representation
154     */
155    public function __toString(): string {
156        return $this->name;
157    }
158
159    /**
160     * Gets a slice of a name (similar to array_slice).
161     *
162     * This method returns a new instance of the same type as the original and with the same
163     * attributes.
164     *
165     * If the slice is empty, null is returned. The null value will be correctly handled in
166     * concatenations using concat().
167     *
168     * Offset and length have the same meaning as in array_slice().
169     *
170     * @param int $offset Offset to start the slice at (may be negative)
171     * @param int|null $length Length of the slice (may be negative)
172     *
173     * @return static|null Sliced name
174     */
175    public function slice(int $offset, ?int $length = null) {
176        if ($offset === 1 && $length === null) {
177            // Short-circuit the common case.
178            if (false !== $pos = \strpos($this->name, '\\')) {
179                return new static(\substr($this->name, $pos + 1));
180            }
181            return null;
182        }
183
184        $parts = \explode('\\', $this->name);
185        $numParts = \count($parts);
186
187        $realOffset = $offset < 0 ? $offset + $numParts : $offset;
188        if ($realOffset < 0 || $realOffset > $numParts) {
189            throw new \OutOfBoundsException(sprintf('Offset %d is out of bounds', $offset));
190        }
191
192        if (null === $length) {
193            $realLength = $numParts - $realOffset;
194        } else {
195            $realLength = $length < 0 ? $length + $numParts - $realOffset : $length;
196            if ($realLength < 0 || $realLength > $numParts - $realOffset) {
197                throw new \OutOfBoundsException(sprintf('Length %d is out of bounds', $length));
198            }
199        }
200
201        if ($realLength === 0) {
202            // Empty slice is represented as null
203            return null;
204        }
205
206        return new static(array_slice($parts, $realOffset, $realLength), $this->attributes);
207    }
208
209    /**
210     * Concatenate two names, yielding a new Name instance.
211     *
212     * The type of the generated instance depends on which class this method is called on, for
213     * example Name\FullyQualified::concat() will yield a Name\FullyQualified instance.
214     *
215     * If one of the arguments is null, a new instance of the other name will be returned. If both
216     * arguments are null, null will be returned. As such, writing
217     *     Name::concat($namespace, $shortName)
218     * where $namespace is a Name node or null will work as expected.
219     *
220     * @param string|string[]|self|null $name1 The first name
221     * @param string|string[]|self|null $name2 The second name
222     * @param array<string, mixed> $attributes Attributes to assign to concatenated name
223     *
224     * @return static|null Concatenated name
225     */
226    public static function concat($name1, $name2, array $attributes = []) {
227        if (null === $name1 && null === $name2) {
228            return null;
229        }
230        if (null === $name1) {
231            return new static($name2, $attributes);
232        }
233        if (null === $name2) {
234            return new static($name1, $attributes);
235        } else {
236            return new static(
237                self::prepareName($name1) . '\\' . self::prepareName($name2), $attributes
238            );
239        }
240    }
241
242    /**
243     * Prepares a (string, array or Name node) name for use in name changing methods by converting
244     * it to a string.
245     *
246     * @param string|string[]|self $name Name to prepare
247     *
248     * @psalm-return non-empty-string
249     * @return string Prepared name
250     */
251    private static function prepareName($name): string {
252        if (\is_string($name)) {
253            if ('' === $name) {
254                throw new \InvalidArgumentException('Name cannot be empty');
255            }
256
257            return $name;
258        }
259        if (\is_array($name)) {
260            if (empty($name)) {
261                throw new \InvalidArgumentException('Name cannot be empty');
262            }
263
264            return implode('\\', $name);
265        }
266        if ($name instanceof self) {
267            return $name->name;
268        }
269
270        throw new \InvalidArgumentException(
271            'Expected string, array of parts or Name instance'
272        );
273    }
274
275    public function getType(): string {
276        return 'Name';
277    }
278}
279