is there any way to preserve phpdoc?

[steamboatid]

dear all,

let's assume that the phpdoc is valid and has been checked.
i want to upgrade unmaintained legacy php code into --at least-- php8.1 fully comply code, especially on the function arguments and function return value.

current result,
rector able to add return value types and the arguments types to the functions, but it also remove the phpdoc.

expected result,
add return value types and the arguments types to the functions, but preserve the phpdoc.

fyi,
i also use phpcbf to meet the code style standards.

many thanks in advance

[TomasVotruba]

Hi, I'm not sure I understand... Could you share minimal example code snippet with demo?
https://getrector.org/demo

[TomasVotruba]

That's expected behavior, as the type is now declared in PHP. Rector only preserves docblocks, if they contain more value like types arrays or comments.

To keep it in original, skip the rules responsible for the change.

[steamboatid]

it is docblocks.
it's there for documentation.

i've tried to use couple of skip rules combinations, but no luck so far.
below is the full skip rules, i dont use them all at once, rather than using it one by one, then combine 2-3 of them.

$rectorConfig->skip([
\Rector\Php54\Rector\Array_\LongArrayToShortArrayRector::class,

\Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector::class,
\Rector\CodeQuality\Rector\If_\SimplifyIfNullableReturnRector::class,
\Rector\CodeQuality\Rector\If_\SimplifyIfNotNullReturnRector::class,

\Rector\CodingStyle\Rector\ClassMethod\ReturnArrayClassMethodToYieldRector::class,
\Rector\DeadCode\PhpDoc\TagRemover\ReturnTagRemover::class,
\Rector\DeadCode\PhpDoc\TagRemover\VarTagRemover::class,

\Rector\DeadCode\Rector\ClassLike\RemoveAnnotationRector::class,
\Rector\DeadCode\Rector\Node\RemoveNonExistingVarAnnotationRector::class,
\Rector\TypeDeclaration\PhpDocParser\NonInformativeReturnTagRemover::class,

\Rector\TypeDeclaration\Rector\FunctionLike\ReturnTypeDeclarationRector::class,
\Rector\TypeDeclaration\Rector\FunctionLike\ParamTypeDeclarationRector::class,
]);

[samsonasik]

You have the following use:

use Rector\Php81\Rector;

which make non -fqcn not skipped:

	$rectorConfig->skip([
		Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector::class,
		Rector\Php54\Rector\Array_\LongArrayToShortArrayRector::class,
	]);

as it will read from Rector suffix:

You can remove:

-use Rector\Php81\Rector;

or ensure it fqcn with \ prefix:

	$rectorConfig->skip([
-		Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector::class,
+		\Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector::class,
-		Rector\Php54\Rector\Array_\LongArrayToShortArrayRector::class,
+		\Rector\Php54\Rector\Array_\LongArrayToShortArrayRector::class,
	]);

to make skipped rules applied.

[TomasVotruba]

You can always see rules responsible for the change under the modified file. In this case it's these 2:

• https://getrector.org/demo/2be9b027-8b27-4566-8ff1-c2cdae48cbd3

[github1maxserv]

A use case to prevent very specific phpdoc blocks from being removed:

In TYPO3 v11 the Extbase property mapping is not fully capable to read native (scalar) types.
protected int $notApplicableRooms = 0;
The Symfony 5 PropertyInfoExtractor seems to use the property name and detects (using an Inflector class) that the name is plural.
The conclusion is that the property is an array. The Extbase property mapper doesn't support arrays. and thus the value from the database is not mapped to the property.

If you add a phpdoc block the property is correctly mapped and filled with the database value

/**
 * @var int $notApplicableRooms
 */
protected int $notApplicableRooms = 0;

If one could add something like @rectorKeepPhpdocBlock (or a more generic variant) to keep specific phpdoc blocks rector could be used for automated checks in such cases.

I'm aware that these are edge cases and that the problem should be solved upstream, but in reality such changes won't make it to older releases of software and thus tools like rector could handle these cases somehow.