request for clarification re: return types for generators

[SignpostMarv]

What's the appropriate docblock here?

function Foo() : Generator {
    yield from [
        ['foo', 123, ['foo' => ['bar', 'baz', null]]],
        ['bar', 456, ['foo' => ['bar', 'baz', null]]],
        ['baz', 789, ['foo' => ['bar', 'baz', null]]],
    ];
}

[JanTvrdik]

Depends on what you deem to be appropriate. All of the following should work.

• @return iterable
• @return Iterator
• @return Generator
• @return iterable<int, array>
• @return Iterator & iterable<int, array>
• @return Generator & iterable<int, array>
• @return iterable<int, array<int, mixed>>
• @return Iterator & iterable<int, array<int, mixed>>
• @return Generator & iterable<int, array<int, mixed>>

[SignpostMarv]

I was trying to do things like @return Generator<mixed[]>

[JanTvrdik]

This is currently intentionally unsupported. There is no obvious way that should work, so in order to make it work a consensus (ideally formally standardized consensus) would need to be reached.

---

By not obvious I specifically mean that Generator has a lot of generic parameters:

• key() return type,
• current() return type,
• getReturn() return type,
• send() parameter type and
• throw() parameter type.

It's not obvious which should be part of the generic signature, which should be required, what order should be used…

[SignpostMarv]

is re-purposing @throws too much of a stretch ?

[JanTvrdik]

I'm sorry, I don't understand how @throws could be used here in any meaningful way. Could you provide an example of what you had in mind?

[SignpostMarv]

/**
* @throws RuntimeException
*/
function Foo() : Generator {
    $inner = (function() : Generator {
        yield from [1,2,3];
    })();

    $inner->throw(new RuntimeException('foo'));

    return $inner; 
}

[SignpostMarv]

The reason I'm thinking it'd be a bit of a stretch is @throws is supposed to be a hint that "calling this method will throw an exception of this type in some circumstance", whereas here it'll be the Generator doing the throwing if the Generator is looped more than 3 times.

clarification:

$foo = Foo(); // @throws is inaccurate, since the generator hasn't been looped over.

$foo = Foo(); // @throws is inaccurate, since the generator hasn't been looped over *yet*.

$i = 0;
foreach ($foo as $bar) {
    if ($i >= 3) { // unless the generator is deeply analysed, it's a "maybe" that @throws is accurate
        break;
    }

    // ... some stuff with $bar

    ++$i;
}

foreach (Foo() as $bar) { // a direct foreach loop on Foo() with no conditional exit suggests the @throws is accurate
    // ... some stuff with $bar
}

[SignpostMarv]

@JanTvrdik I've given it some further thought; expand the scope of @method to be allowed to be used on methods that return Generator ?

i.e.

/**
* @method int key()
* @method array<int, string|int|array<string, array<int, string|null>>> current()
* @method mixed send(array<int, string|int|array<string, array<int, string|null>>> $value)
* @method bool getReturn()
* @method mixed throw(Throwable $exception)
*/
function Foo() : Generator {
    yield from [
        ['foo', 123, ['foo' => ['bar', 'baz', null]]],
        ['bar', 456, ['foo' => ['bar', 'baz', null]]],
        ['baz', 789, ['foo' => ['bar', 'baz', null]]],
    ];

    return true;
}

[JanTvrdik]

@SignpostMarv No, that does not work. You need to be able to declare the generator type in all places, where type can be, e.g. it must be possible to document a parameter which accept specific type of Generator.

[SignpostMarv]

@JanTvrdik since Generator is a "final" class, so there aren't (currently) any more specific types of Generator, meaning we can't do this:

/**
* @method int key()
* @method array<int, string|int|array<string, array<int, string|null>>> current()
* @method mixed send(array<int, string|int|array<string, array<int, string|null>>> $value)
* @method bool getReturn()
* @method mixed throw(Throwable $exception)
*/
class Bar extends Generator
{
}

/**
* @return Bar
*/
function Foo() : Generator {
    yield from [
        ['foo', 123, ['foo' => ['bar', 'baz', null]]],
        ['bar', 456, ['foo' => ['bar', 'baz', null]]],
        ['baz', 789, ['foo' => ['bar', 'baz', null]]],
    ];

    return true;
}

However, the following seems to pass psalm:^1.1 & phpstan:^0.9.2, whilst php-cs-fixer only complains about the phpdoc_to_comment rule:

namespace Test;

use Generator;
/**
* @method int key()
* @method array<int, string|int|array<string, array<int, string|null>>> current()
* @method mixed send(array<int, string|int|array<string, array<int, string|null>>> $value)
* @method bool getReturn()
* @method mixed throw(\Throwable $exception)
*/
use Generator as Foo;

function Bar() : Foo
{
    yield from [
        ['foo', 123, ['foo' => ['bar', 'baz', null]]],
        ['bar', 456, ['foo' => ['bar', 'baz', null]]],
        ['baz', 789, ['foo' => ['bar', 'baz', null]]],
    ];

    return true;
}

public function Baz() : Generator
{
    yield from [
        ['foo', 123, ['foo' => ['bar', 'baz', null]]],
        ['bar', 456, ['foo' => ['bar', 'baz', null]]],
        ['baz', 789, ['foo' => ['bar', 'baz', null]]],
    ];

    return true;
}

[JanTvrdik]

@SignpostMarv You're attempting to find a creative solution for a problem that already has a industry-wide trusted solution – generics. I would strongly advice against solving this problem with any other means.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.