2016-06-24 00:45:46 +02:00
|
|
|
|
<?php
|
2016-08-13 20:20:46 +02:00
|
|
|
|
namespace Psalm\Checker;
|
|
|
|
|
|
2017-07-25 22:11:02 +02:00
|
|
|
|
use Psalm\Aliases;
|
2017-05-19 06:48:26 +02:00
|
|
|
|
use Psalm\ClassLikeDocblockComment;
|
2016-11-02 07:29:00 +01:00
|
|
|
|
use Psalm\Exception\DocblockParseException;
|
2017-11-15 03:43:31 +01:00
|
|
|
|
use Psalm\Exception\IncorrectDocblockException;
|
2017-05-19 06:48:26 +02:00
|
|
|
|
use Psalm\Exception\TypeParseTreeException;
|
2018-01-21 18:44:46 +01:00
|
|
|
|
use Psalm\FileSource;
|
2016-11-13 05:59:31 +01:00
|
|
|
|
use Psalm\FunctionDocblockComment;
|
2016-08-13 20:20:46 +02:00
|
|
|
|
use Psalm\Type;
|
2017-05-25 07:32:34 +02:00
|
|
|
|
use Psalm\VarDocblockComment;
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
|
|
|
|
class CommentChecker
|
|
|
|
|
{
|
2018-04-22 04:13:10 +02:00
|
|
|
|
const TYPE_REGEX = '(\??\\\?[\(\)A-Za-z0-9_&\<\.=,\>\[\]\-\{\}:|?\\\\]*|\$[a-zA-Z_0-9_]+)';
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* @param string $comment
|
2017-07-25 22:11:02 +02:00
|
|
|
|
* @param Aliases $aliases
|
2017-02-10 06:14:44 +01:00
|
|
|
|
* @param array<string, string>|null $template_types
|
2017-03-02 04:27:52 +01:00
|
|
|
|
* @param int|null $var_line_number
|
2017-04-11 21:34:05 +02:00
|
|
|
|
* @param int|null $came_from_line_number what line number in $source that $comment came from
|
2017-05-27 02:16:18 +02:00
|
|
|
|
*
|
|
|
|
|
* @throws DocblockParseException if there was a problem parsing the docblock
|
|
|
|
|
*
|
2018-02-08 05:33:31 +01:00
|
|
|
|
* @return VarDocblockComment[]
|
2016-11-22 01:07:56 +01:00
|
|
|
|
* @psalm-suppress MixedArrayAccess
|
2016-06-24 00:45:46 +02:00
|
|
|
|
*/
|
2016-11-02 07:29:00 +01:00
|
|
|
|
public static function getTypeFromComment(
|
|
|
|
|
$comment,
|
2018-01-21 18:44:46 +01:00
|
|
|
|
FileSource $source,
|
2017-07-25 22:11:02 +02:00
|
|
|
|
Aliases $aliases,
|
2017-03-02 04:27:52 +01:00
|
|
|
|
array $template_types = null,
|
2017-05-25 07:32:34 +02:00
|
|
|
|
$var_line_number = null,
|
2017-04-11 21:34:05 +02:00
|
|
|
|
$came_from_line_number = null
|
2016-11-02 07:29:00 +01:00
|
|
|
|
) {
|
2017-05-25 07:32:34 +02:00
|
|
|
|
$var_id = null;
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2017-05-25 07:32:34 +02:00
|
|
|
|
$var_type_string = null;
|
2018-01-02 02:04:03 +01:00
|
|
|
|
$original_type = null;
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
$var_comments = [];
|
2017-03-02 04:27:52 +01:00
|
|
|
|
$comments = self::parseDocComment($comment, $var_line_number);
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2017-11-03 02:45:17 +01:00
|
|
|
|
if (!isset($comments['specials']['var']) && !isset($comments['specials']['psalm-var'])) {
|
2018-02-08 05:33:31 +01:00
|
|
|
|
return [];
|
2017-03-02 04:27:52 +01:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if ($comments) {
|
2017-11-03 02:45:17 +01:00
|
|
|
|
$all_vars = (isset($comments['specials']['var']) ? $comments['specials']['var'] : [])
|
|
|
|
|
+ (isset($comments['specials']['psalm-var']) ? $comments['specials']['psalm-var'] : []);
|
|
|
|
|
|
2017-03-02 04:27:52 +01:00
|
|
|
|
/** @var int $line_number */
|
2017-11-03 02:45:17 +01:00
|
|
|
|
foreach ($all_vars as $line_number => $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;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
try {
|
|
|
|
|
$line_parts = self::splitDocLine($var_line);
|
|
|
|
|
} catch (DocblockParseException $e) {
|
|
|
|
|
throw $e;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if ($line_parts && $line_parts[0]) {
|
2017-11-15 03:43:31 +01:00
|
|
|
|
if ($line_parts[0][0] === '$' && $line_parts[0] !== '$this') {
|
|
|
|
|
throw new IncorrectDocblockException('Misplaced variable');
|
|
|
|
|
}
|
|
|
|
|
|
2018-04-05 23:18:49 +02:00
|
|
|
|
try {
|
|
|
|
|
$var_type_string = Type::fixUpLocalType(
|
|
|
|
|
$line_parts[0],
|
|
|
|
|
$aliases,
|
|
|
|
|
$template_types
|
|
|
|
|
);
|
|
|
|
|
} catch (TypeParseTreeException $e) {
|
|
|
|
|
throw new DocblockParseException($line_parts[0] . ' is not a valid type');
|
|
|
|
|
}
|
2017-03-02 04:27:52 +01:00
|
|
|
|
|
2018-01-02 02:04:03 +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] === '$') {
|
2017-05-25 07:32:34 +02:00
|
|
|
|
$var_id = $line_parts[1];
|
2017-03-02 04:27:52 +01:00
|
|
|
|
}
|
2018-02-08 05:33:31 +01:00
|
|
|
|
}
|
2017-03-02 04:27:52 +01:00
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
if (!$var_type_string || !$original_type) {
|
|
|
|
|
continue;
|
2016-06-24 00:45:46 +02:00
|
|
|
|
}
|
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
try {
|
2018-04-20 16:52:23 +02:00
|
|
|
|
$defined_type = Type::parseString($var_type_string, false, $template_types ?: []);
|
2018-02-08 05:33:31 +01:00
|
|
|
|
} catch (TypeParseTreeException $e) {
|
|
|
|
|
if (is_int($came_from_line_number)) {
|
|
|
|
|
throw new DocblockParseException(
|
|
|
|
|
$var_type_string .
|
|
|
|
|
' is not a valid type' .
|
|
|
|
|
' (from ' .
|
|
|
|
|
$source->getCheckedFilePath() .
|
|
|
|
|
':' .
|
|
|
|
|
$came_from_line_number .
|
|
|
|
|
')'
|
|
|
|
|
);
|
|
|
|
|
}
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
throw new DocblockParseException($var_type_string . ' is not a valid type');
|
|
|
|
|
}
|
2017-05-25 07:32:34 +02:00
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
$defined_type->setFromDocblock();
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2018-02-08 05:33:31 +01: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;
|
|
|
|
|
$var_comment->deprecated = isset($comments['specials']['deprecated']);
|
2017-02-04 04:07:14 +01:00
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
$var_comments[] = $var_comment;
|
|
|
|
|
}
|
|
|
|
|
}
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2018-02-08 05:33:31 +01:00
|
|
|
|
return $var_comments;
|
2016-06-24 00:45:46 +02:00
|
|
|
|
}
|
|
|
|
|
|
2016-10-14 06:53:43 +02:00
|
|
|
|
/**
|
2016-12-04 01:11:30 +01:00
|
|
|
|
* @param string $comment
|
|
|
|
|
* @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-11-22 01:07:56 +01:00
|
|
|
|
* @psalm-suppress MixedArrayAccess
|
2016-10-14 06:53:43 +02:00
|
|
|
|
*/
|
2017-02-10 02:35:17 +01:00
|
|
|
|
public static function extractFunctionDocblockInfo($comment, $line_number)
|
2016-06-24 00:45:46 +02:00
|
|
|
|
{
|
2016-12-04 01:11:30 +01:00
|
|
|
|
$comments = self::parseDocComment($comment, $line_number);
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2016-11-13 05:59:31 +01:00
|
|
|
|
$info = new FunctionDocblockComment();
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2016-10-04 03:36:42 +02:00
|
|
|
|
if (isset($comments['specials']['return']) || isset($comments['specials']['psalm-return'])) {
|
2016-12-17 01:22:30 +01:00
|
|
|
|
/** @var array<int, string> */
|
2016-12-04 01:11:30 +01:00
|
|
|
|
$return_specials = isset($comments['specials']['psalm-return'])
|
|
|
|
|
? $comments['specials']['psalm-return']
|
|
|
|
|
: $comments['specials']['return'];
|
|
|
|
|
|
|
|
|
|
$return_block = trim((string)reset($return_specials));
|
2016-06-24 00:45:46 +02:00
|
|
|
|
|
2016-10-28 17:05:51 +02:00
|
|
|
|
try {
|
|
|
|
|
$line_parts = self::splitDocLine($return_block);
|
2016-11-02 07:29:00 +01:00
|
|
|
|
} catch (DocblockParseException $e) {
|
2016-10-28 17:05:51 +02:00
|
|
|
|
throw $e;
|
|
|
|
|
}
|
2016-10-28 06:11:16 +02:00
|
|
|
|
|
|
|
|
|
if (preg_match('/^' . self::TYPE_REGEX . '$/', $line_parts[0])
|
|
|
|
|
&& !preg_match('/\[[^\]]+\]/', $line_parts[0])
|
2016-10-28 19:24:06 +02:00
|
|
|
|
&& !strpos($line_parts[0], '::')
|
2017-01-15 16:58:44 +01:00
|
|
|
|
&& $line_parts[0][0] !== '{'
|
2016-10-28 19:24:06 +02:00
|
|
|
|
) {
|
2018-03-22 22:55:36 +01:00
|
|
|
|
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
|
|
|
|
|
throw new IncorrectDocblockException('Misplaced variable');
|
2017-05-25 03:11:18 +02:00
|
|
|
|
}
|
|
|
|
|
|
2016-11-13 05:59:31 +01:00
|
|
|
|
$info->return_type = $line_parts[0];
|
2017-01-28 06:24:25 +01:00
|
|
|
|
$line_number = array_keys($return_specials)[0];
|
|
|
|
|
|
|
|
|
|
if ($line_number) {
|
|
|
|
|
$info->return_type_line_number = $line_number;
|
|
|
|
|
}
|
2017-07-10 02:32:35 +02:00
|
|
|
|
} else {
|
|
|
|
|
throw new DocblockParseException('Badly-formatted @return type');
|
2016-06-24 00:45:46 +02:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2017-11-03 02:45:17 +01:00
|
|
|
|
if (isset($comments['specials']['param']) || isset($comments['specials']['psalm-param'])) {
|
|
|
|
|
$all_params = (isset($comments['specials']['param']) ? $comments['specials']['param'] : [])
|
|
|
|
|
+ (isset($comments['specials']['psalm-param']) ? $comments['specials']['psalm-param'] : []);
|
|
|
|
|
|
2016-12-17 06:48:31 +01:00
|
|
|
|
/** @var string $param */
|
2017-11-03 02:45:17 +01:00
|
|
|
|
foreach ($all_params as $line_number => $param) {
|
2016-10-28 17:05:51 +02:00
|
|
|
|
try {
|
2016-12-17 06:48:31 +01:00
|
|
|
|
$line_parts = self::splitDocLine($param);
|
2016-11-02 07:29:00 +01:00
|
|
|
|
} catch (DocblockParseException $e) {
|
2016-10-28 17:05:51 +02:00
|
|
|
|
throw $e;
|
|
|
|
|
}
|
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] === '$') {
|
2018-03-30 23:46:12 +02:00
|
|
|
|
continue;
|
2017-01-16 05:49:58 +01:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-25 12:32:21 +01:00
|
|
|
|
if (count($line_parts) > 1) {
|
|
|
|
|
if (preg_match('/^' . self::TYPE_REGEX . '$/', $line_parts[0])
|
|
|
|
|
&& !preg_match('/\[[^\]]+\]/', $line_parts[0])
|
2017-01-28 08:37:52 +01:00
|
|
|
|
&& preg_match('/^(\.\.\.)?&?\$[A-Za-z0-9_]+,?$/', $line_parts[1])
|
2016-12-25 12:32:21 +01:00
|
|
|
|
&& !strpos($line_parts[0], '::')
|
2017-01-15 16:58:44 +01:00
|
|
|
|
&& $line_parts[0][0] !== '{'
|
2017-11-12 03:22:11 +01:00
|
|
|
|
&& !in_array($line_parts[0], ['null', 'false', 'true'], true)
|
2016-12-25 12:32:21 +01:00
|
|
|
|
) {
|
|
|
|
|
if ($line_parts[1][0] === '&') {
|
|
|
|
|
$line_parts[1] = substr($line_parts[1], 1);
|
|
|
|
|
}
|
|
|
|
|
|
2018-03-22 22:55:36 +01:00
|
|
|
|
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
|
2017-11-15 03:43:31 +01:00
|
|
|
|
throw new IncorrectDocblockException('Misplaced variable');
|
2017-05-25 03:11:18 +02:00
|
|
|
|
}
|
|
|
|
|
|
2017-01-28 08:37:52 +01:00
|
|
|
|
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
|
|
|
|
|
|
2016-12-25 12:32:21 +01:00
|
|
|
|
$info->params[] = [
|
2017-01-17 07:14:43 +01:00
|
|
|
|
'name' => $line_parts[1],
|
2016-12-25 12:32:21 +01:00
|
|
|
|
'type' => $line_parts[0],
|
2017-11-19 19:05:35 +01:00
|
|
|
|
'line_number' => (int)$line_number,
|
2016-12-25 12:32:21 +01:00
|
|
|
|
];
|
2016-10-15 06:12:57 +02:00
|
|
|
|
}
|
2016-12-25 12:32:21 +01:00
|
|
|
|
} else {
|
|
|
|
|
throw new DocblockParseException('Badly-formatted @param');
|
2016-06-24 00:45:46 +02:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2016-07-22 19:29:46 +02:00
|
|
|
|
if (isset($comments['specials']['deprecated'])) {
|
2016-11-13 05:59:31 +01:00
|
|
|
|
$info->deprecated = true;
|
2016-07-22 19:29:46 +02:00
|
|
|
|
}
|
|
|
|
|
|
2016-10-11 20:17:55 +02:00
|
|
|
|
if (isset($comments['specials']['psalm-suppress'])) {
|
2016-12-17 06:48:31 +01:00
|
|
|
|
/** @var string $suppress_entry */
|
2016-10-11 20:17:55 +02:00
|
|
|
|
foreach ($comments['specials']['psalm-suppress'] as $suppress_entry) {
|
2016-12-17 06:48:31 +01:00
|
|
|
|
$info->suppress[] = preg_split('/[\s]+/', $suppress_entry)[0];
|
2016-07-22 19:29:46 +02:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2017-02-10 02:35:17 +01:00
|
|
|
|
if (isset($comments['specials']['template'])) {
|
|
|
|
|
/** @var string $suppress_entry */
|
|
|
|
|
foreach ($comments['specials']['template'] as $template_line) {
|
|
|
|
|
$template_type = preg_split('/[\s]+/', $template_line);
|
|
|
|
|
|
2017-05-27 02:05:57 +02:00
|
|
|
|
if (count($template_type) > 2 && in_array(strtolower($template_type[1]), ['as', 'super'], true)) {
|
2017-02-10 02:35:17 +01:00
|
|
|
|
$info->template_types[] = [$template_type[0], strtolower($template_type[1]), $template_type[2]];
|
|
|
|
|
} else {
|
|
|
|
|
$info->template_types[] = [$template_type[0]];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if (isset($comments['specials']['template-typeof'])) {
|
|
|
|
|
/** @var string $suppress_entry */
|
|
|
|
|
foreach ($comments['specials']['template-typeof'] as $template_typeof) {
|
|
|
|
|
$typeof_parts = preg_split('/[\s]+/', $template_typeof);
|
|
|
|
|
|
|
|
|
|
if (count($typeof_parts) < 2 || $typeof_parts[1][0] !== '$') {
|
2017-11-15 03:43:31 +01:00
|
|
|
|
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),
|
|
|
|
|
];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2016-11-13 05:59:31 +01:00
|
|
|
|
$info->variadic = isset($comments['specials']['psalm-variadic']);
|
2017-05-10 18:36:11 +02:00
|
|
|
|
$info->ignore_nullable_return = isset($comments['specials']['psalm-ignore-nullable-return']);
|
2018-01-25 00:52:58 +01:00
|
|
|
|
$info->ignore_falsable_return = isset($comments['specials']['psalm-ignore-falsable-return']);
|
2016-10-18 23:55:07 +02:00
|
|
|
|
|
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
|
|
|
|
/**
|
|
|
|
|
* @param string $comment
|
|
|
|
|
* @param int $line_number
|
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($comment, $line_number)
|
|
|
|
|
{
|
|
|
|
|
$comments = self::parseDocComment($comment, $line_number);
|
|
|
|
|
|
|
|
|
|
$info = new ClassLikeDocblockComment();
|
|
|
|
|
|
|
|
|
|
if (isset($comments['specials']['template'])) {
|
|
|
|
|
/** @var string $suppress_entry */
|
|
|
|
|
foreach ($comments['specials']['template'] as $template_line) {
|
|
|
|
|
$template_type = preg_split('/[\s]+/', $template_line);
|
|
|
|
|
|
2017-05-27 02:05:57 +02:00
|
|
|
|
if (count($template_type) > 2 && in_array(strtolower($template_type[1]), ['as', 'super'], true)) {
|
2017-02-10 02:35:17 +01:00
|
|
|
|
$info->template_types[] = [$template_type[0], strtolower($template_type[1]), $template_type[2]];
|
|
|
|
|
} else {
|
|
|
|
|
$info->template_types[] = [$template_type[0]];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2017-05-05 00:35:05 +02:00
|
|
|
|
if (isset($comments['specials']['deprecated'])) {
|
|
|
|
|
$info->deprecated = true;
|
|
|
|
|
}
|
|
|
|
|
|
2017-11-17 02:47:58 +01:00
|
|
|
|
if (isset($comments['specials']['psalm-seal-properties'])) {
|
|
|
|
|
$info->sealed_properties = true;
|
|
|
|
|
}
|
|
|
|
|
|
2018-04-22 06:40:30 +02:00
|
|
|
|
if (isset($comments['specials']['psalm-seal-methods'])) {
|
|
|
|
|
$info->sealed_methods = true;
|
|
|
|
|
}
|
|
|
|
|
|
2017-09-13 17:32:13 +02:00
|
|
|
|
if (isset($comments['specials']['psalm-suppress'])) {
|
|
|
|
|
/** @var string $suppress_entry */
|
|
|
|
|
foreach ($comments['specials']['psalm-suppress'] as $suppress_entry) {
|
|
|
|
|
$info->suppressed_issues[] = preg_split('/[\s]+/', $suppress_entry)[0];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2018-04-22 04:13:10 +02:00
|
|
|
|
if (isset($comments['specials']['method'])) {
|
|
|
|
|
/** @var string $method_entry */
|
|
|
|
|
foreach ($comments['specials']['method'] as $method_entry) {
|
|
|
|
|
$method_entry = trim($method_entry);
|
|
|
|
|
|
|
|
|
|
$return_docblock = '';
|
|
|
|
|
|
|
|
|
|
if (!preg_match('/^([a-z_A-Z][a-z_0-9A-Z]+) *\(/', $method_entry, $matches)) {
|
|
|
|
|
$doc_line_parts = self::splitDocLine($method_entry);
|
|
|
|
|
|
|
|
|
|
$return_docblock = '/** @return ' . array_shift($doc_line_parts) . ' */';
|
|
|
|
|
|
|
|
|
|
$method_entry = implode(' ', $doc_line_parts);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$method_entry = trim(preg_replace('/\/\/.*/', '', $method_entry));
|
|
|
|
|
|
|
|
|
|
$php_string = '<?php ' . $return_docblock . ' function ' . $method_entry . '{}';
|
|
|
|
|
|
|
|
|
|
try {
|
|
|
|
|
$statements = \Psalm\Provider\StatementsProvider::parseStatements($php_string);
|
|
|
|
|
} catch (\Exception $e) {
|
|
|
|
|
throw new DocblockParseException('Badly-formatted @method string ' . $method_entry);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if (!$statements[0] instanceof \PhpParser\Node\Stmt\Function_) {
|
|
|
|
|
throw new \UnexpectedValueException('Shouldn’t get here with ' . $php_string);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$info->methods[] = $statements[0];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2017-12-14 20:22:27 +01:00
|
|
|
|
self::addMagicPropertyToInfo($info, $comments['specials'], 'property');
|
|
|
|
|
self::addMagicPropertyToInfo($info, $comments['specials'], 'property-read');
|
|
|
|
|
self::addMagicPropertyToInfo($info, $comments['specials'], 'property-write');
|
2017-05-05 00:35:05 +02:00
|
|
|
|
|
2017-12-14 20:22:27 +01:00
|
|
|
|
return $info;
|
|
|
|
|
}
|
2017-05-05 00:35:05 +02:00
|
|
|
|
|
2017-12-14 20:22:27 +01:00
|
|
|
|
/**
|
|
|
|
|
* @param ClassLikeDocblockComment $info
|
2018-01-10 16:56:43 +01:00
|
|
|
|
* @param array<string, array<int, string>> $specials
|
2017-12-14 20:22:27 +01:00
|
|
|
|
* @param string $property_tag ('property', 'property-read', or 'property-write')
|
2017-12-15 22:48:06 +01:00
|
|
|
|
*
|
2017-12-14 20:22:27 +01:00
|
|
|
|
* @throws DocblockParseException
|
2017-12-15 22:48:06 +01:00
|
|
|
|
*
|
|
|
|
|
* @return void
|
2017-12-14 20:22:27 +01:00
|
|
|
|
*/
|
|
|
|
|
protected static function addMagicPropertyToInfo(ClassLikeDocblockComment $info, array $specials, $property_tag)
|
|
|
|
|
{
|
|
|
|
|
$magic_property_comments = isset($specials[$property_tag]) ? $specials[$property_tag] : [];
|
|
|
|
|
foreach ($magic_property_comments as $line_number => $property) {
|
|
|
|
|
try {
|
|
|
|
|
$line_parts = self::splitDocLine($property);
|
|
|
|
|
} catch (DocblockParseException $e) {
|
|
|
|
|
throw $e;
|
|
|
|
|
}
|
2017-05-05 00:35:05 +02:00
|
|
|
|
|
2017-12-14 20:22:27 +01:00
|
|
|
|
if (count($line_parts) === 1 && $line_parts[0][0] === '$') {
|
|
|
|
|
array_unshift($line_parts, 'mixed');
|
|
|
|
|
}
|
2017-05-25 03:11:18 +02:00
|
|
|
|
|
2017-12-14 20:22:27 +01:00
|
|
|
|
if (count($line_parts) > 1) {
|
|
|
|
|
if (preg_match('/^' . self::TYPE_REGEX . '$/', $line_parts[0])
|
|
|
|
|
&& !preg_match('/\[[^\]]+\]/', $line_parts[0])
|
|
|
|
|
&& preg_match('/^(\.\.\.)?&?\$[A-Za-z0-9_]+,?$/', $line_parts[1])
|
|
|
|
|
&& !strpos($line_parts[0], '::')
|
|
|
|
|
&& $line_parts[0][0] !== '{'
|
|
|
|
|
) {
|
|
|
|
|
if ($line_parts[1][0] === '&') {
|
|
|
|
|
$line_parts[1] = substr($line_parts[1], 1);
|
|
|
|
|
}
|
2017-05-05 00:35:05 +02:00
|
|
|
|
|
2018-03-22 22:55:36 +01:00
|
|
|
|
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
|
2017-12-14 20:22:27 +01:00
|
|
|
|
throw new IncorrectDocblockException('Misplaced variable');
|
2017-05-05 00:35:05 +02:00
|
|
|
|
}
|
2017-12-14 20:22:27 +01:00
|
|
|
|
|
|
|
|
|
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
|
|
|
|
|
|
|
|
|
|
$info->properties[] = [
|
|
|
|
|
'name' => $line_parts[1],
|
|
|
|
|
'type' => $line_parts[0],
|
|
|
|
|
'line_number' => $line_number,
|
|
|
|
|
'tag' => $property_tag,
|
|
|
|
|
];
|
2017-05-05 00:35:05 +02:00
|
|
|
|
} else {
|
2017-12-14 20:22:27 +01:00
|
|
|
|
throw new DocblockParseException('Badly-formatted @property');
|
2017-05-05 00:35:05 +02:00
|
|
|
|
}
|
2017-12-14 20:22:27 +01:00
|
|
|
|
} else {
|
|
|
|
|
throw new DocblockParseException('Badly-formatted @property');
|
2017-05-05 00:35:05 +02:00
|
|
|
|
}
|
|
|
|
|
}
|
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 = '';
|
|
|
|
|
|
2018-03-27 04:13:10 +02:00
|
|
|
|
$expects_callable_return = false;
|
|
|
|
|
|
|
|
|
|
$return_block = preg_replace('/[ \t]+/', ' ', $return_block);
|
|
|
|
|
|
|
|
|
|
for ($i = 0, $l = strlen($return_block); $i < $l; ++$i) {
|
2016-10-28 06:11:16 +02:00
|
|
|
|
$char = $return_block[$i];
|
2018-03-27 04:13:10 +02:00
|
|
|
|
$next_char = $i < $l - 1 ? $return_block[$i + 1] : null;
|
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
|
|
|
|
}
|
2016-11-02 07:29:00 +01:00
|
|
|
|
} elseif ($char === ' ' || $char === "\t") {
|
2016-10-28 06:11:16 +02:00
|
|
|
|
if ($brackets) {
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
|
2018-03-27 04:13:10 +02:00
|
|
|
|
if ($next_char === ':') {
|
|
|
|
|
++$i;
|
2018-03-27 06:12:41 +02:00
|
|
|
|
$type .= ':';
|
2018-03-27 04:13:10 +02:00
|
|
|
|
$expects_callable_return = true;
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if ($expects_callable_return) {
|
|
|
|
|
$expects_callable_return = false;
|
|
|
|
|
continue;
|
|
|
|
|
}
|
|
|
|
|
|
2016-11-01 05:39:41 +01:00
|
|
|
|
$remaining = trim(substr($return_block, $i + 1));
|
|
|
|
|
|
|
|
|
|
if ($remaining) {
|
2018-03-27 04:13:10 +02:00
|
|
|
|
return array_merge([$type], explode(' ', $remaining));
|
2016-11-01 05:39:41 +01:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return [$type];
|
2016-10-28 06:11:16 +02:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$type .= $char;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return [$type];
|
|
|
|
|
}
|
|
|
|
|
|
2016-11-02 07:29:00 +01:00
|
|
|
|
/**
|
2016-10-28 06:11:16 +02:00
|
|
|
|
* Parse a docblock comment into its parts.
|
|
|
|
|
*
|
2016-11-02 07:29:00 +01:00
|
|
|
|
* Taken from advanced api docmaker, which was taken from
|
|
|
|
|
* https://github.com/facebook/libphutil/blob/master/src/parser/docblock/PhutilDocblockParser.php
|
2016-10-28 06:11:16 +02:00
|
|
|
|
*
|
|
|
|
|
* @param string $docblock
|
2016-12-04 01:11:30 +01:00
|
|
|
|
* @param int $line_number
|
2018-01-10 04:33:36 +01:00
|
|
|
|
* @param bool $preserve_format
|
2017-05-27 02:16:18 +02:00
|
|
|
|
*
|
2016-10-28 06:11:16 +02:00
|
|
|
|
* @return array Array of the main comment and specials
|
2018-01-10 16:56:43 +01:00
|
|
|
|
* @psalm-return array{description:string, specials:array<string, array<int, string>>}
|
2016-10-28 06:11:16 +02:00
|
|
|
|
*/
|
2018-01-10 04:33:36 +01:00
|
|
|
|
public static function parseDocComment($docblock, $line_number = null, $preserve_format = false)
|
2016-10-28 06:11:16 +02:00
|
|
|
|
{
|
|
|
|
|
// Strip off comments.
|
|
|
|
|
$docblock = trim($docblock);
|
|
|
|
|
$docblock = preg_replace('@^/\*\*@', '', $docblock);
|
|
|
|
|
$docblock = preg_replace('@\*/$@', '', $docblock);
|
2017-01-02 05:30:59 +01:00
|
|
|
|
$docblock = preg_replace('@^[ \t]*\*@m', '', $docblock);
|
2016-10-28 06:11:16 +02:00
|
|
|
|
|
|
|
|
|
// Normalize multi-line @specials.
|
|
|
|
|
$lines = explode("\n", $docblock);
|
2016-12-04 01:11:30 +01:00
|
|
|
|
|
|
|
|
|
$line_map = [];
|
|
|
|
|
|
2016-10-28 06:11:16 +02:00
|
|
|
|
$last = false;
|
|
|
|
|
foreach ($lines as $k => $line) {
|
|
|
|
|
if (preg_match('/^\s?@\w/i', $line)) {
|
|
|
|
|
$last = $k;
|
|
|
|
|
} elseif (preg_match('/^\s*$/', $line)) {
|
|
|
|
|
$last = false;
|
|
|
|
|
} elseif ($last !== false) {
|
2017-01-28 06:24:25 +01:00
|
|
|
|
$old_last_line = $lines[$last];
|
2018-01-10 04:33:36 +01:00
|
|
|
|
$lines[$last] = rtrim($old_last_line) . ($preserve_format ? "\n" . $line : ' ' . trim($line));
|
2017-01-28 06:24:25 +01:00
|
|
|
|
|
|
|
|
|
if ($line_number) {
|
|
|
|
|
$old_line_number = $line_map[$old_last_line];
|
|
|
|
|
unset($line_map[$old_last_line]);
|
|
|
|
|
$line_map[$lines[$last]] = $old_line_number;
|
|
|
|
|
}
|
|
|
|
|
|
2016-10-28 06:11:16 +02:00
|
|
|
|
unset($lines[$k]);
|
|
|
|
|
}
|
2016-12-04 01:11:30 +01:00
|
|
|
|
|
|
|
|
|
if ($line_number) {
|
|
|
|
|
$line_map[$line] = $line_number++;
|
|
|
|
|
}
|
2016-10-28 06:11:16 +02:00
|
|
|
|
}
|
2016-11-02 07:29:00 +01:00
|
|
|
|
|
|
|
|
|
$special = [];
|
2016-10-28 06:11:16 +02:00
|
|
|
|
|
2018-01-10 04:33:36 +01:00
|
|
|
|
if ($preserve_format) {
|
|
|
|
|
foreach ($lines as $m => $line) {
|
|
|
|
|
if (preg_match('/^\s?@([\w\-:]+)[\t ]*(.*)$/sm', $line, $matches)) {
|
|
|
|
|
/** @var string[] $matches */
|
|
|
|
|
list($full_match, $type, $data) = $matches;
|
|
|
|
|
|
|
|
|
|
$docblock = str_replace($full_match, '', $docblock);
|
|
|
|
|
|
|
|
|
|
if (empty($special[$type])) {
|
|
|
|
|
$special[$type] = [];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$line_number = $line_map && isset($line_map[$full_match]) ? $line_map[$full_match] : (int)$m;
|
|
|
|
|
|
|
|
|
|
$special[$type][$line_number] = rtrim($data);
|
2016-10-28 06:11:16 +02:00
|
|
|
|
}
|
2018-01-10 04:33:36 +01:00
|
|
|
|
}
|
|
|
|
|
} else {
|
|
|
|
|
$docblock = implode("\n", $lines);
|
|
|
|
|
|
|
|
|
|
// Parse @specials.
|
|
|
|
|
if (preg_match_all('/^\s?@([\w\-:]+)[\t ]*([^\n]*)/m', $docblock, $matches, PREG_SET_ORDER)) {
|
|
|
|
|
$docblock = preg_replace('/^\s?@([\w\-:]+)\s*([^\n]*)/m', '', $docblock);
|
|
|
|
|
/** @var string[] $match */
|
|
|
|
|
foreach ($matches as $m => $match) {
|
|
|
|
|
list($_, $type, $data) = $match;
|
|
|
|
|
|
|
|
|
|
if (empty($special[$type])) {
|
|
|
|
|
$special[$type] = [];
|
|
|
|
|
}
|
2016-10-28 06:11:16 +02:00
|
|
|
|
|
2018-01-10 04:33:36 +01:00
|
|
|
|
$line_number = $line_map && isset($line_map[$_]) ? $line_map[$_] : (int)$m;
|
2017-06-29 06:28:37 +02:00
|
|
|
|
|
2018-01-10 04:33:36 +01:00
|
|
|
|
$special[$type][$line_number] = $data;
|
|
|
|
|
}
|
2016-10-28 06:11:16 +02:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$docblock = str_replace("\t", ' ', $docblock);
|
|
|
|
|
|
|
|
|
|
// Smush the whole docblock to the left edge.
|
|
|
|
|
$min_indent = 80;
|
|
|
|
|
$indent = 0;
|
|
|
|
|
foreach (array_filter(explode("\n", $docblock)) as $line) {
|
2017-05-27 02:05:57 +02:00
|
|
|
|
for ($ii = 0; $ii < strlen($line); ++$ii) {
|
2016-10-28 06:11:16 +02:00
|
|
|
|
if ($line[$ii] != ' ') {
|
|
|
|
|
break;
|
|
|
|
|
}
|
2017-05-27 02:05:57 +02:00
|
|
|
|
++$indent;
|
2016-10-28 06:11:16 +02:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$min_indent = min($indent, $min_indent);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
$docblock = preg_replace('/^' . str_repeat(' ', $min_indent) . '/m', '', $docblock);
|
|
|
|
|
$docblock = rtrim($docblock);
|
|
|
|
|
|
|
|
|
|
// Trim any empty lines off the front, but leave the indent level if there
|
|
|
|
|
// is one.
|
|
|
|
|
$docblock = preg_replace('/^\s*\n/', '', $docblock);
|
|
|
|
|
|
2016-11-02 07:29:00 +01:00
|
|
|
|
return [
|
|
|
|
|
'description' => $docblock,
|
2017-05-27 02:05:57 +02:00
|
|
|
|
'specials' => $special,
|
2016-11-02 07:29:00 +01:00
|
|
|
|
];
|
2016-10-28 06:11:16 +02:00
|
|
|
|
}
|
2016-11-13 05:59:31 +01:00
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* @param array{description:string,specials:array<string,array<string>>} $parsed_doc_comment
|
2016-11-21 19:37:27 +01:00
|
|
|
|
* @param string $left_padding
|
2017-05-27 02:16:18 +02:00
|
|
|
|
*
|
2017-09-16 18:45:11 +02:00
|
|
|
|
* @return string
|
2016-11-13 05:59:31 +01:00
|
|
|
|
*/
|
|
|
|
|
public static function renderDocComment(array $parsed_doc_comment, $left_padding)
|
|
|
|
|
{
|
2018-04-13 01:42:24 +02:00
|
|
|
|
$doc_comment_text = '/**' . "\n";
|
2016-11-13 05:59:31 +01:00
|
|
|
|
|
|
|
|
|
$description_lines = null;
|
|
|
|
|
|
|
|
|
|
$trimmed_description = trim($parsed_doc_comment['description']);
|
|
|
|
|
|
|
|
|
|
if (!empty($trimmed_description)) {
|
2018-04-13 01:42:24 +02:00
|
|
|
|
$description_lines = explode("\n", $parsed_doc_comment['description']);
|
2016-11-13 05:59:31 +01:00
|
|
|
|
|
|
|
|
|
foreach ($description_lines as $line) {
|
2018-04-13 01:42:24 +02:00
|
|
|
|
$doc_comment_text .= $left_padding . ' *' . (trim($line) ? ' ' . $line : '') . "\n";
|
2016-11-13 05:59:31 +01:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if ($description_lines && $parsed_doc_comment['specials']) {
|
2018-04-13 01:42:24 +02:00
|
|
|
|
$doc_comment_text .= $left_padding . ' *' . "\n";
|
2016-11-13 05:59:31 +01:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if ($parsed_doc_comment['specials']) {
|
2017-09-16 21:08:11 +02:00
|
|
|
|
$last_type = null;
|
2017-09-16 21:00:50 +02:00
|
|
|
|
|
2016-11-13 05:59:31 +01:00
|
|
|
|
foreach ($parsed_doc_comment['specials'] as $type => $lines) {
|
2018-01-07 06:11:23 +01:00
|
|
|
|
if ($last_type !== null && ($last_type !== 'return' || $last_type !== 'psalm-return')) {
|
2018-04-13 01:42:24 +02:00
|
|
|
|
$doc_comment_text .= $left_padding . ' *' . "\n";
|
2017-09-16 21:08:11 +02:00
|
|
|
|
}
|
|
|
|
|
|
2016-11-13 05:59:31 +01:00
|
|
|
|
foreach ($lines as $line) {
|
2018-01-10 04:33:36 +01:00
|
|
|
|
$doc_comment_text .= $left_padding . ' * @' . $type . ' '
|
2018-04-13 01:42:24 +02:00
|
|
|
|
. str_replace("\n", "\n" . $left_padding . ' *', $line) . "\n";
|
2016-11-13 05:59:31 +01:00
|
|
|
|
}
|
2017-09-16 21:00:50 +02:00
|
|
|
|
|
2017-09-16 21:08:11 +02:00
|
|
|
|
$last_type = $type;
|
2016-11-13 05:59:31 +01:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2018-04-13 01:42:24 +02:00
|
|
|
|
$doc_comment_text .= $left_padding . ' */' . "\n" . $left_padding;
|
2016-11-13 05:59:31 +01:00
|
|
|
|
|
|
|
|
|
return $doc_comment_text;
|
|
|
|
|
}
|
2016-06-24 00:45:46 +02:00
|
|
|
|
}
|