an array shape of array{foo:int} would be treated similarly to a typed class, e.g.

class Thing {
    /**
    * @var int
    */
    public $foo = 0;
}

or in 7.4 as

class Thing {
    public int $foo = 0;
}

With the example class above, one would expect to receive an error if doing $obj->foo = 'bar';, as 'bar' is not the expected type for Thing::$foo.
As it applies to @param & @return,

/**
* @param array{foo:int}
*
* @return array{foo:int, bar:string}
*/
function ArrayFunc(array $arr) : array {
	$arr['foo'] = 'bar'; // pretend this isn't here for $arrThree
	$arr['bar'] = (string) $arr['foo'];
	
	return $arr;
}

$arrOne = ArrayFunc([]);
$arrTwo = ArrayFunc(['foo' => 'bar']);
$arrThree = ArrayFunc(['foo' => 1, 'baz' => 2]);

echo gettype($arrThree['baz']);

The function body should trigger an error because a string is being assigned to an array-shape member that is typed as as an int
$arrOne should trigger an error because the input array does not match the expected shape at all
$arrTwo should trigger an error because while the member structure matches the array shape (foo being present in the array shape and the input), the member value does not match the array shape.
The input for $arrThree should most likely not trigger an error (refefer to psalm's implementation maybe?), as while baz is not a member defined in the array shape it's not explicitly excluded.
Since the return signature of ArrayFunc() defines an array shape that does not include the member baz, calling gettype($arrThree['baz']); should trigger an error because despite the function body not removing unlisted members, the return type does not list baz as a member.

class-string, and class-string<T> are useful for handling static methods and object instantiation.

For example,

function Foo(string $className) : DateTimeInterface {
    if ( ! is_a($className, DateTimeInterface::class, true)) {
        throw new InvalidArgumentException('Not an implementation of  DateTimeInterface!');
    }

    // at this point, $className is implicitly typed as `class-string<DateTimeInterface>`

    if ( ! is_a($className, DateTime::class, true) && ! is_a($className, DateTimeImmutable::class)) {
        throw new InvalidArgumentException('Not a supported implementation of  DateTimeInterface!');
    }

   // at this point, $className is probably implicitly typed as `class-string<DateTime|DateTimeImmutable>`

    return new $className();
}

In the function body, if we were to add @param class-string<DateTimeInterface>, the first if condition should trigger one of those "redundant docblock" errors, whereby the docblock says a thing and a condition includes a redundant check.

If the second if condition were not present, the invocation should trigger an error because one obviously cannot instantiate an interface- however from a static analysis perspective both conditions can be eliminated with class-string:

/**
* @param class-string<DateTime|DateTimeImmuteable> $className
*/
function Bar(string $className) : DateTimeInterface {
    return new $className();
}

The docblock would allow a supporting analyser to trigger an error if anything other than DateTime, DateTimeImmuteable, or a non-abstract child class thereof were passed to Bar().
Such an analyser would be able to see that both type supplied to the body of the class-string definition implement DateTimeInterface.

/**
* @param class-string<DateTime|DateTimeImmuteable> $className
*/
function Baz(string $className) : DateTimeImmuteable {
    return new $className();
}

The previous example should trigger an error, since the docblock allows both DateTime::class and DateTimeImmutable::class to be supplied, but as the function body does not perform any conditional operations, only one of these matches the return type.

In the context of phpstan/phpstan-phpunit, array shapes and class-string<T> support (explicit via @param & @return) would mean being able to drop redundant checks from test cases, ala DaftObjectImplementationTest::testConstructorArrayKeys()- where one has to explicitly check a string refers to a class or interface then mark a test as skipped because static analysis can't pick up that a @param or @dataProvider return type should only contain class/interface strings of a specific type.

Additionally, one would hope a supporting analyser would be able to imply class-string by decorating a variable's type in conditional branches, i.e. is_a($foo, DateTimeInterface::class, true); would implicitly flag $foo as being class-string<DateTimeInterface>

@muglug could likely give a more accurate breakdown

request re: shapes #21

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions