Chris@13: <?php declare(strict_types=1);
Chris@13: 
Chris@13: namespace PhpParser;
Chris@13: 
Chris@13: use PhpParser\Node\Expr;
Chris@13: use PhpParser\Node\Identifier;
Chris@13: use PhpParser\Node\Name;
Chris@13: use PhpParser\Node\NullableType;
Chris@13: use PhpParser\Node\Scalar;
Chris@13: use PhpParser\Node\Stmt;
Chris@13: 
Chris@13: /**
Chris@13:  * This class defines helpers used in the implementation of builders. Don't use it directly.
Chris@13:  *
Chris@13:  * @internal
Chris@13:  */
Chris@13: final class BuilderHelpers
Chris@13: {
Chris@13:     /**
Chris@13:      * Normalizes a node: Converts builder objects to nodes.
Chris@13:      *
Chris@13:      * @param Node|Builder $node The node to normalize
Chris@13:      *
Chris@13:      * @return Node The normalized node
Chris@13:      */
Chris@13:     public static function normalizeNode($node) : Node {
Chris@13:         if ($node instanceof Builder) {
Chris@13:             return $node->getNode();
Chris@13:         } elseif ($node instanceof Node) {
Chris@13:             return $node;
Chris@13:         }
Chris@13: 
Chris@13:         throw new \LogicException('Expected node or builder object');
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a node to a statement.
Chris@13:      *
Chris@13:      * Expressions are wrapped in a Stmt\Expression node.
Chris@13:      *
Chris@13:      * @param Node|Builder $node The node to normalize
Chris@13:      *
Chris@13:      * @return Stmt The normalized statement node
Chris@13:      */
Chris@13:     public static function normalizeStmt($node) : Stmt {
Chris@13:         $node = self::normalizeNode($node);
Chris@13:         if ($node instanceof Stmt) {
Chris@13:             return $node;
Chris@13:         }
Chris@13: 
Chris@13:         if ($node instanceof Expr) {
Chris@13:             return new Stmt\Expression($node);
Chris@13:         }
Chris@13: 
Chris@13:         throw new \LogicException('Expected statement or expression node');
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes strings to Identifier.
Chris@13:      *
Chris@13:      * @param string|Identifier $name The identifier to normalize
Chris@13:      *
Chris@13:      * @return Identifier The normalized identifier
Chris@13:      */
Chris@13:     public static function normalizeIdentifier($name) : Identifier {
Chris@13:         if ($name instanceof Identifier) {
Chris@13:             return $name;
Chris@13:         }
Chris@13: 
Chris@13:         if (\is_string($name)) {
Chris@13:             return new Identifier($name);
Chris@13:         }
Chris@13: 
Chris@17:         throw new \LogicException('Expected string or instance of Node\Identifier');
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes strings to Identifier, also allowing expressions.
Chris@13:      *
Chris@13:      * @param string|Identifier|Expr $name The identifier to normalize
Chris@13:      *
Chris@13:      * @return Identifier|Expr The normalized identifier or expression
Chris@13:      */
Chris@13:     public static function normalizeIdentifierOrExpr($name) {
Chris@13:         if ($name instanceof Identifier || $name instanceof Expr) {
Chris@13:             return $name;
Chris@13:         }
Chris@13: 
Chris@13:         if (\is_string($name)) {
Chris@13:             return new Identifier($name);
Chris@13:         }
Chris@13: 
Chris@13:         throw new \LogicException('Expected string or instance of Node\Identifier or Node\Expr');
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a name: Converts string names to Name nodes.
Chris@13:      *
Chris@13:      * @param Name|string $name The name to normalize
Chris@13:      *
Chris@13:      * @return Name The normalized name
Chris@13:      */
Chris@13:     public static function normalizeName($name) : Name {
Chris@13:         return self::normalizeNameCommon($name, false);
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a name: Converts string names to Name nodes, while also allowing expressions.
Chris@13:      *
Chris@13:      * @param Expr|Name|string $name The name to normalize
Chris@13:      *
Chris@13:      * @return Name|Expr The normalized name or expression
Chris@13:      */
Chris@13:     public static function normalizeNameOrExpr($name) {
Chris@13:         return self::normalizeNameCommon($name, true);
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a name: Converts string names to Name nodes, optionally allowing expressions.
Chris@13:      *
Chris@13:      * @param Expr|Name|string $name      The name to normalize
Chris@13:      * @param bool             $allowExpr Whether to also allow expressions
Chris@13:      *
Chris@13:      * @return Name|Expr The normalized name, or expression (if allowed)
Chris@13:      */
Chris@13:     private static function normalizeNameCommon($name, bool $allowExpr) {
Chris@13:         if ($name instanceof Name) {
Chris@13:             return $name;
Chris@13:         } elseif (is_string($name)) {
Chris@13:             if (!$name) {
Chris@13:                 throw new \LogicException('Name cannot be empty');
Chris@13:             }
Chris@13: 
Chris@13:             if ($name[0] === '\\') {
Chris@13:                 return new Name\FullyQualified(substr($name, 1));
Chris@13:             } elseif (0 === strpos($name, 'namespace\\')) {
Chris@13:                 return new Name\Relative(substr($name, strlen('namespace\\')));
Chris@13:             } else {
Chris@13:                 return new Name($name);
Chris@13:             }
Chris@13:         }
Chris@13: 
Chris@13:         if ($allowExpr) {
Chris@13:             if ($name instanceof Expr) {
Chris@13:                 return $name;
Chris@13:             }
Chris@13:             throw new \LogicException(
Chris@13:                 'Name must be a string or an instance of Node\Name or Node\Expr'
Chris@13:             );
Chris@13:         } else {
Chris@13:             throw new \LogicException('Name must be a string or an instance of Node\Name');
Chris@13:         }
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a type: Converts plain-text type names into proper AST representation.
Chris@13:      *
Chris@13:      * In particular, builtin types become Identifiers, custom types become Names and nullables
Chris@13:      * are wrapped in NullableType nodes.
Chris@13:      *
Chris@13:      * @param string|Name|Identifier|NullableType $type The type to normalize
Chris@13:      *
Chris@13:      * @return Name|Identifier|NullableType The normalized type
Chris@13:      */
Chris@13:     public static function normalizeType($type) {
Chris@13:         if (!is_string($type)) {
Chris@13:             if (!$type instanceof Name && !$type instanceof Identifier
Chris@13:                     && !$type instanceof NullableType) {
Chris@13:                 throw new \LogicException(
Chris@13:                     'Type must be a string, or an instance of Name, Identifier or NullableType');
Chris@13:             }
Chris@13:             return $type;
Chris@13:         }
Chris@13: 
Chris@13:         $nullable = false;
Chris@13:         if (strlen($type) > 0 && $type[0] === '?') {
Chris@13:             $nullable = true;
Chris@13:             $type = substr($type, 1);
Chris@13:         }
Chris@13: 
Chris@13:         $builtinTypes = [
Chris@13:             'array', 'callable', 'string', 'int', 'float', 'bool', 'iterable', 'void', 'object'
Chris@13:         ];
Chris@13: 
Chris@13:         $lowerType = strtolower($type);
Chris@13:         if (in_array($lowerType, $builtinTypes)) {
Chris@13:             $type = new Identifier($lowerType);
Chris@13:         } else {
Chris@13:             $type = self::normalizeName($type);
Chris@13:         }
Chris@13: 
Chris@13:         if ($nullable && (string) $type === 'void') {
Chris@13:             throw new \LogicException('void type cannot be nullable');
Chris@13:         }
Chris@13: 
Chris@13:         return $nullable ? new Node\NullableType($type) : $type;
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a value: Converts nulls, booleans, integers,
Chris@13:      * floats, strings and arrays into their respective nodes
Chris@13:      *
Chris@13:      * @param Node\Expr|bool|null|int|float|string|array $value The value to normalize
Chris@13:      *
Chris@13:      * @return Expr The normalized value
Chris@13:      */
Chris@13:     public static function normalizeValue($value) : Expr {
Chris@13:         if ($value instanceof Node\Expr) {
Chris@13:             return $value;
Chris@13:         } elseif (is_null($value)) {
Chris@13:             return new Expr\ConstFetch(
Chris@13:                 new Name('null')
Chris@13:             );
Chris@13:         } elseif (is_bool($value)) {
Chris@13:             return new Expr\ConstFetch(
Chris@13:                 new Name($value ? 'true' : 'false')
Chris@13:             );
Chris@13:         } elseif (is_int($value)) {
Chris@13:             return new Scalar\LNumber($value);
Chris@13:         } elseif (is_float($value)) {
Chris@13:             return new Scalar\DNumber($value);
Chris@13:         } elseif (is_string($value)) {
Chris@13:             return new Scalar\String_($value);
Chris@13:         } elseif (is_array($value)) {
Chris@13:             $items = [];
Chris@13:             $lastKey = -1;
Chris@13:             foreach ($value as $itemKey => $itemValue) {
Chris@13:                 // for consecutive, numeric keys don't generate keys
Chris@13:                 if (null !== $lastKey && ++$lastKey === $itemKey) {
Chris@13:                     $items[] = new Expr\ArrayItem(
Chris@13:                         self::normalizeValue($itemValue)
Chris@13:                     );
Chris@13:                 } else {
Chris@13:                     $lastKey = null;
Chris@13:                     $items[] = new Expr\ArrayItem(
Chris@13:                         self::normalizeValue($itemValue),
Chris@13:                         self::normalizeValue($itemKey)
Chris@13:                     );
Chris@13:                 }
Chris@13:             }
Chris@13: 
Chris@13:             return new Expr\Array_($items);
Chris@13:         } else {
Chris@13:             throw new \LogicException('Invalid value');
Chris@13:         }
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Normalizes a doc comment: Converts plain strings to PhpParser\Comment\Doc.
Chris@13:      *
Chris@13:      * @param Comment\Doc|string $docComment The doc comment to normalize
Chris@13:      *
Chris@13:      * @return Comment\Doc The normalized doc comment
Chris@13:      */
Chris@13:     public static function normalizeDocComment($docComment) : Comment\Doc {
Chris@13:         if ($docComment instanceof Comment\Doc) {
Chris@13:             return $docComment;
Chris@13:         } elseif (is_string($docComment)) {
Chris@13:             return new Comment\Doc($docComment);
Chris@13:         } else {
Chris@13:             throw new \LogicException('Doc comment must be a string or an instance of PhpParser\Comment\Doc');
Chris@13:         }
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * Adds a modifier and returns new modifier bitmask.
Chris@13:      *
Chris@13:      * @param int $modifiers Existing modifiers
Chris@13:      * @param int $modifier  Modifier to set
Chris@13:      *
Chris@13:      * @return int New modifiers
Chris@13:      */
Chris@13:     public static function addModifier(int $modifiers, int $modifier) : int {
Chris@13:         Stmt\Class_::verifyModifier($modifiers, $modifier);
Chris@13:         return $modifiers | $modifier;
Chris@13:     }
Chris@13: }