The export functions are not yet implemented, because it says it has to see what reflection outputs. Doesn't the getDocComment function just return the comments, as found in the php file?

What are you planning to do with the export, let the tags return the line without the * (so just @param int $i for example), and let the docblock itself just loop through the tags and call the export function, and place the lines in the docblok comment style?

Are you planning on implementing that, or would you like to let me make a PR?

In v4.3.2 calling \phpDocumentor\Reflection\DocBlockFactory::create for this phpDoc:

/**
 * @return array<string, Channel>
 */

will cause a RuntimeException from \phpDocumentor\Reflection\TypeResolver::parseTypes:263 with message 'A type is missing in a collection expression'.

The bug seems to be in \phpDocumentor\Reflection\DocBlock\Tags\Return_::create:50. This split:

$parts = preg_split('/\s+/Su', $body, 2);

doesn't take generics into account. array<string, is being read as type and Channel> becomes the description. Removing the space after comma solves the problem.

I've tried to determine if those spaces are actually a valid syntax and it seems like they kind-of-are:

1. Grammar on phpdoc.org doesn't allow for them (on a side note, the "phpDocumentor" link in top left leads to a 404)
2. PSR-5 grammar currently doesn't support generics too
3. However the PSR-5 draft did allow for them before Oct 16, 2018 and spaces were allowed.
4. The file that throws exception phpdocumentor/type-resolver/src/TypeResolver.php does itself use spaces on lines 64-65:

   /**
    * @var array<string, string> List of recognized keywords and unto which Value Object they map
    * @psalm-var array<string, class-string<Type>>
    */
   

So the implementation seems to be inconsistent with grammar in PSR and usage in phpDocumentor/TypeResolver.

I use the PHPUnit\Framework\TestCase notation instead of PHPUnit_Framework_TestCase while extending our TestCases. This will help us migrate to PHPUnit 6, that no longer support snake case class names.

I just need to bump PHPUnit version to ^4.8.35, that support this namespace.

The only problem is that I could not apply this changes to the composer.lock file. If someone can help me, I'd be grateful :smile:

Psalm: switch from Phive to Composer

This switches the installation method for Psalm from Phive to Composer, while still using a Phar file for running Psalm.

Includes:

• Removing Psalm from the Phive configuration.
• Adding Psalm to the Composer configuration. Includes upgrading from version 3.11.2 to version 4.8.1.
• Adjusting the script used in the Makefile. 👉 Please verify and test this as things work differently on different OS-es and this should work for you.
• Adjusting the GH Actions script to use the Composer installed version of Psalm.

Note: due to the committed composer.lock file, Psalm will not automatically upgrade when newer versions are available.

Refs:

• https://github.com/vimeo/psalm/releases
• https://github.com/psalm/phar/releases

Utils::pregSplit: limit is not nullable

Correctly flagged by Psalm:

ERROR: PossiblyNullArgument - src\Utils.php:50:53 - Argument 3 of preg_split cannot be null, possibly null value provided (see https://psalm.dev/078)
        $parts = php_preg_split($pattern, $subject, $limit, $flags);

The $limit argument of the PHP native preg_split() function is not nullable.

Ref: https://www.php.net/manual/en/function.preg-split

Tags::__toString(): remove redundant type casts

Psalm flags these type casts as redundant:

ERROR: RedundantCastGivenDocblockType - src/DocBlock/Tags/Author.php:80:23 - Redundant cast to string given docblock-provided type (see https://psalm.dev/263)
        $authorName = (string) $this->authorName;

ERROR: RedundantCastGivenDocblockType - src/DocBlock/Tags/Example.php:150:21 - Redundant cast to string given docblock-provided type (see https://psalm.dev/263)
        $filePath = (string) $this->filePath;

ERROR: RedundantCastGivenDocblockType - src/DocBlock/Tags/Link.php:74:17 - Redundant cast to string given docblock-provided type (see https://psalm.dev/263)
        $link = (string) $this->link;

ERROR: RedundantCastGivenDocblockType - src/DocBlock/Tags/Method.php:228:23 - Redundant cast to string given docblock-provided type (see https://psalm.dev/263)
        $methodName = (string) $this->methodName;

I have verified each and can confirm that these are redundant. They are probably a left-over from the time when the __construct() method in these classes did not yet have type declarations.

Tags/Return: remove redundant condition

Psalm flags this condition as redundant:

ERROR: RedundantCondition - src/DocBlock/Tags/Return_.php:62:48 - "" can never contain non-empty-lowercase-string (see https://psalm.dev/122)
        return $type . ($description !== '' ? ($type !== '' ? ' ' : '') . $description : '');

Based on the statement in the line above - $type = $this->type ? '' . $this->type : 'mixed'; -, Psalm is correct and the $type variable can never be an empty string.

Psalm: suppress two notices

The current version of Psalm flags the following issues:

ERROR: InvalidReturnType - src\Utils.php:44:16 - The declared return type 'array<array-key, string>' for phpDocumentor\Reflection\Utils::pregSplit is incorrect, got 'list<list<int|string>|string>' (see https://psalm.dev/011)
     * @return string[] Returns an array containing substrings of subject split along boundaries matched by pattern

ERROR: InvalidReturnStatement - src\Utils.php:55:16 - The inferred type 'list<list<int|string>|string>' does not match the declared return type 'array<array-key, string>' for phpDocumentor\Reflection\Utils::pregSplit (see https://psalm.dev/128)
        return $parts;

I'm suggest ignoring this as list isn't an officially supported type.

After this PR, there is still one issue remaining.

Argument 4 of preg_split expects 0|1|2|3|4|5|6|7, parent type int provided (see https://psalm.dev/193)

I believe this issue is for the phpDocumentor\Reflection\Utils class and expects the pregSplit() method to apply input validation to the value received for $flags before passing it off to the PHP native preg_split() function.

IMO that's taking things a little too far as PHP will handle this internally without errors. Want me to add it to the list of issues to be ignored ? See: https://3v4l.org/NdDRK

Side-note: the weird thing is that this issue does show up in CI, but with the same PHP + Psalm Phar version, I cannot reproduce this locally.

In this PR I'm working on an attempt to replace the regex-based parsing in each tag with a more battle tested parser that allows us to support all modern types like tools as phpstan and psalm are defining.

• [x] implement param tag
• [x] implement method tag
• [x] implement return tag
• [x] implement var tag
• [x] implement property tag
• [x] introduce callable params
• [x] introduce callable return type
• [ ] document new features
• [ ] document new architecture
• [x] deprecate replaced tag factories
• [x] implement constant types

BC promise

This library has existed for many years and is used in many projects to get information from docblocks. We can do this fast, and reliably. The new implementation should be introduced without any BC breaks. Only changed and improved tags.

The current approach allows external consumers to create tags based on instanciated factories. Not just the static factory methods as we knew them before. This will enable us to introduce more complex logic in the factories and add extra dependencies. Which as not fully possible in the past.

<?php

require "vendor/autoload.php";

$comment = '/**
 * @return (string|Apple)
 */';

$block = new \phpDocumentor\Reflection\DocBlock($comment);
var_dump($block->getTagsByName("return")[0]->getType()); // \(string|\Apple)

$block = new \phpDocumentor\Reflection\DocBlock($comment, new \phpDocumentor\Reflection\DocBlock\Context("A"));
var_dump($block->getTagsByName("return")[0]->getType()); // \A\(string|\A\Apple)

Generic types are parsed incorrectly as well; and there may be other issues. Since PSR-5 is still a draft, I didn't expect 100% compliance, but the values returned now are pretty useless. Not getting correctly parsed types blocks my project, so I'd gladly help out with this.

The current API for getting types is getType: string and getTypes: Type\Collection (the latter basically being string[]). Unfortunately, PSR-5's types are more complicated... As a consumer I want an API that allows me to handle complex types. Something like:

interface TypeInterface
class ScalarType implements TypeInterface {
    public function getType() // 'string', 'int', etc.
}
class ArrayOfType implements TypeInterface {
    public function getItemType() // TypeInterface of the items
}
class GenericType implements TypeInterface {
    public function getTemplateType()
    public function getParameterTypes()
}
...

I think this belongs in the ReflectionDocBlock library, but I'd like some feedback before I implement this.

Contexts are necessary for factories to resolve QSEN into FQSENs based on partial namespaces and namespace aliases. These provide DocBlocks with the namespace name and namespace aliases.

The new ContextFactory will enable third parties who don't use phpDocumentor's Reflection component to construct a Context based on a class reflector or namespace name (and file contents).

I have added a testcase that currently fails, although it shouldn't. There seems to be a problem with @method annotations, when the method name gets a little bit longer. According to Regex101 it seems to result in a catastrophic backtrack, which gives me the feeling that this regex is too complicated. I tried to simplify it, but couldn't find any solution that generally worked.

The problem is this regex, if anybody has an idea how to improve it, I am happy to implement it.

When I remove last tag, extra spaces are added, that mailform the docblock. Especially with space after asterix: {$indent}* \n.

I fixed it by condition on value in $text.

See tests for more

Build errors: ⇾ https://travis-ci.org/github/JetBrains/phpstorm-stubs/builds/723069982

Pull request where I try to add "&" and "..." in the docs: ⇾ https://github.com/JetBrains/phpstorm-stubs/pull/892

This change is 

This simple fix for ensuring the existence of the 'args' key.

With PHP 7.4 on Linux and Windows, it fails without it. Weird thing is that it doesn't break on MacOSX.

See it live here: https://github.com/ecphp/cas-bundle/actions/runs/36937260

In issue https://github.com/phpDocumentor/phpDocumentor/issues/3378, there was some confusion because the Author tag does not support a description. When the StandardTagFactory encounters a situation where an InvalidTag is generated, it would be nice if it could ask the Tag class what the expected format is and a link to the documentation; and include that in the InvalidTag so that phpDocumentor can provide better error messages in the error report

Let's say I have the following PHP Code

/**
 * This is a global var.
 *
 * @see $varname
 */
$varname = "test";

/**
 * This is a class
 *
 * @see $varname
 */
class Base
{
}

When I try to parse it

$factory  = \phpDocumentor\Reflection\DocBlockFactory::createInstance();
$docblock = $factory->create($docComment);

Ir crashes the PHP engine in version 8.0.6 and 8.1.6.

The DescriptionFactory class is replacing all instances of {} with }, and does not (and cannot) revert them back to {} upon render. As a result, any instance of {} in any docblock is incorrectly changed.

This happens here. The only way I can see to get around it is to create a new DescriptionFactory class, which contains the identical code to this class, with the exception of that one line.

I request that this library either:

1. Properly substitute the {} back in during render
2. Provide an easier way to bypass replacing {}.

I'm happy to submit the fix myself if the maintainers would like to weigh in on their preference. When I removed the substitution of {}, I have found no adverse effects, so I may need more guidance as to why this is necessary before submitting a change.

Thanks for this great library!

Related: https://github.com/phpDocumentor/ReflectionDocBlock/issues/274

Test output before :

There was 1 failure:

1) phpDocumentor\Reflection\DocBlock\DescriptionFactoryTest::testDescriptionCanParseStringWithInlineTagAndBraces
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
-'This description has a {@link http://phpdoc.org/ This contains {braces} }'
+'This description has a {@link http://phpdoc.org/ This contains {braces}} }'

Test output after :

There was 1 failure:

1) phpDocumentor\Reflection\DocBlock\DescriptionFactoryTest::testDescriptionCanParseStringWithInlineTagAndBraces
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
-'This description has a {@link http://phpdoc.org/ This contains {braces} }'
+'This description has a {@link http://phpdoc.org/ This contains {braces}}

The new test case still doesn't pass because the trailing space at the end of the inline tag got cleared in StandardTagFactory::create() which seems to be intended behavior (removing it solves the issue but also breaks two other tests). Discussion / guidance needed in order to move forward.

Given the following test case, our Description doesn't work as expected with nested braces in inline tags.

   /**
     * @uses \phpDocumentor\Reflection\DocBlock\Description
     * @uses \phpDocumentor\Reflection\DocBlock\Tags\Link
     * @uses \phpDocumentor\Reflection\DocBlock\Tags\BaseTag
     * @uses \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
     * @uses \phpDocumentor\Reflection\Types\Context
     *
     * @covers ::__construct
     * @covers ::create
     */
    public function testDescriptionCanParseStringWithInlineTagAndBraces() : void
    {
        $contents   = 'This description has a {@link http://phpdoc.org/ This contains {braces} }';
        $context    = new Context('');
        $tagFactory = m::mock(TagFactory::class);
        $tagFactory->shouldReceive('create')
            ->twice()
            ->andReturnValues(
                [
                    new LinkTag('http://phpdoc.org/', new Description('This contains {braces}')),
                ]
            );

        $factory     = new DescriptionFactory($tagFactory);
        $description = $factory->create($contents, $context);

        $this->assertSame($contents, $description->render());
        $this->assertSame('This description has a %1$s', $description->getBodyTemplate());
    }