Start a Composer repository with generic type-definitions

[mindplay-dk]

I wrote the preliminary pseudo-code with ambient type-definitions and overloads for generic type-hinting.

I'd like to start a repository with a Composer package with stubs for type-hinting - this would make it possible to simply require that package in Composer projects and include it for IDE support, rather than expecting IDE vendors to write or include the definitions with their software.

Since it's going to be a sizeable chunk of ambient definitions (to support all standard and SPL types) it makes sense to keep these out of the documentation itself, I think? And with potential for releasing updates, and accepting PRs, without affecting the versioning of the spec itself, if we make mistakes.

I'd like to call on @mvriel, @jacobsantos and @pulyaevskiy to comment, since you've been active participants in the generics discussion :-)

(Of course, I'm happy to start the repository and get it going, if you guys like the idea.)

[pulyaevskiy]

In general, I think I like this idea. Though since everything in this repository would be just "pseudo-code", how would it look like? PHP file with only docblocks in it? Like:

<?php
/**
 * array<integer|string, TValue>
 * array extends array<integer|string, mixed>
 * array<TValue> extends array<integer|string, TValue>
 */

Not sure if IDEs will be able to just pick up these definitions, honestly. But maybe you have better idea in mind.

[jacobsantos]

I agree with @pulyaevskiy that it will be difficult to implement, but I think @mindplay-dk is saying that it doesn't have to be valid PHP and that the parsing would have to be custom?

From my understanding, the way that IDEs support internal functions is to stub those functions in PHP files with documentation. This is similar to how other IDEs for other languages work.

I will say, that as a person who wants to write a tool that matches the specification. This would be really awesome to support the standard. Even if it is invalid PHP syntax, if it is parsable, then I think the merit is worth doing.

It should be easy I think, because the parser should match what is in the standard anyway.

[mindplay-dk]

I think @mindplay-dk is saying that it doesn't have to be valid PHP and that the parsing would have to be custom?

No, these would be valid PHP with valid doc-blocks.

The exception may be array which isn't a class and can't be described that way, but for all other classes, interfaces, etc. you can write valid stubs.

That's how e.g. Storm currently supports all the built-in types and functions - it has valid PHP stubs with valid doc-blocks, and it loads and parses these the same way it loads and parses your code.

[jacobsantos]

@mindplay-dk Okay. Cool. Even better.

[pulyaevskiy]

I checked in PHPStorm, if I declare something like this:

<?php
/**
 * @template TKey
 * @template TValue
 */ 
interface Traversable
{
}

It complains that declaration already exists (in the IDE's stubs obviously). So not sure if it's going to be useful to include this repo in projects (at least before IDE is updated to take these into account).

But I do agree it's useful for documentation purposes.

[mindplay-dk]

Yeah, maybe the recommendation should not be to include it in projects then, at least not yet.

Either way, I think it's useful to separate the type definitions from the spec, as this is more likely to change or have errors compared with the spec itself? A flaw in the ambient types should not result in a new PSR, right?

[mindplay-dk]

Splitting features into separate PSRs doesn't make much sense to me.

I mean, if you don't feel like documenting generic type relationships with php-doc, that's your choice, you're stilling complying with the PSR - it doesn't mandate how much you have to document, you're free to not document generic type relationships, or document generic parameters as mixed, etc. just as you'd likely do today.

I think having one spec makes sense, so that every change is a change to the spec in whole - with individual side specs we increase the risk of creating PSRs that are incompatible or conflicting with the next/previous version of a related PSR.

[jacobsantos]

@mindplay-dk Sorry, that was off-topic, so I removed it. That is up to you (and the others controlling the process) if you want the types to be a separate PSR.

[pulyaevskiy]

A flaw in the ambient types should not result in a new PSR, right?

@mindplay-dk , yes, agree with that. So all these overloaded interfaces will be out of scope of this doc if I understand correctly?

Just so that I understand - what would remain in the "Collections" section? Just reference to the repo?

Would be nice to hear from @mvriel as well.

[pulyaevskiy]

Also, I contacted author of this RFC: https://wiki.php.net/rfc/generics and asked if he can put some more details on syntax at least. Got response that he'll try to update it soon. Would be nice to have.

[mindplay-dk]

So all these overloaded interfaces will be out of scope of this doc if I understand correctly?

To be clear, I don't think that they are part of the spec, per se - rather, the spec is what make the creation of the ambient definitions possible.

As such, I believe the ambient type definitions are more dependent on changes/additions to PHP itself - only their syntax is dependent on the spec.

Of course, the spec should point to the repository, though - the same way e.g. the HTTP spec points to the repository with the interface definitions. (although those are much more closely related.)

[mindplay-dk]

Also, I contacted author of this RFC

Well, it's one paragraph for now, so probably has years to go before it can be implemented - but it would be great if you could ask this guy to review what we have in the works and get his feedback, since clearly this is a subject he cares about?

[pulyaevskiy]

To be clear, I don't think that they are part of the spec, per se - rather, the spec is what make the creation of the ambient definitions possible.

Makes sense to me.

Well, it's one paragraph for now,

He targets it for 7.1 which maybe a couple years away, but main thing here is to get compatible syntax, I guess. I'll try to keep in touch with him, for sure.

[mvriel]

@pulyaevskiy currently life is a bit in the way; I will try to respond meaningfully as soon as I can

[mindplay-dk]

Closing this, as it has no relevance to the PSRs we're now pursuing.