[FPDP] Format preserving doc printer

[TomasVotruba]

Mirror of nikic/PHP-Parser#344, just for phpdoc

It might be worth to create https://github.com/phpstan/phpdoc-parser which actually preserver format

Here is knowledge snippet from php-parser: nikic/PHP-Parser#487

Related Issues

• No Rector applied, but Symfony Rout annotation modified in wrong way #3932

[staabm]

It might be worth to create phpstan/phpdoc-parser which actually preserver format

what does this mean? do you have a plan/a idea of what needs to be done?

[TomasVotruba]

We need a new package that builds on https://github.com/phpstan/phpdoc-parser,
and adds printing the docblock back to code.

I don't have any ETA on that.

[staabm]

Whats the job of this package? What should it provide on top of what phpstan/phpdoc-parser already can?

[TomasVotruba]

Whats the job of this package?

Current job of existing package is getting docs block to types.

E.g.

/**
 * @var int
 */

↓

Very rougly:

use PHPStan\PhpDocParser\VarTagNode;
use PHPStan\PhpDocParser\IntegerTypeNode;

new VarTagNode(new IntegerTypeNode());

The problem is, all these cases:

/**
 * @var int
 */

/**
 * @var integer
 */

/**
 *  @var     int
 */

Are printed back as:

/**
 * @var int
 */

What should it provide on top of what phpstan/phpdoc-parser already can?

Keep the format in it's original form.

/**
 * @var integer
 */

↓

/**
 * @var integer
 */

and

/**
 *  @var     int
 */

↓

/**
 *  @var     int
 */

[TomasVotruba]

Work in progress https://github.com/rectorphp/phpdoc-parser-printer

[TomasVotruba]

Big jump forward via:

• [PhpDocParser] Make use of native attributes #5841
• and native attribute support in phpdoc-parser Allow nodes to have custom attributes phpstan/phpdoc-parser#65 🎉

[TomasVotruba]

We've just added another jump with static doctrine annotatoin parsing #5974

Before, to parse class-based annotations the https://github.com/doctrine/annotations was needed:

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 */
class Product
{
}

That required the Doctrine\ORM\Mapping\Entity class to be present and autoloaded. That kind-of kills the advantage of static reflection added in Rector 0.10 for annotations.

Further more, this approach required every such annotation to have own php doc node class and factory to make it. In total, Rector contained ~50 such classes + factories.

The #5974 PR solves this using https://github.com/phpstan/phpdoc-parser and copying the doctrine/annotation behavior 1:1 without autoloading used classes and constants.

Now, Rector is now using static for annotations making it more accessible to wide PHP comunity 🤗 👍

[TomasVotruba]

Since last 2 comments and full month of testing we have exactly 0 reported issues with docblocks 👍

I think we can close this issue as resolved 🙂