* Dariusz Rumiński * * This source file is subject to the MIT license that is bundled * with this source code in the file LICENSE. */ namespace PhpCsFixer\DocBlock; use PhpCsFixer\Preg; use PhpCsFixer\Tokenizer\Analyzer\Analysis\NamespaceAnalysis; use PhpCsFixer\Tokenizer\Analyzer\Analysis\NamespaceUseAnalysis; use PhpCsFixer\Utils; /** * @author Michael Vorisek * * @internal * * @no-named-arguments Parameter names are not covered by the backward compatibility promise. */ final class TypeExpression { /** * Regex to match any PHP identifier. * * @internal */ public const REGEX_IDENTIFIER = '(?:(?!(?(?x) # one or several types separated by `|` or `&` '.self::REGEX_TYPE.' (?: \h*(?[|&])\h* (?&type) )*+ )'; /** * Based on: * - https://github.com/phpstan/phpdoc-parser/blob/1.26.0/doc/grammars/type.abnf fuzzing grammar * - and https://github.com/phpstan/phpdoc-parser/blob/1.26.0/src/Parser/PhpDocParser.php parser impl. */ private const REGEX_TYPE = '(?(?x) # single type (?:co(ntra)?variant\h+)? (?\??\h*) (?: (? (?(?i)(?:array|list|object)(?-i)) (?\h*\{[\h\v*]*) (? (? (?(?:(?&constant)|(?&identifier)|(?&name))\h*\??\h*:\h*|) (?(?&types_inner)) ) (?: \h*,[\h\v*]* (?&array_shape_inner) )*+ (?:\h*,|(?!(?&array_shape_unsealed_variadic))) |) (? # unsealed array shape, e.g. `...`. `...` (?\h*\.\.\.) (? (?\h*<\h*) (?(?&types_inner)) (?: (?\h*,\h*) (?(?&array_shape_unsealed_type_a)) |) \h*> |) |) [\h\v*]*\} ) | (? # callable syntax, e.g. `callable(string, int...): bool`, `\Closure(T, int): T` (?(?&name)) (? (?\h*<\h*) (? (? (? (?&identifier) ) (? # template bound \h+(?i)(?of|as)(?-i)\h+ (?(?&types_inner)) |) (? # template default \h*=\h* (?(?&types_inner)) |) ) (?: \h*,\h* (?&callable_template_inner) )*+ ) \h*> (?=\h*\() |) (?\h*\(\h*) (? (? (?(?&types_inner)) (?\h*&|) (?\h*\.\.\.|) (?\h*\$(?&identifier)|) (?\h*=|) ) (?: \h*,\h* (?&callable_argument) )*+ (?:\h*,)? |) \h*\) (?: \h*\:\h* (?(?&type)) )? ) | (? # generic syntax, e.g.: `array` (?(?&name)) (?\h*<[\h\v*]*) (? (?&types_inner) (?: \h*,[\h\v*]* (?&types_inner) )*+ (?:\h*,)? ) [\h\v*]*> ) | (? # class constants with optional wildcard, e.g.: `Foo::*`, `Foo::CONST_A`, `FOO::CONST_*` (?(?&name)) ::\*?(?:(?&identifier)\*?)* ) | (? # single constant value (case insensitive), e.g.: 1, -1.8E+6, `\'a\'` (?i) # all sorts of numbers: with or without sign, supports literal separator and several numeric systems, # e.g.: 1, +1.1, 1., .1, -1, 123E+8, 123_456_789, 0x7Fb4, 0b0110, 0o777 [+-]?(?: (?:0b[01]++(?:_[01]++)*+) | (?:0o[0-7]++(?:_[0-7]++)*+) | (?:0x[\da-f]++(?:_[\da-f]++)*+) | (?:(?\d++(?:_\d++)*+)|(?=\.\d)) (?:\.(?&constant_digits)|(?<=\d)\.)?+ (?:e[+-]?(?&constant_digits))?+ ) | \'(?:[^\'\\\]|\\\.)*+\' | "(?:[^"\\\]|\\\.)*+" (?-i) ) | (? # self reference, e.g.: $this, $self, @static (?i) [@$](?:this | self | static) (?-i) ) | (? # full name, e.g.: `int`, `\DateTime`, `\Foo\Bar`, `positive-int` \\\?+ (?'.self::REGEX_IDENTIFIER.') (?:[\\\\\-](?&identifier))*+ ) | (? # parenthesized type, e.g.: `(int)`, `(int|\stdClass)` (? \(\h* ) (?: (? (?&types_inner) ) | (? # conditional type, e.g.: `$foo is \Throwable ? false : $foo` (? (?:\$(?&identifier)) | (?(?&types_inner)) ) (? \h+(?i)is(?:\h+not)?(?-i)\h+ ) (?(?&types_inner)) (?\h*\?\h*) (?(?&types_inner)) (?\h*:\h*) (?(?&types_inner)) ) ) \h*\) ) ) (? # array, e.g.: `string[]`, `array[][]` (\h*\[\h*\])* ) (?:(?=1)0 (?(?> (?&type) (?: \h*[|&]\h* (?&type) )*+ )) |) )'; private const ALIASES = [ 'boolean' => 'bool', 'callback' => 'callable', 'double' => 'float', 'false' => 'bool', 'integer' => 'int', 'list' => 'array', 'real' => 'float', 'true' => 'bool', ]; private string $value; private bool $isCompositeType; /** @var null|'&'|'|' */ private ?string $typesGlue = null; /** @var list */ private array $innerTypeExpressions = []; private ?NamespaceAnalysis $namespace; /** @var list */ private array $namespaceUses; /** * @param list $namespaceUses */ public function __construct(string $value, ?NamespaceAnalysis $namespace, array $namespaceUses) { $this->value = $value; $this->namespace = $namespace; $this->namespaceUses = $namespaceUses; $this->parse(); } public function toString(): string { return $this->value; } /** * @return list */ public function getTypes(): array { if ($this->isCompositeType) { return array_map( static fn (array $type) => $type['expression']->toString(), $this->innerTypeExpressions, ); } return [$this->value]; } /** * Determines if type expression is a composite type (union or intersection). */ public function isCompositeType(): bool { return $this->isCompositeType; } public function isUnionType(): bool { return $this->isCompositeType && '|' === $this->typesGlue; } public function isIntersectionType(): bool { return $this->isCompositeType && '&' === $this->typesGlue; } /** * @return null|'&'|'|' */ public function getTypesGlue(): ?string { return $this->typesGlue; } /** * @param \Closure(self): self $callback */ public function mapTypes(\Closure $callback): self { $value = $this->value; $startIndexOffset = 0; foreach ($this->innerTypeExpressions as [ 'start_index' => $startIndexOrig, 'expression' => $inner, ]) { $innerValueOrig = $inner->value; $inner = $inner->mapTypes($callback); if ($inner->value !== $innerValueOrig) { $value = substr_replace( $value, $inner->value, $startIndexOrig + $startIndexOffset, \strlen($innerValueOrig) ); $startIndexOffset += \strlen($inner->value) - \strlen($innerValueOrig); } } $type = $value === $this->value ? $this : $this->inner($value); return $callback($type); } /** * @param \Closure(self): void $callback */ public function walkTypes(\Closure $callback): void { $this->mapTypes(static function (self $type) use ($callback) { $valueOrig = $type->value; $callback($type); \assert($type->value === $valueOrig); return $type; }); } /** * @param \Closure(self, self): (-1|0|1) $compareCallback */ public function sortTypes(\Closure $compareCallback): self { return $this->mapTypes(function (self $type) use ($compareCallback): self { if ($type->isCompositeType) { $innerTypeExpressions = Utils::stableSort( $type->innerTypeExpressions, static fn (array $v): self => $v['expression'], $compareCallback, ); if ($innerTypeExpressions !== $type->innerTypeExpressions) { $value = implode( $type->getTypesGlue(), array_map(static fn (array $v): string => $v['expression']->toString(), $innerTypeExpressions) ); return $this->inner($value); } } return $type; }); } public function getCommonType(): ?string { $mainType = null; foreach ($this->getTypes() as $type) { if ('null' === $type) { continue; } if (str_starts_with($type, '?')) { $type = substr($type, 1); } if (Preg::match('/\[\h*\]$/', $type)) { $type = 'array'; } elseif (Preg::match('/^(.+?)\h*[<{(]/', $type, $matches)) { $type = $matches[1]; } if (isset(self::ALIASES[$type])) { $type = self::ALIASES[$type]; } if (null === $mainType || $type === $mainType) { $mainType = $type; continue; } $mainType = $this->getParentType($type, $mainType); if (null === $mainType) { return null; } } return $mainType; } public function allowsNull(): bool { foreach ($this->getTypes() as $type) { if (\in_array($type, ['null', 'mixed'], true) || str_starts_with($type, '?')) { return true; } } return false; } private function parse(): void { $seenGlues = null; $innerValues = []; $index = 0; while (true) { Preg::match( '{\G'.self::REGEX_TYPE.'(?\h*(?[|&])\h*(?!$)|$)}', $this->value, $matches, \PREG_OFFSET_CAPTURE, $index ); if ([] === $matches) { throw new \Exception('Unable to parse phpdoc type '.var_export($this->value, true)); } if (null === $seenGlues) { if (($matches['glue'][0] ?? '') === '') { break; } $seenGlues = ['|' => false, '&' => false]; } if (($matches['glue'][0] ?? '') !== '') { \assert(isset($seenGlues[$matches['glue'][0]])); $seenGlues[$matches['glue'][0]] = true; } $innerValues[] = [ 'start_index' => $index, 'value' => $matches['type'][0], 'next_glue' => $matches['glue'][0] ?? null, 'next_glue_raw' => $matches['glue_raw'][0] ?? null, ]; $consumedValueLength = \strlen($matches[0][0]); $index += $consumedValueLength; if (\strlen($this->value) <= $index) { \assert(\strlen($this->value) === $index); $seenGlues = array_filter($seenGlues); \assert([] !== $seenGlues); $this->isCompositeType = true; $this->typesGlue = array_key_first($seenGlues); if (1 === \count($seenGlues)) { foreach ($innerValues as $innerValue) { $this->innerTypeExpressions[] = [ 'start_index' => $innerValue['start_index'], 'expression' => $this->inner($innerValue['value']), ]; } } else { for ($i = 0; $i < \count($innerValues); ++$i) { $innerStartIndex = $innerValues[$i]['start_index']; $innerValue = ''; while (true) { $innerValue .= $innerValues[$i]['value']; if (($innerValues[$i]['next_glue'] ?? $this->typesGlue) === $this->typesGlue) { break; } $innerValue .= $innerValues[$i]['next_glue_raw']; ++$i; } $this->innerTypeExpressions[] = [ 'start_index' => $innerStartIndex, 'expression' => $this->inner($innerValue), ]; } } return; } } $this->isCompositeType = false; if ('' !== $matches['nullable'][0]) { $this->innerTypeExpressions[] = [ 'start_index' => \strlen($matches['nullable'][0]), 'expression' => $this->inner(substr($matches['type'][0], \strlen($matches['nullable'][0]))), ]; } elseif ('' !== $matches['array'][0]) { $this->innerTypeExpressions[] = [ 'start_index' => 0, 'expression' => $this->inner(substr($matches['type'][0], 0, -\strlen($matches['array'][0]))), ]; } elseif ('' !== ($matches['generic'][0] ?? '') && 0 === $matches['generic'][1]) { $this->innerTypeExpressions[] = [ 'start_index' => 0, 'expression' => $this->inner($matches['generic_name'][0]), ]; $this->parseCommaSeparatedInnerTypes( \strlen($matches['generic_name'][0]) + \strlen($matches['generic_start'][0]), $matches['generic_types'][0] ); } elseif ('' !== ($matches['callable'][0] ?? '') && 0 === $matches['callable'][1]) { $this->innerTypeExpressions[] = [ 'start_index' => 0, 'expression' => $this->inner($matches['callable_name'][0]), ]; $this->parseCallableTemplateInnerTypes( \strlen($matches['callable_name'][0]) + \strlen($matches['callable_template_start'][0]), $matches['callable_template_inners'][0] ); $this->parseCallableArgumentTypes( \strlen($matches['callable_name'][0]) + \strlen($matches['callable_template'][0]) + \strlen($matches['callable_start'][0]), $matches['callable_arguments'][0] ); if ('' !== ($matches['callable_return'][0] ?? '')) { $this->innerTypeExpressions[] = [ 'start_index' => \strlen($this->value) - \strlen($matches['callable_return'][0]), 'expression' => $this->inner($matches['callable_return'][0]), ]; } } elseif ('' !== ($matches['array_shape'][0] ?? '') && 0 === $matches['array_shape'][1]) { $this->innerTypeExpressions[] = [ 'start_index' => 0, 'expression' => $this->inner($matches['array_shape_name'][0]), ]; $nextIndex = \strlen($matches['array_shape_name'][0]) + \strlen($matches['array_shape_start'][0]); $this->parseArrayShapeInnerTypes( $nextIndex, $matches['array_shape_inners'][0] ); if ('' !== ($matches['array_shape_unsealed_type'][0] ?? '')) { $nextIndex += \strlen($matches['array_shape_inners'][0]) + \strlen($matches['array_shape_unsealed_variadic'][0]) + \strlen($matches['array_shape_unsealed_type_start'][0]); $this->innerTypeExpressions[] = [ 'start_index' => $nextIndex, 'expression' => $this->inner($matches['array_shape_unsealed_type_a'][0]), ]; if ('' !== ($matches['array_shape_unsealed_type_b'][0] ?? '')) { $nextIndex += \strlen($matches['array_shape_unsealed_type_a'][0]) + \strlen($matches['array_shape_unsealed_type_comma'][0]); $this->innerTypeExpressions[] = [ 'start_index' => $nextIndex, 'expression' => $this->inner($matches['array_shape_unsealed_type_b'][0]), ]; } } } elseif ('' !== ($matches['parenthesized'][0] ?? '') && 0 === $matches['parenthesized'][1]) { $index = \strlen($matches['parenthesized_start'][0]); if ('' !== ($matches['conditional'][0] ?? '')) { if ('' !== ($matches['conditional_cond_left_types'][0] ?? '')) { $this->innerTypeExpressions[] = [ 'start_index' => $index, 'expression' => $this->inner($matches['conditional_cond_left_types'][0]), ]; } $index += \strlen($matches['conditional_cond_left'][0]) + \strlen($matches['conditional_cond_middle'][0]); $this->innerTypeExpressions[] = [ 'start_index' => $index, 'expression' => $this->inner($matches['conditional_cond_right_types'][0]), ]; $index += \strlen($matches['conditional_cond_right_types'][0]) + \strlen($matches['conditional_true_start'][0]); $this->innerTypeExpressions[] = [ 'start_index' => $index, 'expression' => $this->inner($matches['conditional_true_types'][0]), ]; $index += \strlen($matches['conditional_true_types'][0]) + \strlen($matches['conditional_false_start'][0]); $this->innerTypeExpressions[] = [ 'start_index' => $index, 'expression' => $this->inner($matches['conditional_false_types'][0]), ]; } else { $this->innerTypeExpressions[] = [ 'start_index' => $index, 'expression' => $this->inner($matches['parenthesized_types'][0]), ]; } } elseif ('' !== $matches['class_constant'][0]) { $this->innerTypeExpressions[] = [ 'start_index' => 0, 'expression' => $this->inner($matches['class_constant_name'][0]), ]; } } private function parseCommaSeparatedInnerTypes(int $startIndex, string $value): void { $index = 0; while (\strlen($value) !== $index) { Preg::match( '{\G'.self::REGEX_TYPES.'(?:\h*,[\h\v*]*|$)}', $value, $matches, 0, $index ); $this->innerTypeExpressions[] = [ 'start_index' => $startIndex + $index, 'expression' => $this->inner($matches['types']), ]; $index += \strlen($matches[0]); } } private function parseCallableTemplateInnerTypes(int $startIndex, string $value): void { $index = 0; while (\strlen($value) !== $index) { Preg::match( '{\G(?:(?=1)0'.self::REGEX_TYPES.'|(?<_callable_template_inner>(?&callable_template_inner))(?:\h*,\h*|$))}', $value, $prematches, 0, $index ); $consumedValue = $prematches['_callable_template_inner']; $consumedValueLength = \strlen($consumedValue); $consumedCommaLength = \strlen($prematches[0]) - $consumedValueLength; $addedPrefix = 'Closure<'; Preg::match( '{^'.self::REGEX_TYPES.'$}', $addedPrefix.$consumedValue.'>(): void', $matches, \PREG_OFFSET_CAPTURE ); if ('' !== $matches['callable_template_inner_b'][0]) { $this->innerTypeExpressions[] = [ 'start_index' => $startIndex + $index + $matches['callable_template_inner_b_types'][1] - \strlen($addedPrefix), 'expression' => $this->inner($matches['callable_template_inner_b_types'][0]), ]; } if ('' !== $matches['callable_template_inner_d'][0]) { $this->innerTypeExpressions[] = [ 'start_index' => $startIndex + $index + $matches['callable_template_inner_d_types'][1] - \strlen($addedPrefix), 'expression' => $this->inner($matches['callable_template_inner_d_types'][0]), ]; } $index += $consumedValueLength + $consumedCommaLength; } } private function parseCallableArgumentTypes(int $startIndex, string $value): void { $index = 0; while (\strlen($value) !== $index) { Preg::match( '{\G(?:(?=1)0'.self::REGEX_TYPES.'|(?<_callable_argument>(?&callable_argument))(?:\h*,\h*|$))}', $value, $prematches, 0, $index ); $consumedValue = $prematches['_callable_argument']; $consumedValueLength = \strlen($consumedValue); $consumedCommaLength = \strlen($prematches[0]) - $consumedValueLength; $addedPrefix = 'Closure('; Preg::match( '{^'.self::REGEX_TYPES.'$}', $addedPrefix.$consumedValue.'): void', $matches, \PREG_OFFSET_CAPTURE ); $this->innerTypeExpressions[] = [ 'start_index' => $startIndex + $index, 'expression' => $this->inner($matches['callable_argument_type'][0]), ]; $index += $consumedValueLength + $consumedCommaLength; } } private function parseArrayShapeInnerTypes(int $startIndex, string $value): void { $index = 0; while (\strlen($value) !== $index) { Preg::match( '{\G(?:(?=1)0'.self::REGEX_TYPES.'|(?<_array_shape_inner>(?&array_shape_inner))(?:\h*,[\h\v*]*|$))}', $value, $prematches, 0, $index ); $consumedValue = $prematches['_array_shape_inner']; $consumedValueLength = \strlen($consumedValue); $consumedCommaLength = \strlen($prematches[0]) - $consumedValueLength; $addedPrefix = 'array{'; Preg::match( '{^'.self::REGEX_TYPES.'$}', $addedPrefix.$consumedValue.'}', $matches, \PREG_OFFSET_CAPTURE ); $this->innerTypeExpressions[] = [ 'start_index' => $startIndex + $index + $matches['array_shape_inner_value'][1] - \strlen($addedPrefix), 'expression' => $this->inner($matches['array_shape_inner_value'][0]), ]; $index += $consumedValueLength + $consumedCommaLength; } } private function inner(string $value): self { return new self($value, $this->namespace, $this->namespaceUses); } private function getParentType(string $type1, string $type2): ?string { $types = [ $this->normalize($type1), $this->normalize($type2), ]; natcasesort($types); $types = implode('|', $types); $parents = [ 'array|Traversable' => 'iterable', 'array|iterable' => 'iterable', 'iterable|Traversable' => 'iterable', 'self|static' => 'self', ]; return $parents[$types] ?? null; } private function normalize(string $type): string { if (isset(self::ALIASES[$type])) { return self::ALIASES[$type]; } if (\in_array($type, [ 'array', 'bool', 'callable', 'false', 'float', 'int', 'iterable', 'mixed', 'never', 'null', 'object', 'resource', 'string', 'true', 'void', ], true)) { return $type; } if (Preg::match('/\[\]$/', $type)) { return 'array'; } if (Preg::match('/^(.+?)namespaceUses as $namespaceUse) { if ($namespaceUse->getShortName() === $type) { return $namespaceUse->getFullName(); } } if (null === $this->namespace || $this->namespace->isGlobalNamespace()) { return $type; } return "{$this->namespace->getFullName()}\\{$type}"; } }