'int', 'boolean' => 'bool', ]; return array_key_exists($typeHint, $longToShort) ? $longToShort[$typeHint] : $typeHint; } public static function isUnofficialUnionTypeHint(string $typeHint): bool { return in_array($typeHint, ['scalar', 'numeric', 'array-key'], true); } public static function isVoidTypeHint(string $typeHint): bool { return $typeHint === 'void'; } public static function isNeverTypeHint(string $typeHint): bool { return in_array($typeHint, ['never', 'never-return', 'never-returns', 'no-return'], true); } /** * @return list */ public static function convertUnofficialUnionTypeHintToOfficialTypeHints(string $typeHint): array { $conversion = [ 'scalar' => ['string', 'int', 'float', 'bool'], 'numeric' => ['int', 'float', 'string'], 'array-key' => ['int', 'string'], ]; return $conversion[$typeHint]; } public static function isTypeDefinedInAnnotation(File $phpcsFile, int $pointer, string $typeHint): bool { $docCommentOpenPointer = DocCommentHelper::findDocCommentOpenPointer($phpcsFile, $pointer); if ($docCommentOpenPointer === null) { return false; } return self::isTemplate($phpcsFile, $docCommentOpenPointer, $typeHint) || self::isAlias($phpcsFile, $docCommentOpenPointer, $typeHint); } public static function getFullyQualifiedTypeHint(File $phpcsFile, int $pointer, string $typeHint): string { if (self::isSimpleTypeHint($typeHint)) { return self::convertLongSimpleTypeHintToShort($typeHint); } return NamespaceHelper::resolveClassName($phpcsFile, $typeHint, $pointer); } /** * @return list */ public static function getSimpleTypeHints(): array { static $simpleTypeHints; $simpleTypeHints ??= [ 'int', 'integer', 'false', 'float', 'string', 'bool', 'boolean', 'callable', 'self', 'array', 'iterable', 'void', 'never', ]; return $simpleTypeHints; } /** * @return list */ public static function getSimpleIterableTypeHints(): array { return [ 'array', 'iterable', ]; } public static function isSimpleUnofficialTypeHints(string $typeHint): bool { static $simpleUnofficialTypeHints; // See https://psalm.dev/docs/annotating_code/type_syntax/atomic_types/ $simpleUnofficialTypeHints ??= [ 'null', 'mixed', 'scalar', 'numeric', 'true', 'object', 'resource', 'static', '$this', 'array-key', 'list', 'non-empty-array', 'non-empty-list', 'empty', 'positive-int', 'non-positive-int', 'negative-int', 'non-negative-int', 'literal-int', 'int-mask', 'min', 'max', 'callable-array', 'callable-string', ]; return in_array($typeHint, $simpleUnofficialTypeHints, true) || preg_match('~-string$~i', $typeHint) === 1; } /** * @param list $traversableTypeHints */ public static function isTraversableType(string $type, array $traversableTypeHints): bool { return self::isSimpleIterableTypeHint($type) || in_array($type, $traversableTypeHints, true); } public static function typeHintEqualsAnnotation( File $phpcsFile, int $functionPointer, string $typeHint, string $typeHintInAnnotation ): bool { /** @var list $typeHintParts */ $typeHintParts = preg_split('~([&|])~', self::normalize($typeHint), -1, PREG_SPLIT_DELIM_CAPTURE); /** @var list $typeHintInAnnotationParts */ $typeHintInAnnotationParts = preg_split('~([&|])~', self::normalize($typeHintInAnnotation), -1, PREG_SPLIT_DELIM_CAPTURE); if (count($typeHintParts) !== count($typeHintInAnnotationParts)) { return false; } for ($i = 0; $i < count($typeHintParts); $i++) { if ( ( $typeHintParts[$i] === '|' || $typeHintParts[$i] === '&' ) && $typeHintParts[$i] !== $typeHintInAnnotationParts[$i] ) { return false; } if (self::getFullyQualifiedTypeHint($phpcsFile, $functionPointer, $typeHintParts[$i]) !== self::getFullyQualifiedTypeHint( $phpcsFile, $functionPointer, $typeHintInAnnotationParts[$i], )) { return false; } } return true; } public static function getStartPointer(File $phpcsFile, int $endPointer): int { $previousPointer = TokenHelper::findPreviousExcluding( $phpcsFile, [T_WHITESPACE, ...TokenHelper::TYPE_HINT_TOKEN_CODES], $endPointer - 1, ); return TokenHelper::findNextNonWhitespace($phpcsFile, $previousPointer + 1); } private static function isTemplate(File $phpcsFile, int $docCommentOpenPointer, string $typeHint): bool { static $templateAnnotationNames = null; if ($templateAnnotationNames === null) { foreach (['template', 'template-covariant'] as $annotationName) { $templateAnnotationNames[] = sprintf('@%s', $annotationName); foreach (AnnotationHelper::STATIC_ANALYSIS_PREFIXES as $prefixAnnotationName) { $templateAnnotationNames[] = sprintf('@%s-%s', $prefixAnnotationName, $annotationName); } } } $containsTypeHintInTemplateAnnotation = static function (int $docCommentOpenPointer) use ($phpcsFile, $templateAnnotationNames, $typeHint): bool { foreach ($templateAnnotationNames as $templateAnnotationName) { /** @var list> $annotations */ $annotations = AnnotationHelper::getAnnotations($phpcsFile, $docCommentOpenPointer, $templateAnnotationName); foreach ($annotations as $templateAnnotation) { if ($templateAnnotation->isInvalid()) { continue; } if ($templateAnnotation->getValue()->name === $typeHint) { return true; } } } return false; }; $tokens = $phpcsFile->getTokens(); $docCommentOwnerPointer = DocCommentHelper::findDocCommentOwnerPointer($phpcsFile, $docCommentOpenPointer); if ($docCommentOwnerPointer !== null) { if (in_array($tokens[$docCommentOwnerPointer]['code'], TokenHelper::CLASS_TYPE_TOKEN_CODES, true)) { return $containsTypeHintInTemplateAnnotation($docCommentOpenPointer); } if ($tokens[$docCommentOwnerPointer]['code'] === T_FUNCTION && $containsTypeHintInTemplateAnnotation($docCommentOpenPointer)) { return true; } } $classPointer = ClassHelper::getClassPointer($phpcsFile, $docCommentOpenPointer); if ($classPointer === null) { return false; } $classDocCommentOpenPointer = DocCommentHelper::findDocCommentOpenPointer($phpcsFile, $classPointer); if ($classDocCommentOpenPointer === null) { return false; } return $containsTypeHintInTemplateAnnotation($classDocCommentOpenPointer); } private static function isAlias(File $phpcsFile, int $docCommentOpenPointer, string $typeHint): bool { static $aliasAnnotationNames = null; if ($aliasAnnotationNames === null) { foreach (['type', 'import-type'] as $annotationName) { foreach (AnnotationHelper::STATIC_ANALYSIS_PREFIXES as $prefixAnnotationName) { $aliasAnnotationNames[] = sprintf('@%s-%s', $prefixAnnotationName, $annotationName); } } } $classPointer = ClassHelper::getClassPointer($phpcsFile, $docCommentOpenPointer); if ($classPointer === null) { return false; } $classDocCommentOpenPointer = DocCommentHelper::findDocCommentOpenPointer($phpcsFile, $classPointer); if ($classDocCommentOpenPointer === null) { return false; } foreach ($aliasAnnotationNames as $aliasAnnotationName) { $annotations = AnnotationHelper::getAnnotations($phpcsFile, $classDocCommentOpenPointer, $aliasAnnotationName); foreach ($annotations as $aliasAnnotation) { $aliasAnnotationValue = $aliasAnnotation->getValue(); if ($aliasAnnotationValue instanceof TypeAliasTagValueNode && $aliasAnnotationValue->alias === $typeHint) { return true; } if (!($aliasAnnotationValue instanceof TypeAliasImportTagValueNode)) { continue; } if ($aliasAnnotationValue->importedAs === $typeHint) { return true; } if ($aliasAnnotationValue->importedAlias === $typeHint) { return true; } } } return false; } private static function normalize(string $typeHint): string { if (StringHelper::startsWith($typeHint, '?')) { $typeHint = substr($typeHint, 1) . '|null'; } if (self::isNeverTypeHint($typeHint)) { return 'never'; } /** @var list $parts */ $parts = preg_split('~([&|])~', $typeHint, -1, PREG_SPLIT_DELIM_CAPTURE); $hints = []; $delimiter = '|'; foreach ($parts as $part) { if ($part === '|' || $part === '&') { $delimiter = $part; continue; } $hints[] = $part; } if (in_array('mixed', $hints, true)) { return 'mixed'; } $convertedHints = []; foreach ($hints as $hint) { if (self::isUnofficialUnionTypeHint($hint) && $delimiter !== '&') { $convertedHints = array_merge($convertedHints, self::convertUnofficialUnionTypeHintToOfficialTypeHints($hint)); } else { $convertedHints[] = $hint; } } $convertedHints = array_unique($convertedHints); if (count($convertedHints) > 1) { $convertedHints = array_map(static fn (string $part): string => self::isVoidTypeHint($part) ? 'null' : $part, $convertedHints); } sort($convertedHints); return implode($delimiter, $convertedHints); } }