Generics

[mvriel]

Currently it is not possible to define the type of a key and a value contained in a collection object, Generics intends to solve this.

Example:

• Define a collection with integer values: @param Collection<int> $byte
• Define a collection with integer keys and string values: @param Collection<int,string> $byte
• Define a collection with integer or string values: @param Collection<int|string> $byte

[philsturgeon]

Looks good to me.

[mvriel]

I have just added a section on Generics and refactored the ABNF for types (if only because that was a weird mix between EBNF and ABNF). A proof read is welcome!

(Disclaimer: this was written at 11 o'clock without proper proofreading myself, please be gentle ;))

[cretz]

Nice; some thoughts...

Firstly, I would really like to capture the generic as a general type bound. If I have MyObject<int> I should be able to have /** @generic int T */ on MyObject where I can use T throughout the class. This makes it more general and not specific to Traversable/ArrayAccess implementations

Secondly, I'd like the same type of type parameters to be local to, e.g.

/**
 * @generic string[]|string T
 * @param T $input
 * @return T
 */

An alternative to @generic can be a colon-suffixed type-variables if we don't want to waste another line w/ a new tag, e.g.:

/**
 * @param T:string[]|string $input
 * @return T
 */

I know this is asking a lot and can lead to other requests for variance in the type bounds and what not, but it at least doesn't limit this to PHP collections and arrays. Just some food for thought.

[mvriel]

@cretz Interesting thought and I see some overlap with inline element definitions (#7).

My main concern is: how will this improve documentation?
The intention of this PSR is purely to add documentation to PHP and not any behavior.

I can imagine that being able to provide a named alias to a "Type" is something that may be desirable but, I guess, that would more be an additional consideration for the inline element definitions.

[cretz]

The only way it really improves documentation is it narrows the type for the caller. So instead of seeing mixed everywhere or a bunch of |'s, you can almost define types and/or type aliases in documentation. I do believe it's a tad overcomplicated for what PHPDoc does, but I fear restricting the ability to provide type parameters only to arrays and traversable/arrayaccess.

[kdambekalns]

That generics-inspired syntax is what we use in TYPO3 Flow for documentation and also type validation / property mapping. So a big +1 for having that "standardised" for documentation and hopefully even in a PSR. Yay!

[samdark]

It's not defined what collection is in PHP. Should a class implement ArrayAccess to be a collection?

[mindplay-dk]

My main concern is: how will this improve documentation?

It will improve documentation of libraries, which are documented for the purposes of other developers consuming those libraries - generics are a way to describe type-relationships, which is something that exists conceptually in almost any language. Being able to describe them "mathematically", in a standardized expression form, is much better than having to describe them in english, in a comment, where no documentation generator (or IDE or annotation library) can derive any meaning from them.

This is no different from any other type of annotation that describes any other specific aspect of code - technically, you could have an annotation standard that consisted of @ followed by plain text and nothing else; but the documentation you could generate from that would not be very useful, so we use more specific types of expressions to make sure the documentation is human readable and machine parsable.

Generics have become a common way to describe type relationships, that many developers are comfortable with from other languages already.

How does the ability to concisely describe type-relationships not improve documentation? :-)

The intention of this PSR is purely to add documentation to PHP and not any behavior.

Annotations should never add behavior to anything - they are purely metadata.

But you have to look at annotations as more than just documentation these days - your PSR defines something that is already wide spread and heavily used in the community, and it's not safe to ignore the fact that people rely on annotations for IDE support (inspections, automated refactoring, etc.) and consuming metadata at run-time has also become commonplace with mainstream frameworks like Symfony adopting the idea in recent years.

[mindplay-dk]

In addition: if this PSR becomes approved, there is a very high likelihood that other documentation generators, IDE developers, annotation library developers (such as myself) and developers of any tool that relies on annotations, will adopt and implement the standard.

PSR is the closest thing PHP has to a community standard.

I see it as absolutely crucial that a community standard consider the needs of the entire community, to the extend that doing so is not a hindrance.

PSR standards after all are coding standards, and as such need to cater to more than just documentation.

[mindplay-dk]

Here's a "real world" example of a repository pattern, using a (suggested) new @template annotation (as per Google Closure Compiler annotations) to define the type arguments:

interface IEntity
{ ... }

/**
 * @template TEntity : IEntity the type of Entity hosted by this Repository
 */
class Repository
{
    /**
     * @param string $type
     */
    public function __construct($type)
    { ... }

    /**
     * @param int $id
     * @return TEntity
     */
    public function get($id)
    { ... }

    /**
     * @param int $id
     * @return TEntity[]
     */
    public function find($criteria)
    { ... }

    /**
     * @param TEntity $entity
     */
    public function delete($entity)
    { ... }
}

And a brief example of usage:

/** @type Repository<User> */
$users = new Repository(User::class);

// implicit @type User by inference:
$user = $users->get(123);

// implicit type-check in IDEs:
$users->delete($user);

It's really not complicated - you're just defining your own type-aliases with @template similar to built-in aliases like self or static, but actually much simpler to resolve if you had to; which, for documentation purposes, you probably don't even need to.

I used a fictive syntax in my example, in which I assumed you would optionally be able to specify what kind of type is required as type-argument - this should expect a regular type-declaration as per @type etc., but should be optional.

We would need a syntax for providing default type-arguments as well, in order to support both array<TElement> and array<TIndex, TElement> - or, alternatively, as e.g. TypeScript has, a non-generic syntax for index and element types.

If for any reason you're unwilling to include full support for "real" generics, alternatively, I would suggest you abandon the proposed generic-style syntax, in favor of some other syntax to designate index and element types specifically. (Other languages and annotation styles have syntax specifically to deal with index and element types - it does not typically look like generics, as this is fundamentally a different thing than generics entirely.)

[mindplay-dk]

PS: if you think having type-checks for type-arguments is too complicated and "mathematical", I wouldn't hold that against you - I would be quite happy with a simple @template [type_alias] {comment} syntax, as this is much simpler and covers most uses just fine.

Ideally we should be able to constrain the template-type, e.g. @template [type_alias] {: type} {comment}, and from your perspective this doesn't need to be anything other than documentation, though (in the example above) it wouldn't suck to be able to click through from the template-type to IEntity in the documentation.

But I would be happy either way - as long as we don't pollute or confuse the basic concept of generics.

[mindplay-dk]

PPS: if you wanted to support (either or only) index and element declarations, I would suggest building on the existing type-syntax which already has a syntax for indicating collections... You can actually have ambiguous types with the current proposed syntax, e.g. array<Foo> is identical to Foo[] - since array<Foo> implies generics, I would suggest building on the existing annotation-syntax for arrays ([] token) instead, e.g. Foo[] which already works rather than array<Foo>, and e.g. Foo[string] which builds on the existing array syntax, rather than array<string,Foo> which implies generics. For custom collection-types, e.g. a class Collection as per your examples, you could declare those as Collection|Foo[string] which is much closer to what you would do for collection-types presently, without the ability to specify the index-type, e.g. Collection|Foo[].

As said, I would love to also have generics as part of the specification - but the key issue for me right now, is to make sure we don't end up with a standard that looks like generics but doesn't work like it.

I apologize for the bombardment of messages, but this is really important to me. I'll shut up now :-)

[mvriel]

Hi @mindplay-dk, your comments have given me something to ponder and research. Hence I have not responded yet. I am still in the process of research and will get back to this asap

[mindplay-dk]

Would you like me to propose syntax for @template, update the ABNF, and submit a PR?