Trying to write a custom type resolver

[gms8994]

I want to write a custom type resolver (specifically, uuid-string). I've written code that follows how larastan does it including the TypeNodeResolverExtension but checking if the string can be converted to a Uuid. I've added the services entry to the phpstan.neon file.

There are no errors anywhere, but phpstan doesn't actually seem to be performing my check. So I decided to try and write a test for the Type, but it seems pretty clear to me that I'm missing something. All of my code is trying its best to follow the Custom PHPDoc Types page and the Type Inference Testing page, but running phpunit for my type gives me that the string literal provided isn't a uuid-string.

Am I doing something wrong here?

TypeNodeResolverExtension

<?php

namespace App\Types;

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

class UuidStringTypeNodeResolverExtension implements TypeNodeResolverExtension
{
    public function resolve(TypeNode $typeNode, NameScope $nameScope) : ?Type
    {
        if ($typeNode instanceof IdentifierTypeNode && $typeNode->__toString() === 'uuid-string') {
            return new UuidStringType();
        }

        return null;
    }
}

UuidStringType

<?php

declare(strict_types = 1);

namespace App\Types;

use function count;
use Exception;
use PHPStan\TrinaryLogic;
use PHPStan\Type\CompoundType;
use PHPStan\Type\StringType;
use PHPStan\Type\Type;
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;

/**
 * The custom 'uuid-string' type class. It's a subset of the string type. Every string that passes the
 * Uuid::fromString($string) test is a valid uuid-string type.
 */
class UuidStringType extends StringType
{
    public function describe(\PHPStan\Type\VerbosityLevel $level) : string
    {
        return 'uuid-string';
    }

    public function accepts(Type $type, bool $strictTypes) : TrinaryLogic
    {
        if ($type instanceof CompoundType) {
            return $type->isAcceptedBy($this, $strictTypes);
        }

        $constantStrings = $type->getConstantStrings();

        if (count($constantStrings) === 1) {
            $uuid = null;

            try {
                $uuid = Uuid::fromString($constantStrings[0]->getValue());
            } catch (Exception $e) {
                // swallow
            }

            return TrinaryLogic::createFromBoolean($uuid instanceof UuidInterface);
        }

        if ($type instanceof self) {
            return TrinaryLogic::createYes();
        }

        if ($type->isString()->yes()) {
            return TrinaryLogic::createMaybe();
        }

        return TrinaryLogic::createNo();
    }

    public function isSuperTypeOf(Type $type) : TrinaryLogic
    {
        $constantStrings = $type->getConstantStrings();

        if (count($constantStrings) === 1) {
            $uuid = null;

            try {
                $uuid = Uuid::fromString($constantStrings[0]->getValue());
            } catch (Exception $e) {
                // swallow
            }

            return TrinaryLogic::createFromBoolean($uuid instanceof UuidInterface);
        }

        if ($type instanceof self) {
            return TrinaryLogic::createYes();
        }

        if ($type->isString()->yes()) {
            return TrinaryLogic::createMaybe();
        }

        if ($type instanceof CompoundType) {
            return $type->isSubTypeOf($this);
        }

        return TrinaryLogic::createNo();
    }

    /**
     * @param  mixed[]  $properties
     */
    public static function __set_state(array $properties) : Type
    {
        return new self();
    }
}

phpstan.neon

services:
    -
        class: App\Types\UuidStringTypeNodeResolverExtension
        tags:
            - phpstan.phpDoc.typeNodeResolverExtension
    

Unit test

<?php

namespace Tests\Unit\Types;

use PHPStan\Testing\TypeInferenceTestCase;

class UuidStringTypeTest extends TypeInferenceTestCase
{
    /**
     * @return iterable<mixed>
     */
    public static function dataFileAsserts(): iterable
    {
        // path to a file with actual asserts of expected types:
        yield from self::gatherAssertTypes(__DIR__ . '/data/UuidStringTypes.php');
    }

    /**
     * @dataProvider dataFileAsserts
     */
    public function testFileAsserts(
        string $assertType,
        string $file,
        mixed ...$args
    ): void {
        $this->assertFileAsserts($assertType, $file, ...$args);
    }

    public static function getAdditionalConfigFiles(): array
    {

        // path to your project's phpstan.neon, or extension.neon in case of custom extension packages
        return [__DIR__ . '/../../../phpstan.neon'];
    }
}

assertTypes

<?php

namespace AssertFunction;

use function PHPStan\Testing\assertType;

/**
 * @param uuid-string $uuid
 */
function foo($uuid) : void
{
    assertType('uuid-string', $uuid);
}

assertType('uuid-string', '7302f570-b4ff-499c-ba6b-e3d8c486ad3e');

[ondrejmirtes]

Hi, it'd be best if you publish a repository with this code and some failing test, so I can look into it and tinker with it. Thanks.

[ondrejmirtes]

Union and intersect results depend on what types say about each other in isSuperTypeOf.

That's also why they test the types in different order.

[gms8994]

Would it be possible to get some more explicit examples of how to actually test that a custom type resolver returns correctly for some given information? I'm just not able to see what it is that I'm doing/not doing to generate this correctly.

Additionally, I think that might be helpful for future developers trying to write custom type resolvers as well.

[ondrejmirtes]

Please just show what you're trying to do in a way of a failing test and I'll help you.

Purpose of custom type node resolver extensions is to convert phpdoc-parser AST into PHPStan Type objects.

[gms8994]

I think that's part of my problem - I'm not sure even how to write a failing test for this resolver. I want to ensure that strings typed as uuid-string are actually capable of becoming uuids. That way, test code doesn't try to put an integer1 in to that field, etc.

I appreciate you and the other phpstan developers. If I'm trying to go about this in the wrong way, please correct me so that I can do things properly.

[ondrejmirtes]

So you should probably write a test for CallMethodsRule. Write a RuleTestCase and do self::getContainer()->getByType(CallMethodsRule::class) in getRule() to write tests against this rule.

That will allow you to write rule-based tests to check what strings are accepted as uuid-string.

Or you can write unit tests that call the accepts() method and check the results.