1 <?php declare(strict_types=1);
5 use PhpParser\Node\Expr;
6 use PhpParser\Node\Identifier;
7 use PhpParser\Node\Name;
8 use PhpParser\Node\NullableType;
9 use PhpParser\Node\Scalar;
10 use PhpParser\Node\Stmt;
13 * This class defines helpers used in the implementation of builders. Don't use it directly.
17 final class BuilderHelpers
20 * Normalizes a node: Converts builder objects to nodes.
22 * @param Node|Builder $node The node to normalize
24 * @return Node The normalized node
26 public static function normalizeNode($node) : Node {
27 if ($node instanceof Builder) {
28 return $node->getNode();
29 } elseif ($node instanceof Node) {
33 throw new \LogicException('Expected node or builder object');
37 * Normalizes a node to a statement.
39 * Expressions are wrapped in a Stmt\Expression node.
41 * @param Node|Builder $node The node to normalize
43 * @return Stmt The normalized statement node
45 public static function normalizeStmt($node) : Stmt {
46 $node = self::normalizeNode($node);
47 if ($node instanceof Stmt) {
51 if ($node instanceof Expr) {
52 return new Stmt\Expression($node);
55 throw new \LogicException('Expected statement or expression node');
59 * Normalizes strings to Identifier.
61 * @param string|Identifier $name The identifier to normalize
63 * @return Identifier The normalized identifier
65 public static function normalizeIdentifier($name) : Identifier {
66 if ($name instanceof Identifier) {
70 if (\is_string($name)) {
71 return new Identifier($name);
74 throw new \LogicException('Expected string or instance of Node\Identifier or Node\Expr');
78 * Normalizes strings to Identifier, also allowing expressions.
80 * @param string|Identifier|Expr $name The identifier to normalize
82 * @return Identifier|Expr The normalized identifier or expression
84 public static function normalizeIdentifierOrExpr($name) {
85 if ($name instanceof Identifier || $name instanceof Expr) {
89 if (\is_string($name)) {
90 return new Identifier($name);
93 throw new \LogicException('Expected string or instance of Node\Identifier or Node\Expr');
97 * Normalizes a name: Converts string names to Name nodes.
99 * @param Name|string $name The name to normalize
101 * @return Name The normalized name
103 public static function normalizeName($name) : Name {
104 return self::normalizeNameCommon($name, false);
108 * Normalizes a name: Converts string names to Name nodes, while also allowing expressions.
110 * @param Expr|Name|string $name The name to normalize
112 * @return Name|Expr The normalized name or expression
114 public static function normalizeNameOrExpr($name) {
115 return self::normalizeNameCommon($name, true);
119 * Normalizes a name: Converts string names to Name nodes, optionally allowing expressions.
121 * @param Expr|Name|string $name The name to normalize
122 * @param bool $allowExpr Whether to also allow expressions
124 * @return Name|Expr The normalized name, or expression (if allowed)
126 private static function normalizeNameCommon($name, bool $allowExpr) {
127 if ($name instanceof Name) {
129 } elseif (is_string($name)) {
131 throw new \LogicException('Name cannot be empty');
134 if ($name[0] === '\\') {
135 return new Name\FullyQualified(substr($name, 1));
136 } elseif (0 === strpos($name, 'namespace\\')) {
137 return new Name\Relative(substr($name, strlen('namespace\\')));
139 return new Name($name);
144 if ($name instanceof Expr) {
147 throw new \LogicException(
148 'Name must be a string or an instance of Node\Name or Node\Expr'
151 throw new \LogicException('Name must be a string or an instance of Node\Name');
156 * Normalizes a type: Converts plain-text type names into proper AST representation.
158 * In particular, builtin types become Identifiers, custom types become Names and nullables
159 * are wrapped in NullableType nodes.
161 * @param string|Name|Identifier|NullableType $type The type to normalize
163 * @return Name|Identifier|NullableType The normalized type
165 public static function normalizeType($type) {
166 if (!is_string($type)) {
167 if (!$type instanceof Name && !$type instanceof Identifier
168 && !$type instanceof NullableType) {
169 throw new \LogicException(
170 'Type must be a string, or an instance of Name, Identifier or NullableType');
176 if (strlen($type) > 0 && $type[0] === '?') {
178 $type = substr($type, 1);
182 'array', 'callable', 'string', 'int', 'float', 'bool', 'iterable', 'void', 'object'
185 $lowerType = strtolower($type);
186 if (in_array($lowerType, $builtinTypes)) {
187 $type = new Identifier($lowerType);
189 $type = self::normalizeName($type);
192 if ($nullable && (string) $type === 'void') {
193 throw new \LogicException('void type cannot be nullable');
196 return $nullable ? new Node\NullableType($type) : $type;
200 * Normalizes a value: Converts nulls, booleans, integers,
201 * floats, strings and arrays into their respective nodes
203 * @param Node\Expr|bool|null|int|float|string|array $value The value to normalize
205 * @return Expr The normalized value
207 public static function normalizeValue($value) : Expr {
208 if ($value instanceof Node\Expr) {
210 } elseif (is_null($value)) {
211 return new Expr\ConstFetch(
214 } elseif (is_bool($value)) {
215 return new Expr\ConstFetch(
216 new Name($value ? 'true' : 'false')
218 } elseif (is_int($value)) {
219 return new Scalar\LNumber($value);
220 } elseif (is_float($value)) {
221 return new Scalar\DNumber($value);
222 } elseif (is_string($value)) {
223 return new Scalar\String_($value);
224 } elseif (is_array($value)) {
227 foreach ($value as $itemKey => $itemValue) {
228 // for consecutive, numeric keys don't generate keys
229 if (null !== $lastKey && ++$lastKey === $itemKey) {
230 $items[] = new Expr\ArrayItem(
231 self::normalizeValue($itemValue)
235 $items[] = new Expr\ArrayItem(
236 self::normalizeValue($itemValue),
237 self::normalizeValue($itemKey)
242 return new Expr\Array_($items);
244 throw new \LogicException('Invalid value');
249 * Normalizes a doc comment: Converts plain strings to PhpParser\Comment\Doc.
251 * @param Comment\Doc|string $docComment The doc comment to normalize
253 * @return Comment\Doc The normalized doc comment
255 public static function normalizeDocComment($docComment) : Comment\Doc {
256 if ($docComment instanceof Comment\Doc) {
258 } elseif (is_string($docComment)) {
259 return new Comment\Doc($docComment);
261 throw new \LogicException('Doc comment must be a string or an instance of PhpParser\Comment\Doc');
266 * Adds a modifier and returns new modifier bitmask.
268 * @param int $modifiers Existing modifiers
269 * @param int $modifier Modifier to set
271 * @return int New modifiers
273 public static function addModifier(int $modifiers, int $modifier) : int {
274 Stmt\Class_::verifyModifier($modifiers, $modifier);
275 return $modifiers | $modifier;