param type can be a string but not class-string

[metaturso]

I was wondering if it's possible to annotate a method as accepting a string but not a class name obtained via the ::class constant, i.e. class-string.

class Foo
{
    /**
     * @param string & !class-string $entityName
     */
    function getEntity(string $entityName) { /** .. */ }
}

$foo = new Foo();
$foo->getEntity(EntityName::class); // invalid
$foo->getEntity('EntityName'); // legal

As far as I can see in the manual, phpstan 1.9 does not support this. Are there any workarounds?

[ondrejmirtes]

What's the use case for such a method? Right now you'd have to write a custom rule and check the argument type.

[metaturso]

The use case is to guard against improper calls to a legacy method that does some funky stuff with a Doctrine entity name. Is there a built-in rule that checks the format of a string? I'm not against writing writing a custom rule either.

Admittedly, this is shoe horning the type system into something it's not designed for, so I'm not surprised it's not supported out of the box, but I'm happy to make the compromise.

[ondrejmirtes]

I have an idea what could work for you, give me a few hours and I'll type it out 😊

[ondrejmirtes]

So the idea is that we're going to make a new custom PHPDoc type thanks to https://phpstan.org/developing-extensions/custom-phpdoc-types.

Step 1: Implement NonClassStringType

namespace App;

use PHPStan\Type\AcceptsResult;
use PHPStan\Type\StringType;
use PHPStan\Type\Type;
use PHPStan\Type\VerbosityLevel;

class NonClassStringType extends StringType
{

	public function describe(VerbosityLevel $level): string
	{
		return 'non-class-string';
	}

	public function acceptsWithReason(Type $type, bool $strictTypes): AcceptsResult
	{
		if ($type->isClassStringType()->yes()) {
			return AcceptsResult::createNo();
		}

		return parent::acceptsWithReason($type, $strictTypes);
	}

}

That's basically it. When implementing a custom type, we should make sure it plays well with other types in TypeCombinator::union() and TypeCombinator::intersect() (see https://phpstan.org/developing-extensions/type-system#type-normalization). That's done by overriding Type::isSuperTypeOf() method. These are the expected results:

• union(StringType, NonClassStringType) -> StringType
• union(NonClassStringType, ConstantStringType with a value that isn't a class name) -> NonClassStringType
• union(NonClassStringType, ConstantStringType with a value that is a class name) -> UnionType(NonClassStringType, ConstantStringType)
• union(ClassStringType, NonClassStringType) -> UnionType(ClassStringType, NonClassStringType)
• intersect(StringType, NonClassStringType) -> NonClassStringType
• intersect(NonClassStringType, ConstantStringType with a value that isn't a class name) -> ConstantStringType
• intersect(NonClassStringType, ConstantStringType with a value that is a class name) -> NeverType
• intersect(ClassStringType, NonClassStringType) -> NeverType

These should be tested in a similar way PHPStan internals are tested here https://github.com/phpstan/phpstan-src/blob/1.11.x/tests/PHPStan/Type/TypeCombinatorTest.php

Step 2: TypeNodeResolverExtension

This makes sure that non-class-string in a PHPDoc gets resolved into our NonClassStringType.

namespace App;

use PHPStan\Analyser\NameScope;
use PHPStan\PhpDoc\TypeNodeResolverExtension;
use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
use PHPStan\PhpDocParser\Ast\Type\TypeNode;
use PHPStan\Type\Type;
use function strtolower;

class NonClassStringTypeNodeResolverExtension implements TypeNodeResolverExtension
{

	public function resolve(TypeNode $typeNode, NameScope $nameScope): ?Type
	{
		if (!$typeNode instanceof IdentifierTypeNode) {
			return null;
		}

		$name = strtolower($typeNode->name);
		if ($name !== 'non-class-string') {
			return null;
		}

		return new NonClassStringType();
	}

}

And register this extension in phpstan.neon:

services:
	-
		class: App\NonClassStringTypeNodeResolverExtension
		tags:
			- phpstan.phpDoc.typeNodeResolverExtension

Step 3: Test that it works

With all above, with a function marked with this type, we should observe the correct behaviour:

/** @param non-class-string $name */
function sayHello(string $name): void
{
}

sayHello('blah blah'); // OK
sayHello(\stdClass::class); // Error reported

Let me know how it turned out!

[metaturso]

Awesome, thanks for the explanation and the working example.