This adds support for the @template tag, with the following syntax:

@template name [of boundType] [description]

Examples:

@template T
@template T of DateTime the value type
@template T of DateTime
@template T the value type

Related: https://github.com/phpstan/phpstan/pull/1692

Semantically, @template declares that the given name referer to a templated type in the scope of the related code object. The actual type is decided by the user of the code; boundType defines a constraint on this type.

This PR adds support for parsing type projections (phpstan/phpstan#3290) which I'd like to implement in PHPStan. Type projections are a way of declaring the variance of a type parameter at the site of use rather than at the site of its declaration (via @template-covariant). This allows you to have the type parameter in an incompatible position in the generic class, and only prevents you from using it where the projection is used.

Type projection can be created in the type argument position of a generic type by using either:

• a variance keyword ('covariant' or 'contravariant') followed by the projected type, which denotes an out- or in-projection, respectively,
• an asterisk, which denotes a star projection, or

/**
 * @param Box<covariant Animal> $covariant
 * @param Box<contravariant Cat> $contravariant
 * @param Box<*> $star
 */

The choice of the variance keywords favours consistency: while Kotlin uses in and out which might arguably be more intent-revealing, PHPStan already uses @template-covariant in a similar position, so I say let's stick with it.

One thing I'm not sure about is whether Foo<covariant> should throw a parse error (as currently implemented), or whether it should create an IdentifierTypeNode('covariant'). The former is potentially a BC break if somebody has a class named covariant in their code, and however unlikely it seems, you can always break somebody's build 🤔

I didn't want to touch \PHPStan\PhpDocParser\Parser\TokenIterator, which I think could be refactored to properly implement the \Iterator interface. That seemed like a task of its own.

This loops over the tokens passed to \PHPStan\PhpDocParser\Parser\PhpDocParser::parseDeprecatedTagValue and builds the entire message.

According to https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/param.html, the type may be omitted. This is especially useful in PHP 8 applications, which can almost fully typehint all arguments. The type in the PHPdoc in this case is redundant and may only lead to out-of-sync types.

PHPstorm and Psalm already appear to support this. However, this is not yet the case with PHPstan: https://phpstan.org/r/691a2424-e087-45a0-a9ce-774a57f887ec

(fyi, we're about to remove the types in Symfony, which is why I checked support in the popular static analysis libraries)

Our CI started to crash with removed endlines: https://github.com/symplify/symplify/pull/4148/commits/36230195b068dffdc0c269e12fc094f45d176963

Any ideas what is causing it and how to fix it?

Adds support for parsing array shapes (object-like arrays).

Examples:

array{'foo': int, "bar": string}
array{0: int, 1?: int}
array{int, int}
array{foo: int, bar: string}

Keys can be single quoted strings, double quoted strings, integers, or identifiers (represented as ConstExprStringNode, ConstExprIntegerNode, IdentifierTypeNode).

They can be marked optional with a ? before the key and the :.

They can be omitted entirely.

Values can be any type, including nullable types or nested array shapes.

Are there any plans to support the kinds of shapes that psalm supports in docblocks?

i.e. array<class-string<Foo>, array<int, class-string<Bar>>> ?

What's the appropriate docblock here?

function Foo() : Generator {
    yield from [
        ['foo', 123, ['foo' => ['bar', 'baz', null]]],
        ['bar', 456, ['foo' => ['bar', 'baz', null]]],
        ['baz', 789, ['foo' => ['bar', 'baz', null]]],
    ];
}

Hi,

It seems phpdoc-parser tries to use the files' namespace even for native types. Not sure how to best explain this, let me do my best.

There this really odd issue on the Safe library where phpstan + larastan would throw an error on any library using the Safe package. At first I thought the error was on larastan but after they fixed what I thought was the root cause, the error was still there, so after some more debugging (thank $DEITY for xdebug) I found out that the problem was on the library (or on phpdoc-parser, it could be fixed on both places).

Long story short, the library is basically a bunch of files redeclaring native php functions, the issue is that whenever there's a phpdoc on one of their files using @param array or @return array, since all function files are namespaced under Safe, the parser tries to use the type Safe\array, which unfortunately has a PSR4 match on their array.php file. The bug appeared when the library was used together with larastan because larastan checks if any of the parameters is a subclass of one of Laravel's Eloquent classes on one of their extensions, triggering the second loading of the same file (doing (new ObjectType(Model::class))->isSuperTypeOf(new ObjectType($nameScope->resolveStringName('Safe\array')))->yes()). I (erroneously) thought that adding \ to the array will force it to be on the global namespace but it turns out that \array is not a valid type for phpstan.

Anyway, I believe the native types from PHP should take precedence when being parsed (same than the actual PHP behaviour), maybe with some sort of list to be compared with when parsing the types from @param and @return, although I'm not fully familiar with the implementation to make a proper suggestion.

Please, let me know if there are any doubts so I can explain further, not my best day today :stuck_out_tongue:

Possible fix for https://github.com/phpstan/phpstan/issues/2497

Hey there, great library, fantastic work to all involved. So, like a lot of folks I'm excited about using array shapes, but without multiline syntax it doesn't really seem practical.

I haven't done much with parsers since my school days of long ago, and I was told that you have previously dismissed this idea as not feasible, so please tell me what I'm doing wrong.

Having this phpDoc:

    /**
     * Parses and builds AST for the given Query.
     *
     * @return \Doctrine\ORM\Query\AST\SelectStatement |
     *         \Doctrine\ORM\Query\AST\UpdateStatement |
     *         \Doctrine\ORM\Query\AST\DeleteStatement
     */

PHPStan 0.9.2 errors with:

  234    PHPDoc tag @return has invalid value (\Doctrine\ORM\Query\AST\SelectStatement |): Unexpected token "\n     *", expected TOKEN_IDENTIFIER at offset 117

This is currently used in Doctrine: https://github.com/doctrine/doctrine2/blob/2de6c807c8617b888bbb9da8b0908648432b3673/lib/Doctrine/ORM/Query/Parser.php#L227

Is this by design, bug or simply overseen case?

Bug report

Since PHP 8.1, it is possible to use new as default parameters ("new in initializers" RFC).

PHPStan gets it perfectly, but things stop working once we move them to docblocks, explicitly the @method docblock (see example).

Code snippet that reproduces the problem

https://phpstan.org/r/5d0cdcbb-5c11-4483-90b0-b95986f92bc2

Expected output

Since PHPStan understands the "new in initializers" in the code, I guess that this is a missed use-case instead of an actual bug, but I didn't know where to report it.

Did PHPStan help you today? Did it make you happy in any way?

Every. single. day.

Thanks for this amazing tool!

Like normal methods the method tag might return by reference. This fix introduces the support of reference return types. However in a real world implementation it not very likely one would ever mix reference return types with none reference return types. If even possible using php __call.

fixes #158

The param requires a paramname, however, this could be omitted when the param tag is describing just a single argument method or all other params are adequately documented. For example:

/**
 * @param int
 * /
 public function foo($arg): void 
{}

/**
 * @param int $arg
 * @param int Optional description
 * /
 public function foo($arg, $second): void 
{}

I do see this as edge cased, but it makes makes more sense when you align this with other tags for example the @var tag. Which has the same behavior.

class Foo {
    /** @var int */
   public $bar
}

class Foo {
    /** 
     * @var int
     * @var string $foo
     */
   public $bar $foo
}

I'm working on a pr to support this.

A few times a day, I am getting following exception in symfony project. Clearing symfony cache fixes it - any ideas what could be the issue since it's random?

Uncaught Error: Class "PHPStan\PhpDocParser\Parser\PhpDocParser" not found

Uncaught PHP Exception Symfony\Component\ErrorHandler\Error\ClassNotFoundError: "Attempted to load class "PhpDocParser" from namespace "PHPStan\PhpDocParser\Parser". Did you forget a "use" statement for another namespace?" at /home/flies/workspace/sf5/homologacja/vendor/symfony/property-info/Extractor/PhpStanExtractor.php line 67

The MethodTagValue doesn't contain an property returnsReference. This is not a very common option to use but we found a few of them in the wild.

Full blown example will look like this:

/** @method static Type &myMethod() description here */

I will provide a PR later when ready with other things.