BuilderHelpers.php 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313
  1. <?php declare(strict_types=1);
  2. namespace PhpParser;
  3. use PhpParser\Node\ComplexType;
  4. use PhpParser\Node\Expr;
  5. use PhpParser\Node\Identifier;
  6. use PhpParser\Node\Name;
  7. use PhpParser\Node\NullableType;
  8. use PhpParser\Node\Scalar;
  9. use PhpParser\Node\Stmt;
  10. /**
  11. * This class defines helpers used in the implementation of builders. Don't use it directly.
  12. *
  13. * @internal
  14. */
  15. final class BuilderHelpers
  16. {
  17. /**
  18. * Normalizes a node: Converts builder objects to nodes.
  19. *
  20. * @param Node|Builder $node The node to normalize
  21. *
  22. * @return Node The normalized node
  23. */
  24. public static function normalizeNode($node) : Node {
  25. if ($node instanceof Builder) {
  26. return $node->getNode();
  27. }
  28. if ($node instanceof Node) {
  29. return $node;
  30. }
  31. throw new \LogicException('Expected node or builder object');
  32. }
  33. /**
  34. * Normalizes a node to a statement.
  35. *
  36. * Expressions are wrapped in a Stmt\Expression node.
  37. *
  38. * @param Node|Builder $node The node to normalize
  39. *
  40. * @return Stmt The normalized statement node
  41. */
  42. public static function normalizeStmt($node) : Stmt {
  43. $node = self::normalizeNode($node);
  44. if ($node instanceof Stmt) {
  45. return $node;
  46. }
  47. if ($node instanceof Expr) {
  48. return new Stmt\Expression($node);
  49. }
  50. throw new \LogicException('Expected statement or expression node');
  51. }
  52. /**
  53. * Normalizes strings to Identifier.
  54. *
  55. * @param string|Identifier $name The identifier to normalize
  56. *
  57. * @return Identifier The normalized identifier
  58. */
  59. public static function normalizeIdentifier($name) : Identifier {
  60. if ($name instanceof Identifier) {
  61. return $name;
  62. }
  63. if (\is_string($name)) {
  64. return new Identifier($name);
  65. }
  66. throw new \LogicException('Expected string or instance of Node\Identifier');
  67. }
  68. /**
  69. * Normalizes strings to Identifier, also allowing expressions.
  70. *
  71. * @param string|Identifier|Expr $name The identifier to normalize
  72. *
  73. * @return Identifier|Expr The normalized identifier or expression
  74. */
  75. public static function normalizeIdentifierOrExpr($name) {
  76. if ($name instanceof Identifier || $name instanceof Expr) {
  77. return $name;
  78. }
  79. if (\is_string($name)) {
  80. return new Identifier($name);
  81. }
  82. throw new \LogicException('Expected string or instance of Node\Identifier or Node\Expr');
  83. }
  84. /**
  85. * Normalizes a name: Converts string names to Name nodes.
  86. *
  87. * @param Name|string $name The name to normalize
  88. *
  89. * @return Name The normalized name
  90. */
  91. public static function normalizeName($name) : Name {
  92. if ($name instanceof Name) {
  93. return $name;
  94. }
  95. if (is_string($name)) {
  96. if (!$name) {
  97. throw new \LogicException('Name cannot be empty');
  98. }
  99. if ($name[0] === '\\') {
  100. return new Name\FullyQualified(substr($name, 1));
  101. }
  102. if (0 === strpos($name, 'namespace\\')) {
  103. return new Name\Relative(substr($name, strlen('namespace\\')));
  104. }
  105. return new Name($name);
  106. }
  107. throw new \LogicException('Name must be a string or an instance of Node\Name');
  108. }
  109. /**
  110. * Normalizes a name: Converts string names to Name nodes, while also allowing expressions.
  111. *
  112. * @param Expr|Name|string $name The name to normalize
  113. *
  114. * @return Name|Expr The normalized name or expression
  115. */
  116. public static function normalizeNameOrExpr($name) {
  117. if ($name instanceof Expr) {
  118. return $name;
  119. }
  120. if (!is_string($name) && !($name instanceof Name)) {
  121. throw new \LogicException(
  122. 'Name must be a string or an instance of Node\Name or Node\Expr'
  123. );
  124. }
  125. return self::normalizeName($name);
  126. }
  127. /**
  128. * Normalizes a type: Converts plain-text type names into proper AST representation.
  129. *
  130. * In particular, builtin types become Identifiers, custom types become Names and nullables
  131. * are wrapped in NullableType nodes.
  132. *
  133. * @param string|Name|Identifier|ComplexType $type The type to normalize
  134. *
  135. * @return Name|Identifier|ComplexType The normalized type
  136. */
  137. public static function normalizeType($type) {
  138. if (!is_string($type)) {
  139. if (
  140. !$type instanceof Name && !$type instanceof Identifier &&
  141. !$type instanceof ComplexType
  142. ) {
  143. throw new \LogicException(
  144. 'Type must be a string, or an instance of Name, Identifier or ComplexType'
  145. );
  146. }
  147. return $type;
  148. }
  149. $nullable = false;
  150. if (strlen($type) > 0 && $type[0] === '?') {
  151. $nullable = true;
  152. $type = substr($type, 1);
  153. }
  154. $builtinTypes = [
  155. 'array', 'callable', 'string', 'int', 'float', 'bool', 'iterable', 'void', 'object', 'mixed', 'never',
  156. ];
  157. $lowerType = strtolower($type);
  158. if (in_array($lowerType, $builtinTypes)) {
  159. $type = new Identifier($lowerType);
  160. } else {
  161. $type = self::normalizeName($type);
  162. }
  163. $notNullableTypes = [
  164. 'void', 'mixed', 'never',
  165. ];
  166. if ($nullable && in_array((string) $type, $notNullableTypes)) {
  167. throw new \LogicException(sprintf('%s type cannot be nullable', $type));
  168. }
  169. return $nullable ? new NullableType($type) : $type;
  170. }
  171. /**
  172. * Normalizes a value: Converts nulls, booleans, integers,
  173. * floats, strings and arrays into their respective nodes
  174. *
  175. * @param Node\Expr|bool|null|int|float|string|array $value The value to normalize
  176. *
  177. * @return Expr The normalized value
  178. */
  179. public static function normalizeValue($value) : Expr {
  180. if ($value instanceof Node\Expr) {
  181. return $value;
  182. }
  183. if (is_null($value)) {
  184. return new Expr\ConstFetch(
  185. new Name('null')
  186. );
  187. }
  188. if (is_bool($value)) {
  189. return new Expr\ConstFetch(
  190. new Name($value ? 'true' : 'false')
  191. );
  192. }
  193. if (is_int($value)) {
  194. return new Scalar\LNumber($value);
  195. }
  196. if (is_float($value)) {
  197. return new Scalar\DNumber($value);
  198. }
  199. if (is_string($value)) {
  200. return new Scalar\String_($value);
  201. }
  202. if (is_array($value)) {
  203. $items = [];
  204. $lastKey = -1;
  205. foreach ($value as $itemKey => $itemValue) {
  206. // for consecutive, numeric keys don't generate keys
  207. if (null !== $lastKey && ++$lastKey === $itemKey) {
  208. $items[] = new Expr\ArrayItem(
  209. self::normalizeValue($itemValue)
  210. );
  211. } else {
  212. $lastKey = null;
  213. $items[] = new Expr\ArrayItem(
  214. self::normalizeValue($itemValue),
  215. self::normalizeValue($itemKey)
  216. );
  217. }
  218. }
  219. return new Expr\Array_($items);
  220. }
  221. throw new \LogicException('Invalid value');
  222. }
  223. /**
  224. * Normalizes a doc comment: Converts plain strings to PhpParser\Comment\Doc.
  225. *
  226. * @param Comment\Doc|string $docComment The doc comment to normalize
  227. *
  228. * @return Comment\Doc The normalized doc comment
  229. */
  230. public static function normalizeDocComment($docComment) : Comment\Doc {
  231. if ($docComment instanceof Comment\Doc) {
  232. return $docComment;
  233. }
  234. if (is_string($docComment)) {
  235. return new Comment\Doc($docComment);
  236. }
  237. throw new \LogicException('Doc comment must be a string or an instance of PhpParser\Comment\Doc');
  238. }
  239. /**
  240. * Normalizes a attribute: Converts attribute to the Attribute Group if needed.
  241. *
  242. * @param Node\Attribute|Node\AttributeGroup $attribute
  243. *
  244. * @return Node\AttributeGroup The Attribute Group
  245. */
  246. public static function normalizeAttribute($attribute) : Node\AttributeGroup
  247. {
  248. if ($attribute instanceof Node\AttributeGroup) {
  249. return $attribute;
  250. }
  251. if (!($attribute instanceof Node\Attribute)) {
  252. throw new \LogicException('Attribute must be an instance of PhpParser\Node\Attribute or PhpParser\Node\AttributeGroup');
  253. }
  254. return new Node\AttributeGroup([$attribute]);
  255. }
  256. /**
  257. * Adds a modifier and returns new modifier bitmask.
  258. *
  259. * @param int $modifiers Existing modifiers
  260. * @param int $modifier Modifier to set
  261. *
  262. * @return int New modifiers
  263. */
  264. public static function addModifier(int $modifiers, int $modifier) : int {
  265. Stmt\Class_::verifyModifier($modifiers, $modifier);
  266. return $modifiers | $modifier;
  267. }
  268. }