1
0
mirror of https://github.com/danog/psalm.git synced 2024-12-12 01:09:38 +01:00
psalm/src/Psalm/Internal/Analyzer/CommentAnalyzer.php

1218 lines
46 KiB
PHP
Raw Normal View History

2016-06-24 00:45:46 +02:00
<?php
2018-11-06 03:57:36 +01:00
namespace Psalm\Internal\Analyzer;
use PhpParser;
Refactor scanning and analysis, introducing multithreading (#191) * Add failing test * Add visitor to soup up classlike references * Move a whole bunch of code into the visitor * Move some methods back, move onto analysis stage * Use the getAliases method everywhere * Fix refs * Fix more refs * Fix some tests * Fix more tests * Fix include tests * Shift config class finding to project checker and fix bugs * Fix a few more tests * transition test to new syntax * Remove var_dump * Delete a bunch of code and fix mutation test * Remove unnecessary visitation * Transition to better mocked out file provider, breaking some cached statement loading * Use different scheme for naming anonymous classes * Fix anonymous class issues * Refactor file/statement loading * Add specific property types * Fix mapped property assignment * Improve how we deal with traits * Fix trait checking * Pass Psalm checks * Add multi-process support * Delay console output until the end * Remove PHP 7 syntax * Update file storage with classes * Fix scanning individual files and add reflection return types * Always turn XDebug off * Add quicker method of getting method mutations * Queue return types for crawling * Interpret all strings as possible classes once we see a `get_class` call * Check invalid return types again * Fix template namespacing issues * Default to class-insensitive file names for includes * Don’t overwrite existing issues data * Add var docblocks for scanning * Add null check * Fix loading of external classes in templates * Only try to populate class when we haven’t yet seen it’s not a class * Fix trait property accessibility * Only ever improve docblock param type * Make param replacement more robust * Fix static const missing inferred type * Fix a few more tests * Register constant definitions * Fix trait aliasing * Skip constant type tests for now * Fix linting issues * Make sure caching is off for tests * Remove unnecessary return * Use emulative parser if on PHP 5.6 * Cache parser for faster first-time parse * Fix constant resolution when scanning classes * Remove test that’s beyond a practical scope * Add back --diff support * Add --help for --threads * Remove unused vars
2017-07-25 22:11:02 +02:00
use Psalm\Aliases;
2018-11-06 03:57:36 +01:00
use Psalm\DocComment;
2016-11-02 07:29:00 +01:00
use Psalm\Exception\DocblockParseException;
use Psalm\Exception\IncorrectDocblockException;
use Psalm\Exception\TypeParseTreeException;
2018-01-21 18:44:46 +01:00
use Psalm\FileSource;
2018-11-06 03:57:36 +01:00
use Psalm\Internal\Scanner\ClassLikeDocblockComment;
use Psalm\Internal\Scanner\FunctionDocblockComment;
use Psalm\Internal\Scanner\VarDocblockComment;
use Psalm\Internal\Type\ParseTree;
use Psalm\Type;
use function trim;
use function substr_count;
use function strlen;
use function preg_replace;
use function str_replace;
use function preg_match;
use function count;
use function reset;
use function preg_split;
use const PREG_SPLIT_DELIM_CAPTURE;
use const PREG_SPLIT_NO_EMPTY;
use function array_shift;
use function implode;
use function substr;
use function strpos;
use function strtolower;
use function in_array;
use function explode;
use function array_merge;
use const PREG_OFFSET_CAPTURE;
use function rtrim;
2016-06-24 00:45:46 +02:00
/**
* @internal
*/
2018-11-06 03:57:36 +01:00
class CommentAnalyzer
2016-06-24 00:45:46 +02:00
{
const TYPE_REGEX = '(\??\\\?[\(\)A-Za-z0-9_&\<\.=,\>\[\]\-\{\}:|?\\\\]*|\$[a-zA-Z_0-9_]+)';
2016-06-24 00:45:46 +02:00
/**
* @param array<string, array<string, array{Type\Union}>>|null $template_type_map
* @param array<string, array<int, array{0: string, 1: int}>> $type_aliases
2017-05-27 02:16:18 +02:00
*
* @throws DocblockParseException if there was a problem parsing the docblock
*
* @return VarDocblockComment[]
2016-06-24 00:45:46 +02:00
*/
2016-11-02 07:29:00 +01:00
public static function getTypeFromComment(
PhpParser\Comment\Doc $comment,
2018-01-21 18:44:46 +01:00
FileSource $source,
Refactor scanning and analysis, introducing multithreading (#191) * Add failing test * Add visitor to soup up classlike references * Move a whole bunch of code into the visitor * Move some methods back, move onto analysis stage * Use the getAliases method everywhere * Fix refs * Fix more refs * Fix some tests * Fix more tests * Fix include tests * Shift config class finding to project checker and fix bugs * Fix a few more tests * transition test to new syntax * Remove var_dump * Delete a bunch of code and fix mutation test * Remove unnecessary visitation * Transition to better mocked out file provider, breaking some cached statement loading * Use different scheme for naming anonymous classes * Fix anonymous class issues * Refactor file/statement loading * Add specific property types * Fix mapped property assignment * Improve how we deal with traits * Fix trait checking * Pass Psalm checks * Add multi-process support * Delay console output until the end * Remove PHP 7 syntax * Update file storage with classes * Fix scanning individual files and add reflection return types * Always turn XDebug off * Add quicker method of getting method mutations * Queue return types for crawling * Interpret all strings as possible classes once we see a `get_class` call * Check invalid return types again * Fix template namespacing issues * Default to class-insensitive file names for includes * Don’t overwrite existing issues data * Add var docblocks for scanning * Add null check * Fix loading of external classes in templates * Only try to populate class when we haven’t yet seen it’s not a class * Fix trait property accessibility * Only ever improve docblock param type * Make param replacement more robust * Fix static const missing inferred type * Fix a few more tests * Register constant definitions * Fix trait aliasing * Skip constant type tests for now * Fix linting issues * Make sure caching is off for tests * Remove unnecessary return * Use emulative parser if on PHP 5.6 * Cache parser for faster first-time parse * Fix constant resolution when scanning classes * Remove test that’s beyond a practical scope * Add back --diff support * Add --help for --threads * Remove unused vars
2017-07-25 22:11:02 +02:00
Aliases $aliases,
array $template_type_map = null,
2019-06-01 18:25:57 +02:00
?array $type_aliases = null
2016-11-02 07:29:00 +01:00
) {
$parsed_docblock = DocComment::parsePreservingLength($comment);
return self::arrayToDocblocks(
$comment,
$parsed_docblock,
$source,
$aliases,
$template_type_map,
$type_aliases
);
}
/**
* @param array<string, array<string, array{Type\Union}>>|null $template_type_map
* @param array<string, array<int, array{0: string, 1: int}>> $type_aliases
* @param array{description:string, specials:array<string, array<int, string>>} $parsed_docblock
*
* @return VarDocblockComment[]
*
* @throws DocblockParseException if there was a problem parsing the docblock
*/
public static function arrayToDocblocks(
PhpParser\Comment\Doc $comment,
array $parsed_docblock,
FileSource $source,
Aliases $aliases,
array $template_type_map = null,
?array $type_aliases = null
) : array {
$var_id = null;
2016-06-24 00:45:46 +02:00
2018-05-20 23:19:53 +02:00
$var_type_tokens = null;
$original_type = null;
2016-06-24 00:45:46 +02:00
$var_comments = [];
2016-06-24 00:45:46 +02:00
2019-06-01 22:57:33 +02:00
$comment_text = $comment->getText();
$var_line_number = $comment->getLine();
if ($parsed_docblock) {
$all_vars = (isset($parsed_docblock['specials']['var']) ? $parsed_docblock['specials']['var'] : [])
+ (isset($parsed_docblock['specials']['psalm-var']) ? $parsed_docblock['specials']['psalm-var'] : []);
2019-06-01 22:57:33 +02:00
foreach ($all_vars as $offset => $var_line) {
2017-03-02 04:27:52 +01:00
$var_line = trim($var_line);
2016-06-24 00:45:46 +02:00
2017-03-02 04:27:52 +01:00
if (!$var_line) {
continue;
}
2019-06-01 18:25:57 +02:00
$type_start = null;
$type_end = null;
$line_parts = self::splitDocLine($var_line);
2017-03-02 04:27:52 +01:00
2019-06-01 22:57:33 +02:00
$line_number = $comment->getLine() + substr_count($comment_text, "\n", 0, $offset);
2017-03-02 04:27:52 +01:00
if ($line_parts && $line_parts[0]) {
$type_start = $offset + $comment->getFilePos();
$type_end = $type_start + strlen($line_parts[0]);
$line_parts[0] = preg_replace('@^[ \t]*\*@m', '', $line_parts[0]);
$line_parts[0] = preg_replace('/,\n\s+\}/', '}', $line_parts[0]);
$line_parts[0] = str_replace("\n", '', $line_parts[0]);
if ($line_parts[0] === ''
|| ($line_parts[0][0] === '$'
&& !preg_match('/^\$this(\||$)/', $line_parts[0]))
) {
throw new IncorrectDocblockException('Misplaced variable');
}
try {
2018-05-20 23:19:53 +02:00
$var_type_tokens = Type::fixUpLocalType(
$line_parts[0],
$aliases,
$template_type_map,
2018-07-15 23:23:17 +02:00
$type_aliases
);
} catch (TypeParseTreeException $e) {
throw new DocblockParseException($line_parts[0] . ' is not a valid type');
}
2017-03-02 04:27:52 +01:00
$original_type = $line_parts[0];
2017-03-02 04:27:52 +01:00
$var_line_number = $line_number;
if (count($line_parts) > 1 && $line_parts[1][0] === '$') {
$var_id = $line_parts[1];
2017-03-02 04:27:52 +01:00
}
}
2017-03-02 04:27:52 +01:00
2018-05-20 23:19:53 +02:00
if (!$var_type_tokens || !$original_type) {
continue;
2016-06-24 00:45:46 +02:00
}
try {
$defined_type = Type::parseTokens($var_type_tokens, null, $template_type_map ?: []);
} catch (TypeParseTreeException $e) {
throw new DocblockParseException(
$line_parts[0] .
' is not a valid type' .
' (from ' .
$source->getFilePath() .
':' .
$comment->getLine() .
')'
);
}
$defined_type->setFromDocblock();
2016-06-24 00:45:46 +02:00
$var_comment = new VarDocblockComment();
$var_comment->type = $defined_type;
$var_comment->original_type = $original_type;
$var_comment->var_id = $var_id;
$var_comment->line_number = $var_line_number;
2019-06-01 18:25:57 +02:00
$var_comment->type_start = $type_start;
$var_comment->type_end = $type_end;
$var_comment->deprecated = isset($parsed_docblock['specials']['deprecated']);
$var_comment->internal = isset($parsed_docblock['specials']['internal']);
2019-09-08 21:12:30 +02:00
$var_comment->readonly = isset($parsed_docblock['specials']['readonly'])
|| isset($parsed_docblock['specials']['psalm-readonly']);
$var_comment->remove_taint = isset($parsed_docblock['specials']['psalm-remove-taint']);
if (isset($parsed_docblock['specials']['psalm-internal'])) {
$psalm_internal = reset($parsed_docblock['specials']['psalm-internal']);
if ($psalm_internal) {
$var_comment->psalm_internal = $psalm_internal;
} else {
throw new DocblockParseException('psalm-internal annotation used without specifying namespace');
}
$var_comment->psalm_internal = reset($parsed_docblock['specials']['psalm-internal']);
if (!$var_comment->internal) {
throw new DocblockParseException('@psalm-internal annotation used without @internal');
}
}
$var_comments[] = $var_comment;
}
}
2016-06-24 00:45:46 +02:00
2019-08-11 22:01:37 +02:00
if (!$var_comments
&& (isset($parsed_docblock['specials']['deprecated'])
|| isset($parsed_docblock['specials']['internal'])
2019-09-08 21:12:30 +02:00
|| isset($parsed_docblock['specials']['readonly'])
|| isset($parsed_docblock['specials']['psalm-readonly'])
|| isset($parsed_docblock['specials']['psalm-remove-taint']))
2019-08-11 22:01:37 +02:00
) {
$var_comment = new VarDocblockComment();
$var_comment->deprecated = isset($parsed_docblock['specials']['deprecated']);
$var_comment->internal = isset($parsed_docblock['specials']['internal']);
2019-09-08 21:12:30 +02:00
$var_comment->readonly = isset($parsed_docblock['specials']['readonly'])
|| isset($parsed_docblock['specials']['psalm-readonly']);
$var_comment->remove_taint = isset($parsed_docblock['specials']['psalm-remove-taint']);
2019-08-11 22:01:37 +02:00
$var_comments[] = $var_comment;
}
return $var_comments;
2016-06-24 00:45:46 +02:00
}
2018-07-15 23:23:17 +02:00
/**
* @param Aliases $aliases
* @param array<string, array<int, array{0: string, 1: int}>> $type_aliases
2018-07-15 23:23:17 +02:00
*
* @throws DocblockParseException if there was a problem parsing the docblock
*
2019-11-21 17:03:18 +01:00
* @return array<string, list<array{0: string, 1: int}>>
2018-07-15 23:23:17 +02:00
*/
public static function getTypeAliasesFromComment(
PhpParser\Comment\Doc $comment,
2018-07-15 23:23:17 +02:00
Aliases $aliases,
array $type_aliases = null
) {
$parsed_docblock = DocComment::parsePreservingLength($comment);
2018-07-15 23:23:17 +02:00
if (!isset($parsed_docblock['specials']['psalm-type'])) {
2018-07-15 23:23:17 +02:00
return [];
}
return self::getTypeAliasesFromCommentLines(
$parsed_docblock['specials']['psalm-type'],
2018-07-15 23:23:17 +02:00
$aliases,
$type_aliases
);
}
/**
* @param array<string> $type_alias_comment_lines
* @param Aliases $aliases
* @param array<string, array<int, array{0: string, 1: int}>> $type_aliases
2018-07-15 23:23:17 +02:00
*
* @throws DocblockParseException if there was a problem parsing the docblock
*
2019-11-21 17:03:18 +01:00
* @return array<string, list<array{0: string, 1: int}>>
2018-07-15 23:23:17 +02:00
*/
private static function getTypeAliasesFromCommentLines(
array $type_alias_comment_lines,
Aliases $aliases,
array $type_aliases = null
) {
$type_alias_tokens = [];
foreach ($type_alias_comment_lines as $var_line) {
$var_line = trim($var_line);
if (!$var_line) {
continue;
}
$var_line = preg_replace('/[ \t]+/', ' ', preg_replace('@^[ \t]*\*@m', '', $var_line));
2018-07-15 23:23:17 +02:00
$var_line_parts = preg_split('/( |=)/', $var_line, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
if (!$var_line_parts) {
continue;
}
2018-07-15 23:23:17 +02:00
$type_alias = array_shift($var_line_parts);
if (!isset($var_line_parts[0])) {
continue;
}
if ($var_line_parts[0] === ' ') {
array_shift($var_line_parts);
}
if ($var_line_parts[0] === '=') {
array_shift($var_line_parts);
}
if (!isset($var_line_parts[0])) {
continue;
}
if ($var_line_parts[0] === ' ') {
array_shift($var_line_parts);
}
2019-06-01 22:57:33 +02:00
$type_string = str_replace("\n", '', implode('', $var_line_parts));
2018-07-15 23:23:17 +02:00
2019-06-16 18:45:02 +02:00
$type_string = preg_replace('/>[^>^\}]*$/', '>', $type_string);
$type_string = preg_replace('/\}[^>^\}]*$/', '}', $type_string);
2018-07-15 23:23:17 +02:00
try {
$type_tokens = Type::fixUpLocalType(
$type_string,
$aliases,
null,
$type_alias_tokens + $type_aliases
2018-07-15 23:23:17 +02:00
);
} catch (TypeParseTreeException $e) {
throw new DocblockParseException($type_string . ' is not a valid type');
}
$type_alias_tokens[$type_alias] = $type_tokens;
}
return $type_alias_tokens;
}
2016-10-14 06:53:43 +02:00
/**
* @param int $line_number
2017-05-27 02:16:18 +02:00
*
* @throws DocblockParseException if there was a problem parsing the docblock
*
2016-11-13 05:59:31 +01:00
* @return FunctionDocblockComment
2016-10-14 06:53:43 +02:00
*/
public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $comment)
2018-07-22 04:55:16 +02:00
{
$parsed_docblock = DocComment::parsePreservingLength($comment);
2016-06-24 00:45:46 +02:00
2019-06-01 22:57:33 +02:00
$comment_text = $comment->getText();
2016-11-13 05:59:31 +01:00
$info = new FunctionDocblockComment();
2016-06-24 00:45:46 +02:00
if (isset($parsed_docblock['specials']['return']) || isset($parsed_docblock['specials']['psalm-return'])) {
$return_specials = isset($parsed_docblock['specials']['psalm-return'])
? $parsed_docblock['specials']['psalm-return']
: $parsed_docblock['specials']['return'];
self::extractReturnType(
$comment,
2019-06-01 22:57:33 +02:00
$return_specials,
$info
);
2016-06-24 00:45:46 +02:00
}
if (isset($parsed_docblock['specials']['param']) || isset($parsed_docblock['specials']['psalm-param'])) {
$all_params =
(isset($parsed_docblock['specials']['param'])
? $parsed_docblock['specials']['param']
: [])
+ (isset($parsed_docblock['specials']['psalm-param'])
? $parsed_docblock['specials']['psalm-param']
: []);
2019-06-01 22:57:33 +02:00
foreach ($all_params as $offset => $param) {
$line_parts = self::splitDocLine($param);
2016-06-24 00:45:46 +02:00
2017-05-30 05:21:46 +02:00
if (count($line_parts) === 1 && isset($line_parts[0][0]) && $line_parts[0][0] === '$') {
continue;
}
if (count($line_parts) > 1) {
if (preg_match('/^&?(\.\.\.)?&?\$[A-Za-z0-9_]+,?$/', $line_parts[1])
2017-01-15 16:58:44 +01:00
&& $line_parts[0][0] !== '{'
) {
$line_parts[1] = str_replace('&', '', $line_parts[1]);
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
2019-06-01 22:57:33 +02:00
$start = $offset + $comment->getFilePos();
$end = $start + strlen($line_parts[0]);
$line_parts[0] = preg_replace('@^[ \t]*\*@m', '', $line_parts[0]);
$line_parts[0] = preg_replace('/,\n\s+\}/', '}', $line_parts[0]);
$line_parts[0] = str_replace("\n", '', $line_parts[0]);
if ($line_parts[0] === ''
|| ($line_parts[0][0] === '$'
&& !preg_match('/^\$this(\||$)/', $line_parts[0]))
) {
throw new IncorrectDocblockException('Misplaced variable');
}
$info->params[] = [
2019-06-01 22:57:33 +02:00
'name' => trim($line_parts[1]),
'type' => $line_parts[0],
2019-06-01 22:57:33 +02:00
'line_number' => $comment->getLine() + substr_count($comment_text, "\n", 0, $offset),
'start' => $start,
'end' => $end,
];
2016-10-15 06:12:57 +02:00
}
} else {
throw new DocblockParseException('Badly-formatted @param');
2016-06-24 00:45:46 +02:00
}
}
}
if (isset($parsed_docblock['specials']['param-out'])) {
foreach ($parsed_docblock['specials']['param-out'] as $offset => $param) {
$line_parts = self::splitDocLine($param);
2019-01-19 19:32:43 +01:00
if (count($line_parts) === 1 && isset($line_parts[0][0]) && $line_parts[0][0] === '$') {
continue;
}
if (count($line_parts) > 1) {
if (!preg_match('/\[[^\]]+\]/', $line_parts[0])
&& preg_match('/^(\.\.\.)?&?\$[A-Za-z0-9_]+,?$/', $line_parts[1])
&& $line_parts[0][0] !== '{'
) {
if ($line_parts[1][0] === '&') {
$line_parts[1] = substr($line_parts[1], 1);
}
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
if ($line_parts[0] === ''
|| ($line_parts[0][0] === '$'
&& !preg_match('/^\$this(\||$)/', $line_parts[0]))
) {
2019-01-19 19:32:43 +01:00
throw new IncorrectDocblockException('Misplaced variable');
}
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
$info->params_out[] = [
2019-06-01 22:57:33 +02:00
'name' => trim($line_parts[1]),
'type' => str_replace("\n", '', $line_parts[0]),
'line_number' => $comment->getLine() + substr_count($comment_text, "\n", 0, $offset),
2019-01-19 19:32:43 +01:00
];
}
} else {
throw new DocblockParseException('Badly-formatted @param');
}
}
}
if (isset($parsed_docblock['specials']['psalm-taint-sink'])) {
foreach ($parsed_docblock['specials']['psalm-taint-sink'] as $param) {
$param = trim($param);
$info->taint_sink_params[] = ['name' => $param];
}
}
if (isset($parsed_docblock['specials']['psalm-assert-untainted'])) {
foreach ($parsed_docblock['specials']['psalm-assert-untainted'] as $param) {
$param = trim($param);
$info->assert_untainted_params[] = ['name' => $param];
}
}
if (isset($parsed_docblock['specials']['global'])) {
foreach ($parsed_docblock['specials']['global'] as $offset => $global) {
$line_parts = self::splitDocLine($global);
if (count($line_parts) === 1 && isset($line_parts[0][0]) && $line_parts[0][0] === '$') {
continue;
}
if (count($line_parts) > 1) {
if (!preg_match('/\[[^\]]+\]/', $line_parts[0])
&& preg_match('/^(\.\.\.)?&?\$[A-Za-z0-9_]+,?$/', $line_parts[1])
&& $line_parts[0][0] !== '{'
) {
if ($line_parts[1][0] === '&') {
$line_parts[1] = substr($line_parts[1], 1);
}
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
throw new IncorrectDocblockException('Misplaced variable');
}
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
$info->globals[] = [
'name' => $line_parts[1],
'type' => $line_parts[0],
2019-06-01 22:57:33 +02:00
'line_number' => $comment->getLine() + substr_count($comment_text, "\n", 0, $offset),
];
}
} else {
throw new DocblockParseException('Badly-formatted @param');
}
}
}
if (isset($parsed_docblock['specials']['deprecated'])) {
2016-11-13 05:59:31 +01:00
$info->deprecated = true;
}
if (isset($parsed_docblock['specials']['internal'])) {
$info->internal = true;
}
if (isset($parsed_docblock['specials']['psalm-internal'])) {
$psalm_internal = reset($parsed_docblock['specials']['psalm-internal']);
if ($psalm_internal) {
$info->psalm_internal = $psalm_internal;
} else {
throw new DocblockParseException('@psalm-internal annotation used without specifying namespace');
}
$info->psalm_internal = reset($parsed_docblock['specials']['psalm-internal']);
if (! $info->internal) {
throw new DocblockParseException('@psalm-internal annotation used without @internal');
}
}
if (isset($parsed_docblock['specials']['psalm-remove-taint'])) {
$info->remove_taint = true;
}
if (isset($parsed_docblock['specials']['psalm-suppress'])) {
foreach ($parsed_docblock['specials']['psalm-suppress'] as $offset => $suppress_entry) {
2019-08-18 20:27:50 +02:00
$info->suppressed_issues[$offset + $comment->getFilePos()] = preg_split('/[\s]+/', $suppress_entry)[0];
}
}
if (isset($parsed_docblock['specials']['throws'])) {
2019-08-13 21:44:18 +02:00
foreach ($parsed_docblock['specials']['throws'] as $offset => $throws_entry) {
$throws_class = preg_split('/[\s]+/', $throws_entry)[0];
if (!$throws_class) {
throw new IncorrectDocblockException('Unexpectedly empty @throws');
}
2019-08-13 21:44:18 +02:00
$info->throws[] = [
$throws_class,
$offset + $comment->getFilePos(),
$comment->getLine() + substr_count($comment->getText(), "\n", 0, $offset)
];
}
}
if (strpos(strtolower($parsed_docblock['description']), '@inheritdoc') !== false
|| isset($parsed_docblock['specials']['inheritdoc']) || isset($parsed_docblock['specials']['inheritDoc'])) {
2018-12-21 17:01:24 +01:00
$info->inheritdoc = true;
}
if (isset($parsed_docblock['specials']['template']) || isset($parsed_docblock['specials']['psalm-template'])) {
$all_templates
= (isset($parsed_docblock['specials']['template'])
? $parsed_docblock['specials']['template']
: [])
+ (isset($parsed_docblock['specials']['psalm-template'])
? $parsed_docblock['specials']['psalm-template']
: []);
2018-07-14 01:09:35 +02:00
foreach ($all_templates as $template_line) {
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
2017-02-10 02:35:17 +01:00
$template_name = array_shift($template_type);
if (!$template_name) {
throw new IncorrectDocblockException('Empty @template tag');
}
if (count($template_type) > 1
&& in_array(strtolower($template_type[0]), ['as', 'super', 'of'], true)
2019-01-16 15:23:18 +01:00
) {
$template_modifier = strtolower(array_shift($template_type));
$info->templates[] = [
$template_name,
$template_modifier,
implode(' ', $template_type),
false
];
2017-02-10 02:35:17 +01:00
} else {
$info->templates[] = [$template_name, null, null, false];
}
}
}
if (isset($parsed_docblock['specials']['template-typeof'])) {
foreach ($parsed_docblock['specials']['template-typeof'] as $template_typeof) {
$typeof_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_typeof));
2017-02-10 02:35:17 +01:00
if (count($typeof_parts) < 2 || $typeof_parts[1][0] !== '$') {
throw new IncorrectDocblockException('Misplaced variable');
2017-02-10 02:35:17 +01:00
}
$info->template_typeofs[] = [
'template_type' => $typeof_parts[0],
'param_name' => substr($typeof_parts[1], 1),
];
}
}
if (isset($parsed_docblock['specials']['psalm-assert'])) {
foreach ($parsed_docblock['specials']['psalm-assert'] as $assertion) {
2019-09-22 03:50:11 +02:00
$line_parts = self::splitDocLine($assertion);
2019-09-22 03:50:11 +02:00
if (count($line_parts) < 2 || $line_parts[1][0] !== '$') {
throw new IncorrectDocblockException('Misplaced variable');
}
$info->assertions[] = [
2019-09-22 03:50:11 +02:00
'type' => $line_parts[0],
'param_name' => substr($line_parts[1], 1),
];
}
}
if (isset($parsed_docblock['specials']['psalm-assert-if-true'])) {
foreach ($parsed_docblock['specials']['psalm-assert-if-true'] as $assertion) {
$assertion_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $assertion));
if (count($assertion_parts) < 2 || $assertion_parts[1][0] !== '$') {
throw new IncorrectDocblockException('Misplaced variable');
}
$info->if_true_assertions[] = [
'type' => $assertion_parts[0],
'param_name' => substr($assertion_parts[1], 1),
];
}
}
if (isset($parsed_docblock['specials']['psalm-assert-if-false'])) {
foreach ($parsed_docblock['specials']['psalm-assert-if-false'] as $assertion) {
$assertion_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $assertion));
if (count($assertion_parts) < 2 || $assertion_parts[1][0] !== '$') {
throw new IncorrectDocblockException('Misplaced variable');
}
$info->if_false_assertions[] = [
'type' => $assertion_parts[0],
'param_name' => substr($assertion_parts[1], 1),
];
}
}
$info->variadic = isset($parsed_docblock['specials']['psalm-variadic']);
$info->pure = isset($parsed_docblock['specials']['psalm-pure'])
|| isset($parsed_docblock['specials']['pure']);
if (isset($parsed_docblock['specials']['psalm-mutation-free'])) {
$info->mutation_free = true;
}
if (isset($parsed_docblock['specials']['psalm-external-mutation-free'])) {
$info->external_mutation_free = true;
}
$info->ignore_nullable_return = isset($parsed_docblock['specials']['psalm-ignore-nullable-return']);
$info->ignore_falsable_return = isset($parsed_docblock['specials']['psalm-ignore-falsable-return']);
2016-06-24 00:45:46 +02:00
return $info;
}
2016-10-28 06:11:16 +02:00
2017-02-10 02:35:17 +01:00
/**
2019-06-01 22:57:33 +02:00
* @param array<int, string> $return_specials
* @return void
*/
private static function extractReturnType(
PhpParser\Comment\Doc $comment,
2019-06-01 22:57:33 +02:00
array $return_specials,
FunctionDocblockComment $info
) {
2019-06-01 22:57:33 +02:00
foreach ($return_specials as $offset => $return_block) {
$return_lines = explode("\n", $return_block);
2019-06-01 22:57:33 +02:00
if (!trim($return_lines[0])) {
return;
}
2019-06-01 22:57:33 +02:00
$return_block = trim($return_block);
2019-06-01 22:57:33 +02:00
if (!$return_block) {
return;
}
2019-06-01 22:57:33 +02:00
$line_parts = self::splitDocLine($return_block);
2019-06-01 22:57:33 +02:00
if ($line_parts[0][0] !== '{') {
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
throw new IncorrectDocblockException('Misplaced variable');
}
2019-06-01 22:57:33 +02:00
$start = $offset + $comment->getFilePos();
$end = $start + strlen($line_parts[0]);
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
2019-06-01 22:57:33 +02:00
$info->return_type = str_replace("\n", '', array_shift($line_parts));
$info->return_type_description = $line_parts ? implode(' ', $line_parts) : null;
2019-06-01 22:57:33 +02:00
$info->return_type_line_number
= $comment->getLine() + substr_count($comment->getText(), "\n", 0, $offset);
$info->return_type_start = $start;
$info->return_type_end = $end;
} else {
throw new DocblockParseException('Badly-formatted @return type');
}
break;
}
}
/**
2017-05-27 02:16:18 +02:00
* @throws DocblockParseException if there was a problem parsing the docblock
*
2017-02-10 02:35:17 +01:00
* @return ClassLikeDocblockComment
* @psalm-suppress MixedArrayAccess
*/
public static function extractClassLikeDocblockInfo(
\PhpParser\Node $node,
PhpParser\Comment\Doc $comment,
Aliases $aliases
) {
$parsed_docblock = DocComment::parsePreservingLength($comment);
2017-02-10 02:35:17 +01:00
$info = new ClassLikeDocblockComment();
if (isset($parsed_docblock['specials']['template']) || isset($parsed_docblock['specials']['psalm-template'])) {
$all_templates
= (isset($parsed_docblock['specials']['template'])
? $parsed_docblock['specials']['template']
: [])
+ (isset($parsed_docblock['specials']['psalm-template'])
? $parsed_docblock['specials']['psalm-template']
: []);
2019-02-09 17:02:24 +01:00
foreach ($all_templates as $offset => $template_line) {
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
2017-02-10 02:35:17 +01:00
$template_name = array_shift($template_type);
if (!$template_name) {
throw new IncorrectDocblockException('Empty @template tag');
}
if (count($template_type) > 1
&& in_array(strtolower($template_type[0]), ['as', 'super', 'of'], true)
2019-01-16 15:23:18 +01:00
) {
$template_modifier = strtolower(array_shift($template_type));
$info->templates[] = [
$template_name,
$template_modifier,
implode(' ', $template_type),
false,
$offset
];
} else {
$info->templates[] = [$template_name, null, null, false, $offset];
}
}
}
if (isset($parsed_docblock['specials']['template-covariant'])
|| isset($parsed_docblock['specials']['psalm-template-covariant'])
) {
$all_templates =
(isset($parsed_docblock['specials']['template-covariant'])
? $parsed_docblock['specials']['template-covariant']
: [])
+ (isset($parsed_docblock['specials']['psalm-template-covariant'])
? $parsed_docblock['specials']['psalm-template-covariant']
: []);
foreach ($all_templates as $offset => $template_line) {
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
$template_name = array_shift($template_type);
if (!$template_name) {
throw new IncorrectDocblockException('Empty @template-covariant tag');
}
if (count($template_type) > 1
&& in_array(strtolower($template_type[0]), ['as', 'super', 'of'], true)
) {
$template_modifier = strtolower(array_shift($template_type));
$info->templates[] = [
$template_name,
$template_modifier,
implode(' ', $template_type),
true,
$offset
];
2017-02-10 02:35:17 +01:00
} else {
$info->templates[] = [$template_name, null, null, true, $offset];
2017-02-10 02:35:17 +01:00
}
}
}
if (isset($parsed_docblock['specials']['template-extends'])
|| isset($parsed_docblock['specials']['inherits'])
|| isset($parsed_docblock['specials']['extends'])
) {
$all_inheritance = array_merge(
$parsed_docblock['specials']['template-extends'] ?? [],
$parsed_docblock['specials']['inherits'] ?? [],
$parsed_docblock['specials']['extends'] ?? []
);
foreach ($all_inheritance as $template_line) {
$info->template_extends[] = trim(preg_replace('@^[ \t]*\*@m', '', $template_line));
}
}
if (isset($parsed_docblock['specials']['template-implements'])
|| isset($parsed_docblock['specials']['implements'])
) {
$all_inheritance = array_merge(
$parsed_docblock['specials']['template-implements'] ?? [],
$parsed_docblock['specials']['implements'] ?? []
);
foreach ($all_inheritance as $template_line) {
$info->template_implements[] = trim(preg_replace('@^[ \t]*\*@m', '', $template_line));
}
}
if (isset($parsed_docblock['specials']['deprecated'])) {
$info->deprecated = true;
}
if (isset($parsed_docblock['specials']['internal'])) {
$info->internal = true;
}
if (isset($parsed_docblock['specials']['psalm-internal'])) {
$psalm_internal = reset($parsed_docblock['specials']['psalm-internal']);
if ($psalm_internal) {
$info->psalm_internal = $psalm_internal;
} else {
throw new DocblockParseException('psalm-internal annotation used without specifying namespace');
}
if (! $info->internal) {
throw new DocblockParseException('@psalm-internal annotation used without @internal');
}
}
if (isset($parsed_docblock['specials']['psalm-seal-properties'])) {
$info->sealed_properties = true;
}
if (isset($parsed_docblock['specials']['psalm-seal-methods'])) {
$info->sealed_methods = true;
}
2019-09-01 00:43:39 +02:00
if (isset($parsed_docblock['specials']['psalm-immutable'])
2019-08-30 18:36:35 +02:00
|| isset($parsed_docblock['specials']['psalm-mutation-free'])
) {
$info->mutation_free = true;
2019-08-31 16:07:23 +02:00
$info->external_mutation_free = true;
2019-08-30 18:36:35 +02:00
}
if (isset($parsed_docblock['specials']['psalm-external-mutation-free'])) {
$info->external_mutation_free = true;
}
if (isset($parsed_docblock['specials']['psalm-override-property-visibility'])) {
$info->override_property_visibility = true;
}
if (isset($parsed_docblock['specials']['psalm-override-method-visibility'])) {
$info->override_method_visibility = true;
}
if (isset($parsed_docblock['specials']['psalm-suppress'])) {
2019-08-18 20:27:50 +02:00
foreach ($parsed_docblock['specials']['psalm-suppress'] as $offset => $suppress_entry) {
$info->suppressed_issues[$offset + $comment->getFilePos()] = preg_split('/[\s]+/', $suppress_entry)[0];
}
}
if (isset($parsed_docblock['specials']['method']) || isset($parsed_docblock['specials']['psalm-method'])) {
$all_methods
= (isset($parsed_docblock['specials']['method'])
? $parsed_docblock['specials']['method']
: [])
+ (isset($parsed_docblock['specials']['psalm-method'])
? $parsed_docblock['specials']['psalm-method']
: []);
2019-06-01 22:57:33 +02:00
foreach ($all_methods as $offset => $method_entry) {
$method_entry = preg_replace('/[ \t]+/', ' ', trim($method_entry));
$docblock_lines = [];
$is_static = false;
if (!preg_match('/^([a-z_A-Z][a-z_0-9A-Z]+) *\(/', $method_entry, $matches)) {
$doc_line_parts = self::splitDocLine($method_entry);
if ($doc_line_parts[0] === 'static' && !strpos($doc_line_parts[1], '(')) {
$is_static = true;
array_shift($doc_line_parts);
}
if (count($doc_line_parts) > 1) {
$docblock_lines[] = '@return ' . array_shift($doc_line_parts);
$method_entry = implode(' ', $doc_line_parts);
}
}
$method_entry = trim(preg_replace('/\/\/.*/', '', $method_entry));
2019-12-11 17:40:47 +01:00
$method_entry = preg_replace(
'/array\(([0-9a-zA-Z_\'\" ]+,)*([0-9a-zA-Z_\'\" ]+)\)/',
'[]',
$method_entry
);
$end_of_method_regex = '/(?<!array\()\) ?(\: ?(\??[\\\\a-zA-Z0-9_]+))?/';
if (preg_match($end_of_method_regex, $method_entry, $matches, PREG_OFFSET_CAPTURE)) {
$method_entry = substr($method_entry, 0, (int) $matches[0][1] + strlen((string) $matches[0][0]));
}
$method_entry = str_replace([', ', '( '], [',', '('], $method_entry);
$method_entry = preg_replace('/ (?!(\$|\.\.\.|&))/', '', trim($method_entry));
2018-06-28 23:39:25 +02:00
// replace array bracket contents
$method_entry = preg_replace('/\[([0-9a-zA-Z_\'\" ]+,)*([0-9a-zA-Z_\'\" ]+)\]/', '[]', $method_entry);
try {
$method_tree = ParseTree::createFromTokens(
Type::fixUpLocalType(
$method_entry,
$aliases,
null
)
);
} catch (TypeParseTreeException $e) {
throw new DocblockParseException($method_entry . ' is not a valid method');
}
if (!$method_tree instanceof ParseTree\MethodWithReturnTypeTree
&& !$method_tree instanceof ParseTree\MethodTree) {
throw new DocblockParseException($method_entry . ' is not a valid method');
}
if ($method_tree instanceof ParseTree\MethodWithReturnTypeTree) {
$docblock_lines[] = '@return ' . Type::getTypeFromTree($method_tree->children[1]);
$method_tree = $method_tree->children[0];
}
if (!$method_tree instanceof ParseTree\MethodTree) {
throw new DocblockParseException($method_entry . ' is not a valid method');
}
$args = [];
foreach ($method_tree->children as $method_tree_child) {
if (!$method_tree_child instanceof ParseTree\MethodParamTree) {
throw new DocblockParseException($method_entry . ' is not a valid method');
}
$args[] = ($method_tree_child->byref ? '&' : '')
. ($method_tree_child->variadic ? '...' : '')
. $method_tree_child->name
. ($method_tree_child->default != '' ? ' = ' . $method_tree_child->default : '');
if ($method_tree_child->children) {
$param_type = Type::getTypeFromTree($method_tree_child->children[0]);
$docblock_lines[] = '@param \\' . $param_type . ' '
. ($method_tree_child->variadic ? '...' : '')
. $method_tree_child->name;
}
}
$function_string = 'function ' . $method_tree->value . '(' . implode(', ', $args) . ')';
if ($is_static) {
$function_string = 'static ' . $function_string;
}
$function_docblock = $docblock_lines ? "/**\n * " . implode("\n * ", $docblock_lines) . "\n*/\n" : "";
$php_string = '<?php class A { ' . $function_docblock . ' public ' . $function_string . '{} }';
try {
2018-11-06 03:57:36 +01:00
$statements = \Psalm\Internal\Provider\StatementsProvider::parseStatements($php_string);
} catch (\Exception $e) {
throw new DocblockParseException('Badly-formatted @method string ' . $method_entry);
}
if (!$statements[0] instanceof \PhpParser\Node\Stmt\Class_
|| !isset($statements[0]->stmts[0])
|| !$statements[0]->stmts[0] instanceof \PhpParser\Node\Stmt\ClassMethod
) {
throw new DocblockParseException('Badly-formatted @method string ' . $method_entry);
}
/** @var \PhpParser\Comment\Doc */
$node_doc_comment = $node->getDocComment();
$statements[0]->stmts[0]->setAttribute('startLine', $node_doc_comment->getLine());
$statements[0]->stmts[0]->setAttribute('startFilePos', $node_doc_comment->getFilePos());
$statements[0]->stmts[0]->setAttribute('endFilePos', $node->getAttribute('startFilePos'));
if ($doc_comment = $statements[0]->stmts[0]->getDocComment()) {
$statements[0]->stmts[0]->setDocComment(
new \PhpParser\Comment\Doc(
$doc_comment->getText(),
2019-06-01 22:57:33 +02:00
$comment->getLine() + substr_count($comment->getText(), "\n", 0, $offset),
$node_doc_comment->getFilePos()
)
);
}
$info->methods[] = $statements[0]->stmts[0];
}
}
self::addMagicPropertyToInfo($comment, $info, $parsed_docblock['specials'], 'property');
self::addMagicPropertyToInfo($comment, $info, $parsed_docblock['specials'], 'psalm-property');
self::addMagicPropertyToInfo($comment, $info, $parsed_docblock['specials'], 'property-read');
self::addMagicPropertyToInfo($comment, $info, $parsed_docblock['specials'], 'property-write');
return $info;
}
/**
* @param ClassLikeDocblockComment $info
* @param array<string, array<int, string>> $specials
2019-06-14 16:45:00 +02:00
* @param 'property'|'psalm-property'|'property-read'|'property-write' $property_tag
*
* @throws DocblockParseException
*
* @return void
*/
2019-06-01 22:57:33 +02:00
protected static function addMagicPropertyToInfo(
PhpParser\Comment\Doc $comment,
ClassLikeDocblockComment $info,
array $specials,
string $property_tag
) : void {
$magic_property_comments = isset($specials[$property_tag]) ? $specials[$property_tag] : [];
2019-06-01 22:57:33 +02:00
foreach ($magic_property_comments as $offset => $property) {
$line_parts = self::splitDocLine($property);
2019-06-14 16:45:00 +02:00
if (count($line_parts) === 1 && isset($line_parts[0][0]) && $line_parts[0][0] === '$') {
continue;
}
if (count($line_parts) > 1) {
2019-06-14 16:45:00 +02:00
if (preg_match('/^&?\$[A-Za-z0-9_]+,?$/', $line_parts[1])
&& $line_parts[0][0] !== '{'
) {
2019-06-14 16:45:00 +02:00
$line_parts[1] = str_replace('&', '', $line_parts[1]);
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
$start = $offset + $comment->getFilePos();
$end = $start + strlen($line_parts[0]);
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
2019-06-14 16:45:00 +02:00
if ($line_parts[0] === ''
|| ($line_parts[0][0] === '$'
&& !preg_match('/^\$this(\||$)/', $line_parts[0]))
) {
throw new IncorrectDocblockException('Misplaced variable');
}
$info->properties[] = [
2019-06-14 16:45:00 +02:00
'name' => trim($line_parts[1]),
'type' => $line_parts[0],
2019-06-01 22:57:33 +02:00
'line_number' => $comment->getLine() + substr_count($comment->getText(), "\n", 0, $offset),
'tag' => $property_tag,
2019-06-14 16:45:00 +02:00
'start' => $start,
'end' => $end,
];
}
} else {
throw new DocblockParseException('Badly-formatted @property');
}
}
2017-02-10 02:35:17 +01:00
}
2016-10-28 06:11:16 +02:00
/**
* @param string $return_block
2017-05-27 02:16:18 +02:00
*
* @throws DocblockParseException if an invalid string is found
*
2016-10-28 06:11:16 +02:00
* @return array<string>
*/
2018-01-07 16:23:02 +01:00
public static function splitDocLine($return_block)
2016-10-28 06:11:16 +02:00
{
$brackets = '';
$type = '';
$expects_callable_return = false;
$return_block = str_replace("\t", ' ', $return_block);
2018-05-20 23:19:53 +02:00
$quote_char = null;
$escaped = false;
for ($i = 0, $l = strlen($return_block); $i < $l; ++$i) {
2016-10-28 06:11:16 +02:00
$char = $return_block[$i];
$next_char = $i < $l - 1 ? $return_block[$i + 1] : null;
$last_char = $i > 0 ? $return_block[$i - 1] : null;
2016-10-28 06:11:16 +02:00
2018-05-20 23:19:53 +02:00
if ($quote_char) {
if ($char === $quote_char && $i > 1 && !$escaped) {
$quote_char = null;
$type .= $char;
continue;
}
if ($char === '\\' && !$escaped && ($next_char === $quote_char || $next_char === '\\')) {
$escaped = true;
$type .= $char;
continue;
}
$escaped = false;
$type .= $char;
continue;
}
if ($char === '"' || $char === '\'') {
$quote_char = $char;
$type .= $char;
continue;
}
if ($char === ':' && $last_char === ')') {
$expects_callable_return = true;
$type .= $char;
continue;
}
2016-10-28 06:11:16 +02:00
if ($char === '[' || $char === '{' || $char === '(' || $char === '<') {
$brackets .= $char;
2016-11-02 07:29:00 +01:00
} elseif ($char === ']' || $char === '}' || $char === ')' || $char === '>') {
2016-10-28 06:11:16 +02:00
$last_bracket = substr($brackets, -1);
$brackets = substr($brackets, 0, -1);
if (($char === ']' && $last_bracket !== '[')
|| ($char === '}' && $last_bracket !== '{')
|| ($char === ')' && $last_bracket !== '(')
|| ($char === '>' && $last_bracket !== '<')
) {
2016-11-02 07:29:00 +01:00
throw new DocblockParseException('Invalid string ' . $return_block);
2016-10-28 06:11:16 +02:00
}
} elseif ($char === ' ') {
if ($brackets) {
$expects_callable_return = false;
2019-06-01 23:22:33 +02:00
$type .= ' ';
2016-10-28 06:11:16 +02:00
continue;
}
if ($next_char === '|' || $next_char === '&') {
$nexter_char = $i < $l - 2 ? $return_block[$i + 2] : null;
if ($nexter_char === ' ') {
++$i;
2019-06-06 19:57:00 +02:00
$type .= $next_char . ' ';
continue;
}
}
if ($last_char === '|' || $last_char === '&') {
2019-06-06 19:57:00 +02:00
$type .= ' ';
continue;
}
if ($next_char === ':') {
++$i;
2019-06-06 19:57:00 +02:00
$type .= ' :';
$expects_callable_return = true;
continue;
}
if ($expects_callable_return) {
2019-06-06 20:27:49 +02:00
$type .= ' ';
$expects_callable_return = false;
continue;
}
$remaining = trim(preg_replace('@^[ \t]*\* *@m', ' ', substr($return_block, $i + 1)));
2016-11-01 05:39:41 +01:00
if ($remaining) {
/** @var array<string> */
return array_merge([rtrim($type)], preg_split('/[ \s]+/', $remaining));
2016-11-01 05:39:41 +01:00
}
return [$type];
2016-10-28 06:11:16 +02:00
}
$expects_callable_return = false;
2016-10-28 06:11:16 +02:00
$type .= $char;
}
return [$type];
}
2016-06-24 00:45:46 +02:00
}